This is a monorepo for TypeScript-based NPM packages that are intended for reuse across multiple JustFix.nyc properties.
Individual packages can be found in the
They are published to NPM under the
Unless otherwise noted, all package source code uses es2019 syntax with es2015 module code generation.
The case for this is documented in Henry Zhu's Babel post On Consuming (and Publishing) ES2015+ Packages:
Why is compiling dependencies (as opposed to just compiling our own code) desirable in the first place?
- To have the freedom to make the tradeoffs of where code is able to run (vs. the library).
However, the downside of this approach is that using packages from this monorepo will almost certainly require the use of a transpiler and/or bundler. Fortunately, many tools and frameworks support the transpilation of dependencies, and some even do it by default.
Accomplishing this usually involves the following techniques:
Many transpilation/bundling tools are configured to automatically ignore everything in
node_modules. You'll probably need to tell them to ignore everything in
node_modulesexcept packages scoped under
Your tools may include a regular expression that tells them to only transpile/bundle TypeScript source files; you may need to tell them to also process JS files, or else the files in
@justfixnycpackages will be skipped over.
Below are techniques and examples for specific tools and frameworks.
Most Webpack configurations typically explicitly exclude anything in
exclude option. If you do this, you'll need to change this option to
exclude everything in
node_modules except anything scoped under
Additionally, if you use webpack-node-externals to exclude
being transpiled and bundled by Webpack for scripts that run in node, you'll want
to pass the
whitelist option to ensure that it still processes packages
from this monorepo.
See tenants2#889 for an example of these techniques in practice.
Using Rollup is relatively straightforward, since it uses es2015 modules natively.
You'll need to use the
rollup-plugin-node-resolve package so Rollup can
find your dependencies using the Node module resolution algorithm. See
justfix-ts#1 for an example.
Create React App (CRA)
CRA actually always transpiles
node_modules during development and production,
but its built-in Jest configuration currently does not. See who-owns-what#180 for
Gatsby also always transpiles
node_modules, at least for production. See
justfix-website#40 for an example.
This module ignores
node_modules by default, so you will need to
explicitly tell it not to; the easiest way to do this is by passing
ignore:  to its options, as described in the
Before working on any individual packages, go to the root of the repository and run the following to install all dependencies:
Then run the following to build all packages in the monorepo:
cd into a package of your choice.
Common commands that will work on all packages include:
yarn buildwill build the project.
yarn watchwill watch the project's files for changes and rebuild them when they change.
yarn testwill run the project's tests.
yarn test:watchwill run the project's tests, watching files for changes and re-running the test suite as needed.
Each package should also have a
CONTRIBUTING.md that provides further
guidance on developing it.
We use Prettier for all code formatting, and its formatting is enforced by our continous integration infrastructure.
Checking code formatting can be done with
yarn prettier:check, while automatically fixing all code formatting
issues can be done with
Before publishing, you should make sure you are logged into
npm as a
user with publish access to the
@justfixnyc organization/scope. Use
the following to check if you are logged in:
To publish all changed packages, go to the root of the repository and run:
yarn lerna publish