@0bdx/build-helpers

@0bdx/build-helpers

Helpful utilities for speeding up the ‘build’ part of a zero-build developer experience.

∅  Version: 0.0.4
∅  NPM: https://www.npmjs.com/package/@0bdx/build-helpers
∅  Repo: https://github.com/0bdx/build-helpers
∅  Homepage: https://0bdx.com/build-helpers

@TODO add an overview

Contributing

Set up your development machine

• Check your Git version:
  git --version # should be 'git version 2.20.1' or greater
• Check your Node version:
  node --version # should be 'v14.0.0' or greater
• Check your global TypeScript version:
  tsc --version # should be 'Version 4.9.4' or greater
  There is no actual TypeScript code in this project, but TypeScript can infer types from the JavaScript code and JSDoc comments.
  • VS Code uses tsserver to highlight errors in src/ JavaScript files
  • tsc is needed to generate the build-helpers.d.ts type declaration

Set up VS Code

• Check your VS Code version:
  code --version # should be '1.74.3' or greater
• Install and enable the jeremyljackson.vs-docblock extension.
• Install and enable the dnamsons.kimbie-dark-plus theme.

Set up the repo locally

Clone the repository, and cd into it:
git clone [e-mail]:0bdx/build-helpers.git && cd build-helpers

Install the two dev-dependencies:
npm i
@types/node 18.11.19, 1 package, 3.6 MB for 126 items.
Rollup 3.14.0, 2 packages, 2.5 MB for 31 items.

Open build-helpers in VS Code:
code .

Handy dev commands

Run all tests on the in-development source code:
npm test

Build build-helpers.js and build-helpers.d.ts:
npm run build:prod
npm run build:types

Run all tests on the built build-helpers.js file:
npm run preflight:test

Check that build-helpers.js uses all types correctly:
npm run preflight:types @TODO fix this

Or run all the build and preflight steps in one line, eg before committing:
npm run build && npm run preflight

Display what will be published:
npm publish --dry-run

Publish to npmjs.com/package/@0bdx/build-helpers:
npm publish

How to create a repo like this, from scratch

1. Create the initial repo

• At GitHub, click the ‘+’ icon, and ‘New repository’
• Name it, describe it, tick ‘Add a README file’, choose MIT license
• Click ‘Create repository’
• Click the ‘Code’ button, ‘Local’ tab, ‘SSH’, and the copy icon
• In your Terminal, cd to wherever you work
• git clone and paste something like ‘[e-mail]:kim/my-app.git’
• cd into the new directory, eg cd my-app

2. Add the .gitignore file

.DS_Store
node_modules
node_modules.zip

3. Add placeholders for the type declarations and main files

In stage 4. below, npm init will use the presence of these files to populate the "types" and "main" fields of package.json.

touch build-helpers.d.ts build-helpers.js

4. Add the initial package.json file

npm init --yes
sed -ix 's/: "1.0.0",/: "0.0.1",/' *e.json
sed -ix 's/keywords": \[/keywords": [ "build", "rollup" /' *e.json
sed -ix 's/: "ISC",/: "MIT",/' *e.json
A=(§{1..3},\\n·);sed -ix "s/\"main/${A[*]}·\"main/;s/·/ /g" *e.json
A=(§{a..f},\\n···);sed -ix "s/\"test/${A[*]}·\"test/;s/·/ /g" *e.json
sed -ix 's/§1/"type": "module"/' *e.json
sed -ix 's/§2/"files": [ "§0d.ts", "§0js" ]/' *e.json
sed -ix 's/§3/"engines": { "node": ">= 14.0.0" }/' *e.json
sed -ix 's/§a/"§Z:§A": "rollup -c"/' *e.json` 
sed -ix 's/§b/"§Z:§B": "tsc §0js §_"/' *e.json` 
sed -ix 's/§_/--allowJs --declaration --emitDeclarationOnly/' *e.json` 
sed -ix 's/§c/"§Z": "for s in {§A,§B};do npm run §Z:$s;done"/' *e.json
sed -ix 's/§A/prod/g;s/§B/types/g;s/§Z/build/g;' *e.json` 
sed -ix 's/§d/"§Z:§D": "echo \"🧬 test.js\" && node test.js"/' *e.json` 
sed -ix 's/§e/"§Z:§E": "tsc §0js §_"/' *e.json` 
sed -ix 's/§_/--allowJs --checkJs --noEmit/' *e.json` 
sed -ix 's/§f/"§Z": "for s in {§D,§E};do npm run §Z:$s;done"/' *e.json
sed -ix 's/§D/test/g;s/§E/types/g;s/§Z/preflight/g;' *e.json` 
sed -ix 's|Error: no test specified|🧪 src/test.js|' *e.json
sed -ix 's|exit 1|node src/test.js|' *e.json
sed -ix 's/§0/build-helpers./g' *e.json
sed -ix 's/author": "/author": "0bdx <[e-mail]> (0bdx.com)/' *e.json
rm package.jsonx
npm install @types/node -D
npm install rollup -D

• Create a default package.json file:
  npm init --yes
• Change the version to 0.0.1:
  sed -ix 's/: "1.0.0",/: "0.0.1",/' *e.json
• Add keywords, for better npmjs.org searchability:
  sed -ix 's/keywords": \[/keywords": [ "build", "rollup" /' *e.json
• Change the license to MIT:
  sed -ix 's/: "ISC",/: "MIT",/' *e.json
• Insert three top-level placeholder properties before "main", and then
  insert six placeholder "script" properties before "test":
  A=(§{1..3},\\n·);sed -ix "s/\"main/${A[*]}·\"main/;s/·/ /g" *e.json
A=(§{a..f},\\n···);sed -ix "s/\"test/${A[*]}·\"test/;s/·/ /g" *e.json
• Tell Node to use import not require() (avoids needing .mjs):
  sed -ix 's/§1/"type": "module"/' *e.json
• Tell NPM which files to include as part of the published package:
  sed -ix 's/§2/"files": [ "§0d.ts", "§0js" ]/' *e.json
• Specify the minimum supported Node.js version:
  sed -ix 's/§3/"engines": { "node": ">= 14.0.0" }/' *e.json
• The first script generates the main file, build-helpers.js, and then
  the second script generates the type declarations, build-helpers.d.ts.
  The third script is a shortcut to run both "build:..." scripts:
  sed -ix 's/§a/"§Z:§A": "rollup -c"/' *e.json
sed -ix 's/§b/"§Z:§B": "tsc §0js §_"/' *e.json
sed -ix 's/§_/--allowJs --declaration --emitDeclarationOnly/' *e.json
sed -ix 's/§c/"§Z": "for s in {§A,§B};do npm run §Z:$s;done"/' *e.json
sed -ix 's/§A/prod/g;s/§B/types/g;s/§Z/build/g;' *e.json
• The fourth script runs unit tests on the main file, build-helpers.js,
  and the fifth script checks it against the type declarations.
  The sixth script is a shortcut to run both "preflight:..." scripts:
  sed -ix 's/§d/"§Z:§D": "echo \"🧬 test.js\" && "/' *e.json
sed -ix 's/§e/"§Z:§E": "tsc §0js §_"/' *e.json
sed -ix 's/§_/--allowJs --checkJs --noEmit/' *e.json
sed -ix 's/§f/"§Z": "for s in {§D,§E};do npm run §Z:$s;done"/' *e.json
sed -ix 's/§D/test/g;s/§E/types/g;s/§Z/preflight/g;' *e.json
• The seventh script runs unit tests on the source code:
  sed -ix 's|Error: no test specified|🧪 src/test.js|' *e.json
sed -ix 's|exit 1|node src/test.js|' *e.json
• Replace §0 with build-helpers.:
  sed -ix 's/§0/build-helpers./g' *e.json
• Insert the author’s name, email and domain:
  sed -ix 's/author": "/author": "0bdx <[e-mail]> (0bdx.com)/' *e.json
• Delete the temporary package.jsonx file:
  rm package.jsonx
• Install two dev-dependencies:
  npm install @types/node -D 18.11.19, 1 package, 3.6 MB for 126 items
  npm install rollup -D 3.14.0, 2 packages, 2.5 MB for 31 items