Repository files navigation

A system for managing JS/TS project dev tools

• @jcoreio/toolchain
  • Project goals
  • How-to
    • Creating a new project
    • Migrating an existing project to@jcoreio/toolchain
    • Installing@jcoreio/toolchain in an empty project
    • Upgrading@jcoreio/toolchain
    • Specifymain,module,exports, andbin and link package locally
    • Run build scripts
    • Exclude files from build output
    • Customize Git hooks
    • Disable ESM build
    • Disable source map output
    • Configure transpilation options
    • Run scripts before or after toolchain scripts
    • Disable scripts likebuild:smoke-test that are run byprepublish
    • Load chai plugins, customize mocha, etc.
    • Change mocha default specs
    • Define multiple test targets
    • Create dual CJS+ESM packages
  • Current limitations
    • Source maps

• Make it easy to keep standalone project dev dependencies and configurationup-to-date with the ecosystem
• Help us migrate all of our packages to ESM
• Make it easy to migrate a project to different systems (e.g. switching totypescript, or possibly in the future switching from mocha to another testrunner, or from CircleCI to GitHub actions)
• Make it easy to set up new standalone projects with all the dev tools andconfig we use to ensure quality and publish packages

In the parent dir of where you want to create your project directory, run:

pnpm --package=@jcoreio/toolchain dlx tc create

In your project dir, run:

pnpm --package=@jcoreio/toolchain dlx tc init

This does a bunch of things:

• Switches the project fromyarn ornpm topnpm
• Installs the applicable@jcore/toolchain packages
• Updates managed dev dependencies
• Adds config files for managed dev tools to the project
• Removes obsolete dev dependencies, config files, and things in package.jsonthat have been common in projects before@jcoreio/toolchain
• Formats files and autofixes eslint errors

I plan to maketc init work better for this use case, but right now theprocess is:

• Manually install the relevant@jcoreio/toolchain* packages
• Runtc migrate

• Runtc upgrade [version]

Since the build output is in thedist directory, you should have relative pathsto./dist in yourpackage.json:

{"main":"./dist/index.js","bin":"./dist/index.js"

That way, if you link your package root to another project locally, requiring/runningit will work.

tc build strips the./dist/ out of these paths in the outputdist/package.jsonthat actually gets published:

{"main":"./index.js","bin":"./index.js"

@jcoreio/toolchain adds atoolchain script to yourpackage.json (alsotcfor short):

$ pnpm toolchainUsage: toolchain <command> <arguments...>Available commands:  build               build dist directory  check               check format, types (if applicable), and lint  ci:browse           open CircleCI page in browser  clean               remove build output  coverage            run tests with code coverage  format              format files with prettier  init                install toolchains and migrate  install-git-hooks   install git hooks  lint                check files with eslint  lint:fix            autofix eslint errors  migrate             update dependencies and config, fix lint errors and format  open:coverage       open code coverage report  preinstall          run this script before installing toolchains in a project  prepublish          run check, coverage, and build  release             run automated release  test                run tests  upgrade             upgrade toolchains and migrate  version             print version of @jcoreio/toolchain

Configure thebuildIgnore option in yourtoolchain.config.cjs.buildIgnoretakes an array of glob patterns.** is supported, though brace expansion (e.g.*.{ts,tsx}) is not currently.

Example:

/* eslint-env node, es2018 */module.exports={cjsBabelEnv:{targets:{node:16}},outputEsm:false,buildIgnore:['src/**/__tests__'],}

Editgithooks.cjs. The default added bytoolchain init is:

/* eslint-env node, es2018 */module.exports={  ...require('@jcoreio/toolchain/githooks.cjs'),}

If you jump to@jcoreio/toolchain/githooks.cjs, you'll see:

module.exports={'pre-commit':'lint-staged',}

Each hook can be a shell command string or a (possibly async) function.

toolchain init/toolchain install-git-hooks essentially doesgit config core.hooksPath node_modules/@jcoreio/toolchain/githooks,which contains the scripts that invoke what's configured in yourgithooks.cjs.

SetoutputEsm: false intoolchain.config.cjs:

/* eslint-env node, es2018 */module.exports={cjsBabelEnv:{targets:{node:16}},outputEsm:false,}

AddsourceMaps: false totoolchain.config.cjs:

/* eslint-env node, es2018 */module.exports={sourceMaps:false,// ...}

This will also prevent the published package from includingsrc/**.

You can put options for@babel/preset-env incjsBabelEnv/esmBabelEnv intoolchain.config.cjs. The default options are:

/* eslint-env node, es2018 */module.exports={cjsBabelEnv:{targets:{node:16}},esmBabelEnv:{targets:{node:16}},}

Similar topackage.json scripts, you can addpre* andpost* scripts to yourtoolchain.config.cjs. However, the script can be a shell command string or anobject with props{ description: string, run: () => any }:

/* eslint-env node, es2018 */module.exports={cjsBabelEnv:{targets:{node:16}},esmBabelEnv:{targets:{node:16}},scripts:{pretest:'echo test',postbuild:{description:'runs after build',run:async()=>{// do something...},},},}

Intoolchain.config.cjs:

module.exports={  ...scripts:{'build:smoke-test':false,},}

Edit.mocharc.cjs. For example to add your own configuration script that loads chai plugins:

/* eslint-env node, es2018 */constbase=require('@jcoreio/toolchain-mocha/.mocharc.cjs')module.exports={  ...base,require:[...base.require,'test/configure.js'],}

Edit.mocharc.cjs. It's recommended to use thegetSpecs helper to avoid runningall specs by default if specific specs are passed on the command line. It's kind ofa bug that the Mocha CLI doesn't override the specs from config by default...

/* eslint-env node, es2018 */constbase=require('@jcoreio/toolchain-mocha/.mocharc.cjs')const{ getSpecs}=require('@jcoreio/toolchain-mocha')module.exports={  ...base,spec:getSpecs(['src/**/*.spec.js']),}

If you definetest:unit,test:integration etc scripts,@jcoreio/toolchain-mochawill automatically createcoverage:* scripts for them, and reconfigure thetestscript to run thetest:* scripts in sequence.

To be precise, it looks for scripts matching/^test\W/, so the namestest-unit andtest/foo etc. would also work.

Exampletoolchain.config.cjs:

/* eslint-env node, es2018 */constexeca=require('@jcoreio/toolchain/util/execa.cjs')module.exports={scripts:{'test:unit':{description:'run unit tests',run:(args=[])=>execa('mocha',['--config','.mocharc-unit.cjs', ...args]),},'pretest:integration':'docker compose up -d','test:integration':{description:'run integration tests',run:(args=[])=>execa('mocha',['--config','.mocharc-integration.cjs', ...args]),},},}

As long as you use@jcoreio/toolchain-esnext and don't haveoutputEsm: false inyourtoolchain.config.cjs,tc build will output both.cjs and.mjs files.

There will be atc test:esm command available that runs all your tests in ESM modeso you can make sure the ESM works.

Although ESM requires explicit file extensions for relative imports, you should stillomit them from your source and test code so that the build and test scripts work forboth CJS and ESM. The toolchain will use a babel plugin to add the necessary extensionsto your import paths when building and testing.

Right now the build doesn't output source maps or source files inthe published package, but we should probably make it do that.