Docker NPM Bilder

Build minified, tree-shook javascript and typscript libraries for multiple versions of node using gitlab pipeline and docker for a consistent toolchain build.

Put your javascript and typescript files in src with exports, this package will do the rest.

Publish your packages from your desktop, with or without docker, or within a gitlab pipeline using docker.

Implementation steps

1. npm i --save-dev @richardpickett/docker-npm-builder
2. Put all your source files in src and sub folders, with export for all the elements you want to be made available in your package. For any code necessary for your project you don't want made available, move it to src/internal.
3. Move your current build files for future reference (see the list of files DNB manages below)
4. dnb update to create the build files.
5. Edit dnb.json to your build settings.
6. dnb update to update the build files according to your settings.
7. dnb build to build locally and examine your build artifacts in the dist folder.
8. dnb publish to publish your library and make sure the published version matches your expectations.
9. Commit your changes and tag a new release. The tag will be the published version when the pipeline runs.

Usage

npm i --save-dev @richardpickett/docker-npm-builder

Once installed, you can call dnb to get a full list of it's functionality:

$ dnb
Usage: @richardpickett/docker-npm-builder [options] [command]

Builds npm packages using docker for a consistent toolchain and simple configuration

Options:
  -V, --version      output the version number
  -h, --help         display help for command

Commands:
  update             updates build files, installs if necessary
  build              builds the final dist package files
  publish [options]  publishes the package - caution, this will change your package.json and .npmignore files, it's only intended to be run in the pipeline
  help [command]     display help for command

Directory structure

• src - all source files are in this directory (or child directories)
• src/internal - all source files here are not or export exposed in your package, allowing you to have testing code and other internally used code that your package uses but isn't exported as part of your package.
• dist - this is the distribution folder, where all built artifacts will be

Files DNB manages

dnb will manage the following files for you:

1. .gitlab-ci.yml This file is the build pipeline for gitlab.
2. Dockerfile This file is is used to do the build of your library in a docker container so the toolchain is always consistent
3. .npmrc This file is used to set your npm token in the URL when npm publish is called.
4. tsconfig.json This file is used to configure tsc when the library types are built.
5. .eslint.json This file is used to configure eslint to show errors prior to your commit (also displays errors in vscode)
6. .ncurc.json This supports ncu (npm-check-updates) to keep your project up to date
7. package.json This file is first backed up, then modified when publishing your library. The modified version has all the necessary publishing entries. After publishing, the backup is restored and the published version is saved as package-published.json. Naturally, this only matters for when you publish locally, when you run this in the pipeline the backup and restore doesn't matter.
8. dnb.json This file has all the settings for your build. It's self-documenting with comments starting with "dnb" (which you can also use to comment out options you don't want without deleting them from the file).

If you already have any of these files in your repo, dnb will not interfere with it.

To correctly use dnb, you should delete these files and run dnb update to build them.

You can modify these files if you want, but once you do they won't be managed by dnb any more.

If you need to have dnb restore any of these files, just delete the file (except package.json, don't delete that file) and run dnb update, and it will recreate it.

update

Update both updates and installs the files needed to build your library:

dnb update

build

dnb build is typically run in the pipeline, but you can also run it locally to examine the built code.

publish

dnb publish is typically run in the pipeline, but you can also run it locally to publish your library.

To successfully publish, you need to pass in the version you are publishing (using the --publish-version flag) and have your npm token set as an environment variable.

dnb.json

All settings that start with "dnb" will be ignored. They are used as comments and as a way to disable an option while leaving it in the file.

Everytime you run dnb update, any option in dnb's internal configuration that isn't found in dnb.json (commented or uncommented), will be added back to dnb.json.

So don't delete entries, just "dnb" comment them out.

nodeBuildVersions

You can build your library for many different node versions, just select the ones you want it to build.

jsBuildOptions

• makeIndex creates a src/index.js file that imports and then exports all the exports for the rest of your src files.
• minify will do treeshaking and minimize your code to the smallest footprint.
• createTypes will build your type files for hinting in editors like vscode for those who use your package

packageFile

• autoPopulate - the entries listed will be auto-created in your package.json file when publishing
• keepEntries - the entries here will be copied from your package.json into the package.json published with your package.

publishOptions

• publishFiles - each file or directory listed here will be included in the package
• npmPublishTokenEnvironmentVariable - the variable name in your CICD pipeline (or local, if you're publishing locally) that holds your npm token
• publishAccess - either 'restricted' or 'public' (default)

buildContainerOptions

• additionalPackages - the docker container is node:XX, which is ubuntu-based. If your build requires addtional non-npm package tools installed by apt, you can list them here, they'll be installed when the container starts.
• nodeVersion - if supplied, this version will be used for the docker container, otherwise the highest node version in nodeBuildVersions will be used.

entryPoint - this is where (a) the index will be built if you use jsBuildOptions.makeIndex and (b) the jsBuild will begin finding your code dependencies when it builds the library

hashes - this is where dnb tracks if you're managing the build files or if it should update them.