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
- 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
- VS Code uses
- 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.
Clone the repository, and cd
into it:
git clone git@github.com: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 .
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
- 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 ‘git@github.com:kim/my-app.git’cd
into the new directory, egcd my-app
.DS_Store
node_modules
node_modules.zip
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
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 <0@0bdx.com> (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
notrequire()
(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
withbuild-helpers.
:
sed -ix 's/§0/build-helpers./g' *e.json
- Insert the author’s name, email and domain:
sed -ix 's/author": "/author": "0bdx <0@0bdx.com> (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