npm package: @richardpickett/docker-npm-builder
Description: Builds npm packages using docker for a consistent toolchain and simple configuration
Author: Richard@RichardPickett.com
Latest version: 1.32.8

# 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 `export`s, 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:

```bash
$ 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 `export`ed 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.