Toba Build

TypeScript, JavaScript and SASS bundling configurations for typical Toba project types.

yarn add @toba/build --dev

or

npm install @toba/build --save-dev

Types

Invoke a build type with build<Type> as in buildElectron. The output is one or more standard Webpack configurations. Additional configurations are emitted for things like an Electron renderer or web Service Worker.

| | WebApp | WebSite | Electron | Tester | | -------------: | :----: | :-----: | :------: | :----: | | Mode | Dev | Dev | Dev | Prod | | SASS | ✅ | ✅ | ✅ | ✅ | | DevServer | ✅ | ✅ | | ✅ | | Configurations | 2 | 1 | 2 | 1 |

Usage

In webpack.config.ts:

import { buildTester } from '@toba/build';
export default buildTester();

Customizing

Since the method output is a standard Webpack configuration (or two), it may be customized in the usual way.

import { buildWebSite } from '@toba/build';
// web site build emits an app and service worker config
const [app, sw] = buildWebSite();
export default [
   {
      ...app,
      mode: 'production'
   },
   sw
];

Tree Shaking

To fully support Webpack tree shaking

• Imported modules must be ES6 with import and export rather than CommonJS.
• The package.json for the imported modules must include the property sideEffects set either to false or a list of files that do have side-effects (i.e. those that update globals or import CSS). See documentation for details.
• The TypeScript configuration used by ts-loader must have "allowJS": true in the compilerOptions so the loader incorporates any ES6 modules imported by .ts files.

TypeScript Configurations

These requirements mean that a project may need three distinct TypeScript configurations for these operations:

• Local execution of arbitrary .ts files with ts-node. This includes Webpack if using a TypeScript configuration such as webpack.config.ts.
• Webpack bundling TypeScript and its imports with ts-loader.
• Local unit testing of TypeScript files with ts-jest.

The configurations differ as follows:

| | ts-node | ts-loader | ts-jest | tsc | | ---------------------: | :------: | :-------------: | :------: | :----------: | | @toba/develop file | tsconfig | tsconfig.bundle | | tsconfig.lib | | module | CommonJS | esnext | CommonJS | esnext | | allowJS | true | true | false | false | | declaration | false | false | true | true |

This repository is an example of how the files might be arranged.

.
├── test
│   ├── src
│   │   ├── app.tsx
│   │   ├── [ ... ]
│   │   └── tsconfig.json
│   └── webpack.config.ts
├── .gitignore
├── LICENSE
├── package.json
├── README.md
└── tsconfig.json

The root tsconfig.json is the one used by ts-node to run Webpack if given a .ts configuration. It imports the default tsconfig from @toba/develop.

{
   "extends": "@toba/develop/tsconfig"
}

Jest uses the same root configuration with overrides defined by @toba/test for ts-jest. These overrides are needed to have TypeScript transpile ES6 imports to CommonJS as currently required by Jest.

{
   globals: {
      ...
      'ts-jest': {
         tsConfig: {
            allowJs: true,
            declaration: false
         }
      }
   }
}

The configuration within test/src imports a different @toba/build tsconfig that transpiles to ES6 to enable Webpack tree shaking.

{
   "extends": "@toba/build/ts/tsconfig.bundle",
   "include": ["./**/*.ts*"]
}

The tsconfig used to bundle the source files cannot be in the same folder, or a folder above, webpack.config.ts since ts-node will then try to use that configuration to run Webpack itself.

License

Copyright © 2019 Jason Abbott

This software is licensed under the MIT license. See the LICENSE file accompanying this software for terms of use.