Build

Integrated HTTP/HTTPS server with a build platform, bundler, types/document/changelog generation and file watcher for NodeJS

Profiles

Key feature is configurable multiple build profiles each executing specified build steps
To configure a pipeline, edit build.json or .build.json

Default profiles:

  "profiles": {
    "production": ["clean", "compile", "typings", "typedoc", "lint", "changelog"],
    "development": ["serve", "watch", "compile"],
  },

Profile Steps

clean: clean locations specified in config.clean.locations
compile: compile and bundle sources for each target
compile treats errors as non-fatal so when running with watch it retries once error is corrected optional steps typings and typedoc are skipped on unsucessful compile
typings: generate .d.ts typings
runs for each target with config.build.<target>.typings set saves to config.build.<target>.typings location
all compiler parameters can also be overriden in config.typescript or in user's tsconfig.json
typedoc: generate typedoc documentation typings
runs for each target with config.build.<target>.typedoc set saves to config.build.<target>.typedoc location
uses same configuration parameters from config.typescript and user's tsconfig.json
generator parameters can also be overriden in user's typedoc.json
lint: lint locations specified in config.lint.locations
all lint parameters can also be overriden in config.lint or in user's .eslintrc.json
default configuration requires following peer dependencies:
eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-node
changelog: generate changelog from git commit log
requires that project is a valid git repository
serve: start http/https starts HTTP/HTTPS server using configuration from config.serve
server is native stream-based NodeJS solution without external dependencies
server uses compression when supported by client and provides all requires http headers
SSL: if user does not provide a valid ssl key/cert, default self-signed certificate will be used
self-signed certificate was generated using:
```
openssl req -x509 -newkey rsa:4096 -nodes -days 365 \
-keyout https.key -out https.crt \
-subj "/C=US/ST=Florida/L=Miami/O=@vladmandic"
```
watch: start file watcher for location specified in config.watch.locations
triggers compile step on create/modify/delete events

Configuration

most values have defaults to minimize required configuration
default configuration: https://github.com/vladmandic/build/blob/main/build.json
minimum required configuration is a single target config.build.target
inherits settings from user's configuration files if they exists
package.json, tsconfig.json, typedoc.json, .eslintrc.json
any configuration item can be specified
in a configuration file or as a configuration config object when using API
default configuration file is build.json
configuration Documentation:
https://vladmandic.github.io/build/typedoc/classes/Build.html#config

Usage

1. Using Developer API

TypeDoc API Documentation:
https://vladmandic.github.io/build/typedoc/classes/Build.html

Example:

const Build = require('@vladmandic/build').Build;

const config = {
  profiles: { // define profile 'production' with specific build steps
    "production": ["clean", "compile", "typings", "typedoc", "lint", "changelog"],
  },
  build: {
    targets: [ // minimum configuration requires at least one target
      { input: "src/test.ts", output: "dist/test.js", platform: "node", format: "cjs", typedoc: 'typedoc', typings: 'types' }
    ]
  }
}
const build = new Build(config);

console.log('Toolchain', build.toolchain);
console.log('Environment', build.environment);
console.log('Application', build.application);
console.log('Configuration', build.config);

const result = await build.run('production');
console.log('Build results:', result);

2. Using Command Line Interface

Example: npm run build --help

Usage: build [options]

Options:
  -c, --config <file>      specify config file
  -d, --debug              enable debug output
  -g, --generate           generate config files from templates
  -p, --profile <profile>  run build for specific profile
  -h, --help               display help for command

Example: npm run build --profile production

3. As a script within a project

Modify your package.json to include:

  "scripts": {
    "dev": "build -p development",
    "prod": "build -p production",
  }

And then start using npm run dev or npm run prod

Example Output

2021-09-11 10:08:52 INFO:  @vladmandic/build version 0.4.1
2021-09-11 10:08:52 INFO:  User: vlado Platform: linux Arch: x64 Node: v16.5.0
2021-09-11 10:08:52 STATE: Application log: /home/vlado/dev/build/build.log
2021-09-11 10:08:52 INFO:  Application: { name: '@vladmandic/build', version: '0.4.1' }
2021-09-11 10:08:52 INFO:  Environment: { profile: 'all', config: 'build.json', tsconfig: true, eslintrc: true, git: true }
2021-09-11 10:08:52 INFO:  Toolchain: { build: '0.4.1', esbuild: '0.12.26', typescript: '4.4.3', typedoc: '0.21.9', eslint: '7.32.0' }
2021-09-11 10:08:52 INFO:  Build: { profile: 'all', steps: ['clean','compile','typings','typedoc','lint','changelog','serve','watch' ] }
2021-09-11 10:08:52 STATE: Clean: { locations: [ 'types/*', 'typedoc/*', [length]: 2 ] }
2021-09-11 10:08:52 STATE: Compile: { name: 'build module', format: 'esm', platform: 'node', input: 'src/build.js', output: 'dist/build.esm.js', files: 13, inputBytes: 39928, outputBytes: 603792 }
2021-09-11 10:08:52 STATE: Compile: { name: 'build module', format: 'cjs', platform: 'node', input: 'src/build.js', output: 'dist/build.js', files: 13, inputBytes: 39928, outputBytes: 604935 }
2021-09-11 10:08:54 STATE: Typings: { input: 'src/build.js', output: 'types', files: 7 }
2021-09-11 10:08:58 STATE: TypeDoc: { input: 'src/build.js', output: 'typedoc', objects: 1, index: true }
2021-09-11 10:09:00 STATE: Lint: { locations: [ 'src/*.js', [length]: 1 ], files: 12, errors: 0, warnings: 0 }
2021-09-11 10:09:00 STATE: ChangeLog: { repository: 'https://github.com/vladmandic/build', branch: 'main', output: 'CHANGELOG.md' }
2021-09-11 10:09:00 STATE: WebServer: { ssl: false, port: 8000, root: '.' }
2021-09-11 10:09:00 STATE: WebServer: { ssl: true, port: 8001, root: '.', sslKey: 'cert/https.key', sslCrt: 'cert/https.crt' }
2021-09-11 10:09:00 STATE: Watch: { locations: [ 'src/**', 'src/**', [length]: 2 ] }
2021-09-11 10:09:00 INFO:  Listening...
...
2021-09-11 10:09:11 INFO:  Watch: { event: 'modify', input: 'src/build.js' }
2021-09-11 10:09:11 STATE: Compile: { name: 'build module', format: 'esm', platform: 'node', input: 'src/build.js', output: 'dist/build.esm.js', files: 13, inputBytes: 39928, outputBytes: 603792 }
2021-09-11 10:09:11 STATE: Compile: { name: 'build module', format: 'cjs', platform: 'node', input: 'src/build.js', output: 'dist/build.js', files: 13, inputBytes: 39928, outputBytes: 604935 }
2021-09-11 10:09:13 STATE: Typings: { input: 'src/build.js', output: 'types', files: 7 }
2021-09-11 10:09:14 STATE: TypeDoc: { input: 'src/build.js', output: 'typedoc', objects: 1, index: true }
...
2021-09-11 10:09:17 DATA:  HTTPS: { method: 'GET', ver: '2.0', status: 200, mime: 'text/html', size: 3560, url: '/typedoc/index.html', remote: '::ffff:192.168.0.200' }
2021-09-11 10:09:17 DATA:  HTTPS: { method: 'GET', ver: '2.0', status: 200, mime: 'text/css', size: 72023, url: '/typedoc/assets/css/main.css', remote: '::ffff:192.168.0.200' }
2021-09-11 10:09:17 DATA:  HTTPS: { method: 'GET', ver: '2.0', status: 200, mime: 'text/javascript', size: 155546, url: '/typedoc/assets/js/main.js', remote: '::ffff:192.168.0.200' }
...
2021-09-11 10:09:22 INFO:  Build exiting...

Rebuilding Build Module

Since Build is written in TypeScript, it needs to be bootstrapped into JavaScript bundle before it can be used
Simply run npm run bootstrap which will create dist/build.js

TypeDoc Documentation

https://vladmandic.github.io/build/typedoc/index.html

vladmandic / build