@flowscripter/ts-template

ts-template

Template TypeScript library project.

Usage

1. Export and expand a zip of this repository.
2. Update links and references in README.md.
3. Update links and references in package.json.
4. Update links and references in gulpfile.js

Overview

Entry Points for Node and Browser

The build config in rollup.config.js produces two bundled entry points:

• node.js is intended for consumption in node and exposed via the main property in package.json.
• browser.js - is intended for consumption in a browser and exposed via the browser property in package.json.

This ensures that dependencies for node specific modules can be shimmed via rollup-plugin-node-builtins

Configuration

Explanation of project configuration files:

• .editorconfig - Configures EditorConfig compliant editors
• .eslintrc.js - TypeScript based ESLint configuration for the project derived from @flowscripter/eslint-config
• .gitignore - Specifies files for git to ignore
• .huskyrc.js - Provides git hooks using Husky to enforce semantic commit messages, linting and unit testing.
• .travis.yml - Defines the Travis build pipeline.
• commitlint.config.js - Configures commitlint to ensure commit messages can be used to drive automated Semantic Version releases.
• gulpfile.js - Invoked during the Travis build to run Sonarqube-scanner
• jest.config.js - Configures the unit testing framework Jest for TypeScript and coverage reports.
• package.js - Defines development cycle scripts and configures publication of ES2015 modules.
• release.config.js - Configuration for automated semantic version releasing using semantic-release
• renovate.json - Ensures automated dependency upgrade via Renovate using a config derived from @flowscripter/renovate-config
• rollup.config.js - Defines the TypeScript and ES2015 module build pipeline for Rollup
• tsconfig.json - TypeScript configuration for the project derived from @flowscripter/tsconfig
• typedoc.json - Configuration of TypeDoc API document generation

No Legacy JavaScript Support

All source and build output is in ES2015 module form.

Browsers or NodeJS versions need to support:

• https://github.com/tc39/proposal-dynamic-import
• https://tc39.github.io/ecmascript-asyncawait/
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions

Because of this the modules are configured so that:

• no transpiling is performed (apart from TypeScript to ES2015 JavaScript)
• package.json specifies:
  • "main": "dist/index.js
  • "type": "module"
  • "node": ">=12" so that the --experimental-modules flag can be used

Legacy Module Consumption

Legacy CommonJS format npm packages are supported for internal consumption by rollup-plugin-commonjs

External Dependencies

The module is generated without the debug dependency being included. This is achieved by:

• Specifying debug as a peer dependency in package.json
• Using the rollup-plugin-peer-deps-external plugin for Rollup.

This allows consuming applications to determine the best form of the dependency (e.g. NodeJS or browser version) and ensures it will only be added once to the final consuming application module.

Consuming Browser Application

For a consuming browser application, the library modules are consumed by providing replacements for NodeJS packages such as tty and util via the following Rollup plugins:

• rollup-plugin-node-builtins
• rollup-plugin-node-globals

Consuming NodeJS Application

For the consuming node application the library modules are consumed by declaring NodeJS packages such as tty and util as being externally available via the following Rollup config:

    external: [
        'tty',
        'util',
        'os'
    ]

API

API documentation

Development

Firstly:

npm install

then:

Build: npm run build

Watch: npm run watch

Test: npm test

Lint: npm run lint

Docs: npm run docs

License

MIT © Flowscripter