TS United: Node Edition
Building shared code and reinstalling it into all parts of a monorepo (backend, frontend, mobile)? Incrementing version and publishing shared code to NPM on every small change? Wasting time? Forget about it with TS United!
TS United helps one TypeScript project (folder containing a tsconfig.json
file) import TypeScript/JavaScript code from any other project, while checking each project's code and resolving imports in each project using that project's tsconfig.json.
Note: Node Edition is compatible with NodeJS runtimes (e.g. NodeJS, Mocha testing framework). If you're using another runtime, go to the list of editions and choose the edition you need.
Node Edition handles both running and building your code. Non-main projects are put into a special folder in main project's output folder. Also, TS United handles path aliases, set in tsconfig.json
and merges package.json
files of all projects, thus creating a ready deploy package.
Sounds great? Let's get started!
Adding TS United to your NodeJS project
Step one: Install the @ts-united/node package from NPM into your main (aka root) project. Root project is the project you'll run npm start
in when starting the whole app. For example, the backend part of your NodeJS app will be a root project.
Step two: Create a configuration file for TS United in your root project's base directory
Config file can be in either JS or JSON format and can have the following file names:
ts-united.config.{js,json}
ts-united.{js,json}
.tsunitedrc.{js,json}
.unitedrc.{js,json}
Example - ts-united.config.js
See the Config options section below for complete explanation of config options. It also shows an example config file.
Step three: Use TS United binaries for starting and building your code
In root project's package.json
file use tsu-node
binary to start your code and tsu-node-compile
binary to build your code.
Example:
{
// ...regular package.json
"scripts": {
"start": "tsu-node ./path/to/my/index.ts",
"build": "tsu-node-compile"
// ...some other scripts
}
}
See the Binaries section below for detailed documentation of the binaries
That's all! Now your project uses TS United! Import files from other projects and then run npm start
and npm run build
as usual.
Tip: Any project can import any other project, listed in config file. Related projects can import each other and can import root project (importing root project from related projects is not recommended).
Also you can see a complete example project on GitHub: https://github.com/R-Mielamud/TsUnited/tree/main/example/backend
Usage as a service
But sometimes you can't use tsu-node
binary. For example, in Mocha testing framework you need to use mocha
binary.
For such case TS United supports usage as a service. You can tell Mocha to import @ts-united/node/register
file before running the tests like this: mocha -r "@ts-united/node/register"
. @ts-united/node/register
, once imported, will inject TS United services into runtime and voila! Mocha will be able to import TypeScript files and use tsconfig path aliases!
TS United can be used as a service not only with Mocha. For example, with node
binary. NodeJS binary also can execute TypeScript files and use tsconfig aliases after importing @ts-united/node/register
like this: node -r "@ts-united/node/register" file.ts
And, you can import @ts-united/node/register
right in a source file like this:
// myfile.js
// Here I can't import TypeScript and use tsconfig path aliases
require("@ts-united/node/register"); // But after this line...
// ...I can!
// For example:
const server = require("~/server.ts");
server.start();
Complete example mocha project on GitHub: https://github.com/R-Mielamud/TsUnited/tree/main/example/mocha-tests
Config options
Option | Data type | Default value | Description |
---|---|---|---|
cwd |
string(path)? |
path.dirname(path_of_ts_united_config_file) |
CWD is a base directory for all other directories in config. It can be either absolute or relative. If it's relative, it'll be relative to path.dirname(path_of_ts_united_config_file) . |
unitedFolder |
string(filename)? |
.united_projects |
United folder is a folder in root project's output folder, that will contain built related projects. |
rootProject |
Project |
Root project's info (see Project schema below). | |
relatedProjects |
Array<Project>? |
[] |
Array containing related projects' info. If empty, no projects will be considered related. |
Project schema
Option | Data type | Default value | Description |
---|---|---|---|
name |
string, unique |
Any unique project name (id). | |
path |
string(path) |
The path tsconfig.json file is located in or any child path. Importing files that are outside all projects' paths is forbidden. The path can be absolute or relative to CWD. | |
loadAllFiles |
boolean? |
false |
By default project files are loaded only if they're referenced from other files. Because of this global types (.d.ts files) can be lost. With loadAllFiles: true TS United will preload all project files including global types according to files , include and exclude options of a project's tsconfig.json. |
Example folder structure and config:
|---myproject
|---shared
|--- ...
|---tsconfig.json
|---backend - the root project
|--- ...
|---ts-united.config.js
|---tsconfig.json
|---tsconfig.base.json
// /myproject/backend/ts-united.config.js
// path.dirname("/myproject/backend/ts-united.config.js") === "/myproject/backend"
module.exports = {
cwd: "../", // /myproject
unitedFolder: ".united_projects", // Set to default value
rootProject: {
name: "backend",
path: "./backend", // /myproject/backend
},
relatedProjects: [
{
name: "shared",
path: "./shared", // /myproject/shared
},
],
};
Binaries
-
tsu-node
Usage:
tsu-node ./path/to/my/index.ts
. Note, that the.ts
extension after file name is mandatory.The binary currently has no other command-line options.
-
tsu-node-compile
Usage:
tsu-node-compile [options]
Options:
-
--no-merged-package-json
aka--noMergedPackageJson
- If this flag is present, the mergedpackage.json
file will not be generated.
-