Skip to content

Latest commit

 

History

History
195 lines (147 loc) · 8.2 KB

README.md

File metadata and controls

195 lines (147 loc) · 8.2 KB
Raw

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


Usage

1. Using Developer API

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