├── .node-version ├── .prettierignore ├── packages ├── x-cli │ ├── bin │ │ └── cli.js │ ├── tsconfig.json │ ├── src │ │ ├── main.ts │ │ ├── cli.ts │ │ └── main.spec.ts │ └── package.json └── x-core │ ├── src │ └── index.ts │ ├── tsconfig.json │ └── package.json ├── renovate.json ├── .prettierrc.yml ├── tsconfig.build.json ├── tsconfig.json ├── package.json ├── .github └── workflows │ └── build.yml ├── LICENSE.txt ├── .gitignore └── README.md /.node-version: -------------------------------------------------------------------------------- 1 | 20 2 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | lib/ 2 | *.tsbuildinfo 3 | -------------------------------------------------------------------------------- /packages/x-cli/bin/cli.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | require("../lib/cli"); 4 | -------------------------------------------------------------------------------- /packages/x-core/src/index.ts: -------------------------------------------------------------------------------- 1 | export function awesomeFn() { 2 | return "Hello"; 3 | } 4 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": ["config:base"], 3 | "constraints": { 4 | "npm": "^7.0.0" 5 | } 6 | } 7 | -------------------------------------------------------------------------------- /.prettierrc.yml: -------------------------------------------------------------------------------- 1 | trailingComma: all 2 | tabWidth: 2 3 | semi: true 4 | singleQuote: false 5 | bracketSpacing: true 6 | printWidth: 120 7 | arrowParens: avoid 8 | -------------------------------------------------------------------------------- /packages/x-core/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "../../tsconfig.json", 3 | "compilerOptions": { 4 | "rootDir": "src", 5 | "outDir": "lib" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /packages/x-cli/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "../../tsconfig.json", 3 | "compilerOptions": { 4 | "rootDir": "src", 5 | "outDir": "lib" 6 | }, 7 | "references": [{ "path": "../x-core" }] 8 | } 9 | -------------------------------------------------------------------------------- /packages/x-cli/src/main.ts: -------------------------------------------------------------------------------- 1 | import { awesomeFn } from "@quramy/x-core"; 2 | 3 | export async function main() { 4 | // dependencies across child packages 5 | const out = await awesomeFn(); 6 | return out; 7 | } 8 | -------------------------------------------------------------------------------- /packages/x-cli/src/cli.ts: -------------------------------------------------------------------------------- 1 | import { main } from "./main"; 2 | 3 | main() 4 | .then(out => { 5 | console.log(out); 6 | process.exit(0); 7 | }) 8 | .catch(err => { 9 | console.error(err); 10 | process.exit(1); 11 | }); 12 | -------------------------------------------------------------------------------- /packages/x-cli/src/main.spec.ts: -------------------------------------------------------------------------------- 1 | import assert from "assert"; 2 | import { main } from "./main"; 3 | 4 | async function test() { 5 | const actual = await main(); 6 | assert(actual != null); 7 | console.log("ok"); 8 | } 9 | 10 | test(); 11 | -------------------------------------------------------------------------------- /tsconfig.build.json: -------------------------------------------------------------------------------- 1 | { 2 | // The root project has no sources of its own. By setting `files` to an empty 3 | // list, TS won't automatically include all sources below root (the default). 4 | "files": [], 5 | // Building this project will build all of the following: 6 | "references": [{ "path": "packages/x-core" }, { "path": "packages/x-cli" }] 7 | } 8 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "incremental": true, 4 | "target": "es2019", 5 | "module": "commonjs", 6 | "declaration": true, 7 | "sourceMap": true, 8 | "composite": true, 9 | "strict": true, 10 | "moduleResolution": "node", 11 | "esModuleInterop": true, 12 | "skipLibCheck": true, 13 | "forceConsistentCasingInFileNames": true 14 | } 15 | } 16 | -------------------------------------------------------------------------------- /packages/x-core/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@quramy/x-core", 3 | "version": "1.0.0", 4 | "description": "Awesome functions", 5 | "main": "lib/index.js", 6 | "scripts": { 7 | "compile": "tsc" 8 | }, 9 | "types": "lib/index.d.ts", 10 | "keywords": [], 11 | "author": "quramy", 12 | "license": "MIT", 13 | "dependencies": { 14 | "@types/node": "^20.0.0" 15 | }, 16 | "devDependencies": { 17 | "typescript": "5.6.2" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /packages/x-cli/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@quramy/x-cli", 3 | "version": "1.0.0", 4 | "description": "Awesome CLI", 5 | "main": "lib/main.js", 6 | "bin": { 7 | "x-cli": "bin/cli.js" 8 | }, 9 | "scripts": { 10 | "compile": "tsc", 11 | "test": "node lib/main.spec.js" 12 | }, 13 | "keywords": [], 14 | "author": "quramy", 15 | "license": "MIT", 16 | "dependencies": { 17 | "@quramy/x-core": "^1.0.0", 18 | "@types/node": "^20.0.0", 19 | "minimist": "^1.2.5" 20 | }, 21 | "devDependencies": { 22 | "typescript": "5.6.2" 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "npm-ts-workspaces-example", 3 | "private": true, 4 | "scripts": { 5 | "clean": "rimraf -g \"packages/**/lib\" \"packages/**/*.tsbuildinfo\"", 6 | "compile": "tsc -b tsconfig.build.json", 7 | "prettier": "prettier \"*.{js,json,yml,md}\" \"packages/**/*\"", 8 | "format": "npm run prettier -- --write", 9 | "format:check": "npm run prettier -- --check", 10 | "lint": "npm run format:check", 11 | "test": "npm run --ws test --if-present", 12 | "prepare": "npm run compile" 13 | }, 14 | "devDependencies": { 15 | "prettier": "3.4.2", 16 | "rimraf": "6.0.1", 17 | "typescript": "5.6.2" 18 | }, 19 | "workspaces": [ 20 | "packages/*" 21 | ] 22 | } 23 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | 3 | on: 4 | pull_request: 5 | push: 6 | branches: 7 | - main 8 | 9 | jobs: 10 | build: 11 | runs-on: ubuntu-latest 12 | 13 | strategy: 14 | matrix: 15 | node-version: [18.x] 16 | 17 | steps: 18 | - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4 19 | - name: Use Node.js ${{ matrix.node-version }} 20 | uses: actions/setup-node@v4 21 | with: 22 | node-version: ${{ matrix.node-version }} 23 | cache: npm 24 | - name: npm install, build, and test 25 | run: | 26 | npm install 27 | npm run compile 28 | npm run lint 29 | npm run test 30 | env: 31 | CI: true 32 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright 2020 Quramy 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | # Created by https://www.gitignore.io/api/node 3 | 4 | ### Node ### 5 | # Logs 6 | logs 7 | *.log 8 | npm-debug.log* 9 | yarn-debug.log* 10 | yarn-error.log* 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | 24 | # nyc test coverage 25 | .nyc_output 26 | 27 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 28 | .grunt 29 | 30 | # Bower dependency directory (https://bower.io/) 31 | bower_components 32 | 33 | # node-waf configuration 34 | .lock-wscript 35 | 36 | # Compiled binary addons (http://nodejs.org/api/addons.html) 37 | build/Release 38 | 39 | # Dependency directories 40 | node_modules/ 41 | jspm_packages/ 42 | 43 | # Typescript v1 declaration files 44 | typings/ 45 | 46 | # Optional npm cache directory 47 | .npm 48 | 49 | # Optional eslint cache 50 | .eslintcache 51 | 52 | # Optional REPL history 53 | .node_repl_history 54 | 55 | # Output of 'npm pack' 56 | *.tgz 57 | 58 | # Yarn Integrity file 59 | .yarn-integrity 60 | 61 | # dotenv environment variables file 62 | .env 63 | 64 | 65 | # End of https://www.gitignore.io/api/node 66 | 67 | lib/ 68 | 69 | *.tsbuildinfo 70 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # How to build TypeScript mono-repo project 2 | 3 | [![github actions](https://github.com/Quramy/npm-ts-workspaces-example/workflows/build/badge.svg)](https://github.com/Quramy/npm-ts-workspaces-example/actions) 4 | 5 | This repository explains how to create monorepos project using npm and TypeScript. 6 | 7 | ## ToC 8 | 9 | - [Tools](#tools) 10 | - [Directory Structure](#directory-structure) 11 | - [Workspaces](#workspaces) 12 | - [Dependencies across packages](#dependencies-across-packages) 13 | - [Resolve dependencies as TypeScript projects](#resolve-dependencies-as-typescript-projects) 14 | - [How to execute scripts for each package ?](#how-to-execute-scripts-for-each-package-) 15 | - [License](#license) 16 | 17 | ## Tools 18 | 19 | - npm cli(v7 or later) 20 | - TypeScript 21 | 22 | ## Directory Structure 23 | 24 | Put each package under the `packages` directory. 25 | 26 | ``` 27 | . 28 | ├── node_modules/ 29 | ├── README.md 30 | ├── package-lock.json 31 | ├── package.json 32 | ├── packages 33 | │   ├── x-cli 34 | │   │   ├── lib 35 | │   │   │   ├── cli.d.ts 36 | │   │   │   ├── cli.js 37 | │   │   │   ├── cli.js.map 38 | │   │   │   ├── main.d.ts 39 | │   │   │   ├── main.js 40 | │   │   │   └── main.js.map 41 | │   │   ├── package.json 42 | │   │   ├── src 43 | │   │   │   ├── cli.ts 44 | │   │   │   └── main.ts 45 | │   │   └── tsconfig.json 46 | │   └── x-core 47 | │   ├── lib 48 | │   │   ├── index.d.ts 49 | │   │   ├── index.js 50 | │   │   └── index.js.map 51 | │   ├── package.json 52 | │   ├── src 53 | │   │   └── index.ts 54 | │   └── tsconfig.json 55 | ├── tsconfig.build.json 56 | └── tsconfig.json 57 | ``` 58 | 59 | ## Workspaces 60 | 61 | Using [npm workspaces feature](https://github.com/npm/rfcs/blob/latest/implemented/0026-workspaces.md), configure the following files: 62 | 63 | Open `package.json` and append the `workspaces` key. 64 | 65 | ```js 66 | /* package.json */ 67 | 68 | { 69 | "name": "npm-ts-workspaces-example", 70 | "private": true, 71 | ... 72 | "workspaces": ["packages/*"] 73 | } 74 | ``` 75 | 76 | Exec `npm install`. After successful running, all dependencies included from each package are downloaded under the repository root `node_modules` directory. 77 | 78 | ## Dependencies across packages 79 | 80 | In this example, the `x-cli` package depends on another package, `x-core`. So to execute (or test) `x-cli`, `x-core` packages should be installed. 81 | But in development the `x-core` package is not published so you can't install it. 82 | 83 | For example, `packages/x-cli/src/main.spec.ts` is a test code for `main.ts`, which depends on `packages/x-core/src/index.ts` . 84 | 85 | ```ts 86 | /* packages/x-cli/src/main.ts.*/ 87 | 88 | import { awesomeFn } from "@quramy/x-core"; 89 | 90 | export async function main() { 91 | // dependencies across child packages 92 | const out = await awesomeFn(); 93 | return out; 94 | } 95 | ``` 96 | 97 | So we need to link `x-core` package from `x-cli` to execute the `x-cli` 's test. 98 | 99 | Workspaces feature of npm also solves this problem. `npm i` creates sim-links of each package into the top-level `node_modules` dir. 100 | 101 | ## Resolve dependencies as TypeScript projects 102 | 103 | As mentioned above, npm cli resolves dependencies across packages. It's enough for "runtime". However considering TypeScript sources, in other words "static", it's not. 104 | 105 | We need to tell "x-cli package depends on x-core" to TypeScript compiler. TypeScript provides much useful feature to do this, ["Project References"](https://www.typescriptlang.org/docs/handbook/project-references.html). 106 | 107 | First, you add `composite: true` to project-root tsconfig.json to use project references feature. 108 | 109 | ```js 110 | /* tsconfig.json */ 111 | 112 | { 113 | "compilerOptions": { 114 | ... 115 | "composite": true 116 | } 117 | } 118 | ``` 119 | 120 | Second, configure each package's tsconfig and configure dependencies across packages. 121 | 122 | ```js 123 | /* packages/x-cli/tsconfig.json */ 124 | 125 | { 126 | "extends": "../../tsconfig.json", 127 | "compilerOptions": { 128 | "rootDir": "src", 129 | "outDir": "lib" 130 | }, 131 | "references": [{ "path": "../x-core" }] 132 | } 133 | ``` 134 | 135 | And create a project which depends on all packages: 136 | 137 | ```js 138 | /* tsconfig.build.json */ 139 | 140 | { 141 | "files": [], 142 | "references": [{ "path": "packages/x-core" }, { "path": "packages/x-cli" }] 143 | } 144 | ``` 145 | 146 | Let's exec `npx tsc --build tsconfig.build.json`. The .ts files included in all packages are build at once! 147 | 148 | ## How to execute scripts for each package ? 149 | 150 | We can use [`--workspaces` option](https://docs.npmjs.com/cli/v10/using-npm/workspaces#running-commands-in-the-context-of-workspaces). 151 | 152 | ```sh 153 | # Excecute npm test in all workspaces 154 | $ npm test --workspaces 155 | ``` 156 | 157 | ```sh 158 | # Bump up packages in all workspaces 159 | $ npm version --workspaces patch 160 | 161 | # Publish packages in all workspaces 162 | $ npm publish --workspaces 163 | ``` 164 | 165 | ## License 166 | 167 | The MIT License (MIT) 168 | --------------------------------------------------------------------------------