@messageflow/build

Quick build with Gulp

---

Better build process with Gulp for general Node.js projects written in TypeScript. To embrace native ES modules in Node.js, @messageflow/build allows you to build with compiling to any other module system such as CommonJS and also allows you to output files in the format of .mjs. See the Using .mjs in Node.js section to learn how to use .mjs in Node.js.

Table of contents

• Pre-requisites
• Setup
  • Install
  • Usage
    • gulpfile.js
    • How to build for FOSS
    • Using .mjs in Node.js
• API Reference
  • DEFAULT_FOSS_CLEAN_GLOBS
  • DEFAULT_IGNORE_GLOBS
  • DEFAULT_BABEL_CONFIG
  • Default FOSS configuration
  • BuilderParams
  • builder([options])
• License

Pre-requisites

• Node.js >= 8.9.0
• NPM >= 5.5.1 (NPM comes with Node.js so there is no need to install separately.)

Setup

Install

# Install via NPM as one of the `devDependencies`
$ npm install --save-dev @messageflow/build

Usage

gulpfile.js

const gulp = require('gulp');
const { builder } = require('@messageflow/build');

const build = builder();
/** `cleanGlobs` can be helpful when the destination directory is not the `dist` directory. */
// const build = builder({
//   dist: '.',
//   cleanGlobs: [
//     './*.js',
//     './*.d.ts',
//     '!./gulpfile.js',
//     '!./json.d.ts',
//   ],
// });

gulp.task('clean', build.clean);
gulp.task('lint', build.lint);
gulp.task('copy', build.copy);
gulp.task('ts', build.ts);
gulp.task('watch', build.watch);
gulp.task('default', build.default); // or gulp.task('default', build.all);

How to build for FOSS

// gulpfile.js

const gulp = require('gulp');
const builder = require('@messageflow/build').builder({ foss: true });
/** This is equivalent to */
// const builder = require('@messageflow/build').builder({
//   dist: '.',
//   cleanGlobs: [
//     './*@(mj|j)s',
//     './*.d.ts',
//     '!./gulpfile.js',
//     '!./json.d.ts',
//   ],
// })

gulp.task('lint', builder.lint);
gulp.task('default', builder.all);

Using .mjs in Node.js

Node.js will import the correct dependencies based on the file extension you use. .mjs file will only import .mjs files.

// main.mjs
import otherMod from './other-mod'; // This will import 'other-mod.mjs` but not 'other-mod.js'

// main.js
const otherMod = require('./other-mod'); // This will import 'other-mod.js' but not 'other-mod.mjs'

API Reference

DEFAULT_FOSS_CLEAN_GLOBS

[
  './*.@(mj|j)s',
  './*.d.ts',
  '!./gulpfile.js',
  '!./json.d.ts',
]

DEFAULT_IGNORE_GLOBS

[
  '!**/demo*/**/*.ts*',
  '!**/test*/**/*.ts*',
]

DEFAULT_BABEL_CONFIG

{
  presets: [
    ['@babel/preset-env', {
      targets: { node: 'current' },
      spec: true,
      modules: false,
      useBuiltIns: 'usage',
      shippedProposals: true,
    }],
    ['minify', {
      replace: false,
      mangle: { keepFnName: true },
      removeConsole: false,
      removeDebugger: true,
    }],
  ],
}

Default FOSS configuration

When foss is set to true, the following flags will be set to use its default values:

1. dist - .
2. cleanGlobs - DEFAULT_FOSS_CLEAN_GLOBS

BuilderParams

• src <?string> Optional source directory. Defaults to src.
• dist <?string> Optional destination directory. Defaults to dist.
• cleanGlobs <?string|string[]> Optional glob patterns to clean files/ directories up before every build process initiates. This is required only when the destination directory is not the dist directory. Defaults to the value of dist if unspecified.
• copyGlobs <?string|string[]> Optional glob patterns to copy files/ directories to destination build directory. Defaults to ['<SRC>/**/*.*', '!<SRC>/**/*.ts*', '<SRC>/**/*.d.ts'].
• ignoreGlobs <?string|string[]> Optional glob patterns to ignore files/ directories. Defaults to DEFAULT_IGNORE_GLOBS. This only works when isProd is set to true.
• isProd <?boolean> Optional production flage. Set to true if the build process is meant for production. Defaults to process.env.NODE_ENV === 'production'.
• rootPath <?string> Optional path to current working directory. Defaults to ..
• babelConfig <?Object> Optional configuration for Babel. This is only needed when isProd is set to true. Defaults to DEFAULT_BABEL_CONFIG.
• tsConfig <?string> Optional path to tsconfig.json. Defaults to ./tsconfig.json.
• tslintConfig <?string> Optional path to tslint.json. Defaults to ./tslint.json. This defaults to ./tslint.prod.json when isProd is set to true.
• esModules <?boolean> Optional ES modules flag to run compilation with native ES Modules. Defaults to true.
• mjs <?boolean> Optional flag to run compilation with native ES modules and output files in the format of .mjs. Defaults to false. Native ES modules will be used and will ignore any value set by esModules if this is set to true
• foss <?boolean> Optional flag to run compilation for FOSS. Defaults to false. See Default FOSS configuration to see what is being used under the hood.

---

builder([options])

• options <?BuilderParams> Optional configuration for the build process.

• returns: <Object> An object of build tasks to be assigned as Gulp task, e.g. gulp.task('<TASK_NAME>', <GULP_TASK_FUNCTION>). It comprises of a list of tasks fo a common build process with Gulp for most of the projects:

  1. clean - Always remove old files from previous build.
  2. lint - Always lint all .ts files with given tslint.json.
  3. ts - Compile all .ts files with given tsconfig.json.
  4. copy - Copy all asset files such as images, json, md, etc.
  5. watch - Run the build process by watching for flle changes.
  6. default - Default build process that comprises all the above.
  7. all - Another default build process to compile and output in both .js and .mjs. See the How to build for FOSS section to learn how to use @messageflow/build to build your open source Node.js package using the { foss: true } shorthand.

License

MIT License © Rong Sen Ng