typescript-tooling
v4.1.0
Published
This package helps keep TypeScript configuration and tooling synced up between seperate projects.
Downloads
61
Maintainers
Readme
Typescript Tooling // tst
A tool for creating and managing TypeScript projects with minimal configuration.
Features
TypeScript Tooling...
- 🛠️ Provides reasonable defaults for TypeScript, TSLint, Jest, and Nodemon
- 🐉 Uses a monorepo project structure with help from Lerna
- 📦 Bundles packages into ready-to-use JavaScript with Parcel
- 🏗️ Installs and saves the
devDependencies
you need to get up and running - 📝 Generates useful NPM scripts for your packages (
test
,test:watch
,dev
, andbuild
)
Getting Started
- Install and save
tst
... ignore warnings for missingpeerDependencies
npm install --save-dev typescript-tooling
- Run the
init
command...
npx tst init
- That's it! Here's a few scripts you can use with the example package...
npm run example:test
npm run example:dev
npm run example:build
Usage
npx tst help
How does TST work?
Running tst init
copies config files for various tools into a new .tst
directory in the root of your project. Under the hood, TST's CLI executes normal
commands which use those defaults. For example, tst test <package-name>
runs
the command npx jest packages/<package-name>
(which is also echo'ed out for
reference). This works since TST creates a jest.config.js
at the root of your
project which extends .tst/jest.config.js
. Settings and commands for other
tools operate the same way.
Nothing special is happening here! TST is just a bunch of config files and
shortcuts for writing long CLI commands which can always be executed directly
without using TST. Since no magic is involved, it's easy to stop using this
tool, just move config files from .tst
into the project root and add the
commands TST generates to the scripts
section of your package.json
. For
example...
// `package.json`
{
"scripts": {
"<package-name>:build": "tst build <package-name>"
}
}
...would become...
// `package.json`
{
"scripts": {
"<package-name>:build": "parcel build packages/<package-name>/src/index.ts --out-dir packages/<package-name>/dist --target node"
}
}
What's in the defaults?
If you're interested in seeing TST's defaults for TypeScript, Lerna, Nodemon,
and Jest, check out the
configs
folder; these files are copied into .tst
during a
tst init
.
Overriding TypeScript and TSLint Settings
TST creates or modifies <tsconfig|tslint>.json
in your project root to extend
the defaults in the .tst
directory...
// `<tsconfig|tslint>.json`
{
// TST adds this line if it isn't already set
"extends": "./.tst/<tsconfig|tslint>.json"
}
If you want to add or modify any settings, <tsconfig|tslint>.json
behaves just
as you'd expect, just modify the file...
// `tslint.json`
{
"extends": "./.tst/tslint.json",
"rules": {
// Allow `console.log`s across all packages
"no-console": false
}
}
It's easy to change settings for individual packages too. Imagine you want to
enable TypeScript's DOM library for a ui
package, you would just need to
create packages/ui/tsconfig.json
...
// `packages/ui/tsconfig.json`
{
// Extend the base configuration in your project root
"extends": "../../tsconfig.json",
// Change the setting we're interested in...
"compilerOptions": {
"lib": ["es2018", "dom"]
}
}
You can do the same thing for TSLint settings.
Overriding Jest Settings
TST exports a Jest configuration object from .tst/jest.config.js
which can be
modified and re-exported from your project's jest.config.js
...
// `jest.config.js`
module.exports = {
...require(".tst/jest.config.js"),
verbose: true,
bail: true
};
Working with a Monorepo
TypeScript Tooling is built to be used with
Lerna, which means it's easy to separate
code into multiple packages within the same project. Want to have independently
versioned/deployed types
, api
, and ui
packages? No problem!
Creating a New Package
First, make a new folder at
packages/<package-name>
Create
packages/<package-name>/package.json
and make sure itsname
field matches<package-name>
. For packages only used within your project, make sure to set"private": true
. Private packages only require thename
andprivate
fields.TST looks for
packages/<package-name>/src/index.ts
as the entry point. You can generate NPM scripts (test
,test:watch
,dev
, andbuild
) by running...
npm run tst:scripts
...or...
npx tst scripts
Delegating NPM Scripts to Packages
It's useful to keep all NPM scripts available from the project root so you
aren't constantly bouncing around with cd
. However, an overly complicated set
of NPM scripts in one gigantic package.json
isn't so great.
Luckily, Lerna allows you to execute NPM
Scripts from any package without leaving the project root. Let's say you want to
use Parcel to build deployable bundles for a ui
package; you could add the build script in packages/ui/package.json
...
// `packages/ui/package.json`
{
"scripts": {
"build": "parcel build public/index.html"
}
}
To enable npm run ui:build
from the root, we need to modify the NPM script in
the base package.json
...
// `package.json`
{
"scripts": {
// Use Lerna to execute the NPM script defined in `packages/ui/package.json`
"ui:build": "lerna run build --stream --scope ui"
}
}
It's important to note npx tst scripts
or npm run tst:scripts
won't override
scripts you've defined.
Notes
Test files are expected to live next to the code they cover are named
<module-name>.spec.<ts|tsx>
, i.e.Dog.ts
would be tested byDog.spec.ts
Run
npx tst init
after upgrading TST or cloning down a project with TST to ensure.tst
is up-to-dateYou can upgrade dependencies TST relies on, but know that there is no guarentee everything will still work together (normally you can bump major TypeScript versions without problems)
Disclaimer
This is my first usable open-source tool! Any help making TST more "professional" would be greatly appreciated. Please open an issue if you have any comments, suggestions, or feedback...
License
MIT