gem-hunter
Language: TypeScript
Zero-config CLI for TypeScript package development
a fork of the official tsdx.
$ npm install dts-cli -D # for npm users $ yarn add dts-cli -D # for yarn users $ pnpm install dts-cli -D # for pnpm users
Despite all the recent hype, setting up a new TypeScript (x React) library can be tough. Between Rollup, Jest, tsconfig, Yarn resolutions, ESLint, and getting VSCode to play nicely....there is just a whole lot of stuff to do (and things to screw up). DTS is a zero-config CLI that helps you develop, test, and publish modern TypeScript packages with ease--so you can focus on your awesome new library and not waste another afternoon on the configuration.
DTS comes with the "battery-pack included" and is part of a complete TypeScript breakfast:
invariant error codesdts testdts lint.babelrc.js, jest.config.js, .eslintrc.js, and dts.config.js/dts.config.tsnpx dts-cli create mylib
cd mylib
yarn startThat's it. You don't need to worry about setting up TypeScript or Rollup or Jest or other plumbing. Just start editing src/index.ts and go!
Below is a list of commands you will probably find useful:
Runs the project in development/watch mode. Your project will be rebuilt upon changes. DTS has a special logger for your convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab.
Your library will be rebuilt if you make edits.
Bundles the package to the dist folder.
The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).
Runs your tests using Jest.
Runs Eslint with Prettier on .ts and .tsx files.
If you want to customize eslint you can add an eslint block to your package.json, or you can run yarn lint --write-file and edit the generated .eslintrc.js file.
Bundles and packages to the dist folder.
Runs automatically when you run either npm publish or yarn publish. The prepare script will run the equivalent of npm run build or yarn build. It will also be run if your module is installed as a git dependency (ie: "mymodule": "github:myuser/mymodule#some-branch") so it can be depended on without checking the transpiled code into git.
By default the eslint VSCode extension won't work, since it can't find the configuration file needed in order to start the eslint server. Run npm run lint -- --write-file in order to write the config file in the correct location.
Aside from just bundling your module into different formats, DTS comes with some optimizations for your convenience. They yield objectively better code and smaller bundle sizes.
After DTS compiles your code with TypeScript, it processes your code with 3 Babel plugins:
babel-plugin-annotate-pure-calls: Injects for #__PURE annotations to enable treeshakingbabel-plugin-dev-expressions: A mirror of Facebook's dev-expression Babel plugin. It reduces or eliminates development checks from production codebabel-plugin-rename-import: Used to rewrite any lodash importsbabel-plugin-annotate-pure-calls + babel-plugin-dev-expressions work together to fully eliminate dead code (aka treeshake) development checks from your production code. Let's look at an example to see how it works.
Imagine our source code is just this:
// ./src/index.ts export const sum = (a: number, b: number) => { if (process.env.NODE_ENV !== 'production') { console.log('Helpful dev-only error message'); } return a + b; };
dts build will output an ES module file and 3 CommonJS files (dev, prod, and an entry file). If you want to specify a UMD build, you can do that as well. For brevity, let's examine the CommonJS output (comments added for emphasis):
// Entry File // ./dist/index.js 'use strict'; // This determines which build to use based on the `NODE_ENV` of your end user. if (process.env.NODE_ENV === 'production') { module.exports = require('./mylib.cjs.production.js'); } else { module.exports = require('./mylib.cjs.development.js'); }
// CommonJS Development Build // ./dist/mylib.cjs.development.js 'use strict'; const sum = (a, b) => { { console.log('Helpful dev-only error message'); } return a + b; }; exports.sum = sum; //# sourceMappingURL=mylib.cjs.development.js.map
// CommonJS Production Build // ./dist/mylib.cjs.production.js 'use strict'; exports.sum = (s, t) => s + t; //# sourceMappingURL=test-react-tsdx.cjs.production.js.map
AS you can see, DTS stripped out the development check from the production code. This allows you to safely add development-only behavior (like more useful error messages) without any production bundle size impact.
For ESM build, it's up to end-user to build environment specific build with NODE_ENV replace (done by Webpack 4 automatically).
DTS's rollup config removes getters and setters on objects so that property access has no side effects. Don't do it.
DTS will use babel-plugin-dev-expressions to make the following replacements before treeshaking.
Replaces
if (__DEV__) { console.log('foo'); }
with
if (process.env.NODE_ENV !== 'production') { console.log('foo'); }
IMPORTANT: To use __DEV__ in TypeScript, you need to add declare var __DEV__: boolean somewhere in your project's type path (e.g. ./types/index.d.ts).
// ./types/index.d.ts declare var __DEV__: boolean;
Note: The
dev-expressiontransform does not run whenNODE_ENVistest. As such, if you use__DEV__, you will need to define it as a global constant in your test environment.
Replaces
invariant(condition, 'error message here');
with
if (!condition) { if ('production' !== process.env.NODE_ENV) { invariant(false, 'error message here'); } else { invariant(false); } }
Note: DTS doesn't supply an invariant function for you, you need to import one yourself. We recommend https://github.com/alexreardon/tiny-invariant.
To extract and minify invariant error codes in production into a static codes.json file, specify the --extractErrors flag in command line. For more details see Error extraction docs.
Replaces
warning(condition, 'dev warning here');
with
if ('production' !== process.env.NODE_ENV) { warning(condition, 'dev warning here'); }
Note: DTS doesn't supply a warning function for you, you need to import one yourself. We recommend https://github.com/alexreardon/tiny-warning.
If you want to use a lodash function in your package, DTS will help you do it the right way so that your library does not get fat shamed on Twitter. However, before you continue, seriously consider rolling whatever function you are about to use on your own. Anyways, here is how to do it right.
First, install lodash and lodash-es as dependencies
yarn add lodash lodash-es
Now install @types/lodash to your development dependencies.
yarn add @types/lodash --dev
Import your lodash method however you want, DTS will optimize it like so.
// ./src/index.ts import kebabCase from 'lodash/kebabCase'; export const KebabLogger = (msg: string) => { console.log(kebabCase(msg)); };
For brevity let's look at the ES module output.
import o from"lodash-es/kebabCase";const e=e=>{console.log(o(e))};export{e as KebabLogger}; //# sourceMappingURL=test-react-tsdx.esm.production.js.map
DTS will rewrite your import kebabCase from 'lodash/kebabCase' to import o from 'lodash-es/kebabCase'. This allows your library to be treeshakable to end consumers while allowing to you to use @types/lodash for free.
Note: DTS will also transform destructured imports. For example,
import { kebabCase } from 'lodash'would have also been transformed to `import o from "lodash-es/kebabCase".
After running --extractErrors, you will have a ./errors/codes.json file with all your extracted invariant error codes. This process scans your production code and swaps out your invariant error message strings for a corresponding error code (just like React!). This extraction only works if your error checking/warning is done by a function called invariant.
Note: We don't provide this function for you, it is up to you how you want it to behave. For example, you can use either tiny-invariant or tiny-warning, but you must then import the module as a variable called invariant and it should have the same type signature.
⚠️Don't forget: you will need to host the decoder somewhere. Once you have a URL, look at ./errors/ErrorProd.js and replace the reactjs.org URL with yours.
Known issue: our
transformErrorMessagesbabel plugin currently doesn't have sourcemap support, so you will see "Sourcemap is likely to be incorrect" warnings. We would love your help on this.
TODO: Simple guide to host error codes to be completed
DTS can automatically rollup TypeScript type definitions into a single index.d.ts file via rollup-plugin-dts plugin. To enable types rollup, add --rollupTypes flag to your build and watch scripts.
"build": "dts build --rollupTypes", "start": "dts watch --rollupTypes",
rollup-plugin-dts was seen to cause issues when using json and less imports. Use with caution.
❗⚠️❗ Warning:
These modifications will override the default behavior and configuration of DTS. As such they can invalidate internal guarantees and assumptions. These types of changes can break internal behavior and can be very fragile against updates. Use with discretion!
DTS uses Rollup under the hood. The defaults are solid for most packages (Formik uses the defaults!). However, if you do wish to alter the rollup configuration, you can do so by creating a file called dts.config.js (or dts.config.ts) at the root of your project like so:
dts.config.js
// Not transpiled with TypeScript or Babel, so use plain Es6/Node.js! /** * @type {import('dts-cli').DtsConfig} */ module.exports = { // This function will run for each entry/format/env combination rollup(config, options) { return config; // always return a config. }, };
or
const defineConfig = require('dts-cli').defineConfig; module.exports = defineConfig({ // This function will run for each entry/format/env combination rollup: (config, options) => { return config; // always return a config. }, });
dts.config.ts
import { defineConfig } from 'dts-cli'; export default defineConfig({ // This function will run for each entry/format/env combination rollup: (config, options) => { return config; // always return a config. }, });
The options object contains the following:
export interface DtsOptions { // path to file input: string; // Name of package name: string; // JS target target: 'node' | 'browser'; // Module format format: 'cjs' | 'umd' | 'esm' | 'system'; // Environment env: 'development' | 'production'; // Path to tsconfig file tsconfig?: string; // Is error extraction running? extractErrors?: boolean; // Is minifying? minify?: boolean; // Is this the very first rollup config (and thus should one-off metadata be extracted)? writeMeta?: boolean; // Only transpile, do not type check (makes compilation faster) transpileOnly?: boolean; }
const postcss = require('rollup-plugin-postcss'); const autoprefixer = require('autoprefixer'); const cssnano = require('cssnano'); module.exports = { rollup(config, options) { config.plugins.push( postcss({ plugins: [ autoprefixer(), cssnano({ preset: 'default', }), ], inject: false, // only write out CSS for the first bundle (avoids pointless extra files): extract: !!options.writeMeta, }) ); return config; }, };
You can add your own .babelrc to the root of your project and DTS will merge it with its own Babel transforms (which are mostly for optimization), putting any new presets and plugins at the end of its list.
You can add your own jest.config.js to the root of your project and DTS will shallow merge it with its own Jest config.
You can add your own .eslintrc.js to the root of your project and DTS will deep merge it with its own ESLint config.
If you still need more customizations, we recommend using patch-package so you don't need to fork.
Keep in mind that these types of changes may be quite fragile against version updates.
DTS was originally ripped out of Formik's build tooling. DTS has several similarities to @developit/microbundle, but that is because Formik's Rollup configuration and Microbundle's internals had converged around similar plugins.
Some key differences include:
Description Rebuilds on any change Usage $ dts watch [options] Options -i, --entry Entry module --target Specify your target environment (default web) --name Specify name exposed in UMD builds --format Specify module format(s) (default cjs,esm) --tsconfig Specify your custom tsconfig path (default <root-folder>/tsconfig.json) --verbose Keep outdated console output in watch mode instead of clearing the screen --onFirstSuccess Run a command on the first successful build --onSuccess Run a command on a successful build --onFailure Run a command on a failed build --noClean Don't clean the dist folder --transpileOnly Skip type checking --rollupTypes Enable types rollup -h, --help Displays this message Examples $ dts watch --entry src/foo.tsx $ dts watch --target node $ dts watch --name Foo $ dts watch --format cjs,esm,umd $ dts watch --tsconfig ./tsconfig.foo.json $ dts watch --noClean $ dts watch --onFirstSuccess "echo The first successful build!" $ dts watch --onSuccess "echo Successful build!" $ dts watch --onFailure "echo The build failed!" $ dts watch --transpileOnly
Description Build your project once and exit Usage $ dts build [options] Options -i, --entry Entry module --target Specify your target environment (default web) --name Specify name exposed in UMD builds --format Specify module format(s) (default cjs,esm) --extractErrors Opt-in to extracting invariant error codes --tsconfig Specify your custom tsconfig path (default <root-folder>/tsconfig.json) --transpileOnly Skip type checking --rollupTypes Enable types rollup -h, --help Displays this message Examples $ dts build --entry src/foo.tsx $ dts build --target node $ dts build --name Foo $ dts build --format cjs,esm,umd $ dts build --extractErrors $ dts build --tsconfig ./tsconfig.foo.json $ dts build --transpileOnly
This runs Jest, forwarding all CLI flags to it. See https://jestjs.io for options. For example, if you would like to run in watch mode, you can run dts test --watch. So you could set up your package.json scripts like:
{
"scripts": {
"test": "dts test",
"test:watch": "dts test --watch",
"test:coverage": "dts test --coverage"
}
}Description Run eslint with Prettier Usage $ dts lint [options] Options --fix Fixes fixable errors and warnings --ignore-pattern Ignore a pattern --max-warnings Exits with non-zero error code if number of warnings exceed this number (default Infinity) --write-file Write the config file locally --report-file Write JSON report to file locally -h, --help Displays this message Examples $ dts lint src $ dts lint src --fix $ dts lint src test --ignore-pattern test/foo.ts $ dts lint src test --max-warnings 10 $ dts lint src --write-file $ dts lint src --report-file report.json
Description Create a new package with DTS Usage $ dts create <pkg> [options] Options --template Specify a template. Allowed choices: [basic, react, react-with-storybook] --husky Should husky be added to the generated project? (default true) -h, --help Displays this message Examples $ dts create mypackage $ dts create --template react mypackage $ dts create --husky mypackage $ dts create --no-husky mypackage $ dts create --husky false mypackage
You can run dts watch or dts build with multiple entry files, for example:
dts build \ --entry ./src/index.ts \ --entry ./src/foo.ts \ --entry ./src/subdir/index.ts \ --entry ./src/globdir/**/*.ts
When given multiple entries, dts-cli will output separate bundles for each file for each format, as well as their
declarations. Each file will be output to dist/ with the same name it has in the src/ directory. Entries in
subdirectories of src/ will be mapped to equivalently named subdirectories in dist/.
dts-cli will also expand any globs.
Please see the Contributing Guidelines.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
