Skip to content

Commit c3ed34a

Browse files
ctrlplusbctrlplusb
committed
docs: Updates readme
1 parent 1f7cc0a commit c3ed34a

File tree

1 file changed

+100
-41
lines changed

1 file changed

+100
-41
lines changed

‎readme.md‎

Lines changed: 100 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,25 @@ A CLI to manage monorepos with predictability and stability.
99
 
1010

1111
- [1. Introduction](#1-introduction)
12-
- [2. Goals](#2-goals)
12+
- [2. Motivation](#2-motivation)
1313
- [3. Prerequisites](#3-prerequisites)
1414
- [4. Install](#4-install)
15-
- [5. Guide](#5-guide)
16-
- [5.1. Installing your dependencies](#51-installing-your-dependencies)
17-
- [5.2. Linking packages](#52-linking-packages)
18-
- [5.3. Updating linked packages](#53-updating-linked-packages)
19-
- [5.4. Watching updates to linked packages](#54-watching-updates-to-linked-packages)
20-
- [5.5. Upgrading package dependencies](#55-upgrading-package-dependencies)
21-
- [6. CLI Reference](#6-cli-reference)
22-
- [6.1. `install`](#61-install)
23-
- [6.2. `link`](#62-link)
24-
- [6.3. `refresh`](#63-refresh)
25-
- [6.4. `watch`](#64-watch)
26-
- [6.5. `upgrade`](#65-upgrade)
27-
- [7. Appreciation](#7-appreciation)
28-
- [8. Further Reading / References](#8-further-reading--references)
15+
- [5. Requirements](#5-requirements)
16+
- [6. Guide](#6-guide)
17+
- [6.1. Installing your dependencies](#61-installing-your-dependencies)
18+
- [6.2. Linking packages](#62-linking-packages)
19+
- [6.3. Updating linked packages](#63-updating-linked-packages)
20+
- [6.4. Watching updates to linked packages](#64-watching-updates-to-linked-packages)
21+
- [6.5. Upgrading package dependencies](#65-upgrading-package-dependencies)
22+
- [7. CLI Reference](#7-cli-reference)
23+
- [7.1. `clean`](#71-clean)
24+
- [7.2. `install`](#72-install)
25+
- [7.3. `link`](#73-link)
26+
- [7.4. `refresh`](#74-refresh)
27+
- [7.5. `watch`](#75-watch)
28+
- [7.6. `upgrade`](#76-upgrade)
29+
- [8. Appreciation](#8-appreciation)
30+
- [9. Further Reading / References](#9-further-reading--references)
2931

3032
 
3133

@@ -60,28 +62,28 @@ We lean heavily into a "standard" npm experience and promote the capability for
6062

6163
---
6264

63-
## 2. Goals
65+
## 2. Motivation
6466

65-
- Leverage standard `npm` as far as possible.
66-
67-
At any time you should be able to stop using `monilla` and just run standard `npm` commands. Yes, you might have to execute a lot of `npm` commands depending on how many packages are in your project, but you'll be able to do so at the least.
68-
69-
- Treat each package as though it were an independent `npm` package.
70-
71-
We expect that each package within your monorepo is built almost as if it were independent. It's own package.json scripts, dependencies, etc. This enables richer workflows for packages being operated against in isolation. For example, cleaner publishing workflows for packages to an `npm` registry, or simple lifting and shifting of packages in or out of your monorepo.
67+
_Coming soon_
7268

7369
 
7470

7571
---
7672

7773
## 3. Prerequisites
7874

79-
**Node.js** version 16 or higher is required to use this CLI.
75+
**Node.js** version 18 or higher is required to use this CLI.
76+
77+
> **Note**
78+
>
79+
> There was a change in behaviour between npm versions in how linked package dependencies were installed. A flag (`--install-links`) was introduced to the npm CLI to address this issue.
80+
>
81+
> Node 18 by default ships with a version of npm which includes support for this flag. Therefore we are making it a requirement that you utilise Node 18.
8082
8183
We highly recommend installing [nvm](https://github.com/nvm-sh/nvm) on your machine. It enables you to manage multiple versions of Node.js seamlessly. Utilising `nvm` you can install the required version of Node.js via the following command;
8284

8385
```bash
84-
nvm install --default 16
86+
nvm install --default 18
8587
```
8688

8789
> **Note**
@@ -104,7 +106,56 @@ npm install monilla --save-dev
104106

105107
---
106108

107-
## 5. Guide
109+
## 5. Requirements
110+
111+
**Linked Packages `package.json` Design**
112+
113+
We expect that each package within your monorepo is built almost as if it were independent package, that _could_ be published to npm.
114+
115+
This means that you need to;
116+
117+
- add all the expected dependencies to your `package.json` to meet your package's needs;
118+
- define the `main` _or_ `exports` _or_ `module` fields to indicate the entries and available imports from your package;
119+
- define the `files` list, declaring which dirs/files should be exposed by your package;
120+
121+
For e.g.
122+
123+
```json
124+
{
125+
"name": "@my/stuff",
126+
"version": "0.0.0",
127+
"private": true,
128+
"type": "module",
129+
"exports": "./dist/index.js",
130+
"types": "./dist/index.d.ts",
131+
"files": ["dist"],
132+
"scripts": {
133+
"build": "tsup"
134+
},
135+
"dependencies": {
136+
"chalk": "^5.0.1"
137+
},
138+
"devDependencies": {
139+
"@types/node": "^16.11.41",
140+
"tsup": "^6.1.2",
141+
"typescript": "^4.7.4"
142+
}
143+
}
144+
```
145+
146+
> **Note**
147+
>
148+
> We declare our package as "private" with a version of "0.0.0". This is intentional as we never intend to actually publish our package to npm. It will only be used by other packages within the monorepo.
149+
150+
We will perform an "npm pack" of your linked packages, carrying across the expected files that would have been exposed if it were published to npm.
151+
152+
This enables us to produce an `npm install` behaviour for your linked packages that is essentially the same as a vanilla install should the package have been downloaded from the npm registry.
153+
154+
 
155+
156+
---
157+
158+
## 6. Guide
108159

109160
Imagine a monorepo with the following structure:
110161

@@ -139,7 +190,7 @@ Using this as a reference, we'll describe a few scenarios below.
139190
140191
 
141192

142-
### 5.1. Installing your dependencies
193+
### 6.1. Installing your dependencies
143194

144195
```bash
145196
npx monilla install
@@ -152,7 +203,7 @@ This performs two functions;
152203

153204
 
154205

155-
### 5.2. Linking packages
206+
### 6.2. Linking packages
156207

157208
Linking enables you to utilise one of your monorepo packages within another as though it were installed via the NPM registry.
158209

@@ -174,7 +225,7 @@ npx monilla link --from @my/components --to @my/mobile-app
174225
175226
 
176227

177-
### 5.3. Updating linked packages
228+
### 6.3. Updating linked packages
178229

179230
If you've performed updates to one of your linked packages, you can ensure that all dependants are using the latest version of them via the following command;
180231

@@ -188,7 +239,7 @@ npx monilla refresh
188239
189240
 
190241

191-
### 5.4. Watching updates to linked packages
242+
### 6.4. Watching updates to linked packages
192243

193244
Watching your linked packages results in automatic building and pushing of the updates;
194245

@@ -204,7 +255,7 @@ This command is especially useful when performing local development across your
204255
205256
 
206257

207-
### 5.5. Upgrading package dependencies
258+
### 6.5. Upgrading package dependencies
208259

209260
We support interactive upgrading of the dependencies for all the packages within your monorepo;
210261

@@ -222,50 +273,58 @@ You'll be asked which packages you'd like to update for each of the packages wit
222273

223274
---
224275

225-
## 6. CLI Reference
276+
## 7. CLI Reference
226277

227278
Work in progress. You can get help via the CLI `--help` flag;
228279

229280
```bash
230281
npx monilla --help
231282
```
232283

233-
### 6.1. `install`
284+
### 7.1. `clean`
285+
286+
```bash
287+
npx monilla clean
288+
```
289+
290+
Removes all `node_modules` folders and `package-lock.json` files from across the monorepo. Supports the good old "nuke and retry" strategy when in dire need.
291+
292+
### 7.2. `install`
234293

235294
```bash
236295
npx monilla install
237296
```
238297

239298
This performs two functions;
240299

241-
- Installs the required dependencies for each package within the monorepo, including the root.
242-
- Ensures that any linked packages within the monorepo are bound.
300+
- Installs the dependencies for every package, including the root.
301+
- Ensures that any linked packages are bound.
243302

244-
### 6.2. `link`
303+
### 7.3. `link`
245304

246305
```bash
247306
npx monilla link --from @my/components --to @my/mobile-app
248307
```
249308

250309
Link monorepo packages, declaring the `from` package as a dependency within the `to` package.
251310

252-
### 6.3. `refresh`
311+
### 7.4. `refresh`
253312

254313
```bash
255314
npx monilla refresh
256315
```
257316

258317
Ensures that packages are using the latest form of their internal packages dependencies that have been linked against them.
259318

260-
### 6.4. `watch`
319+
### 7.5. `watch`
261320

262321
```bash
263322
npx monilla watch
264323
```
265324

266325
Starts a "development" process that will watch your linked packages for any changes, and will automatically update consuming packages to use the updated versions.
267326

268-
### 6.5. `upgrade`
327+
### 7.6. `upgrade`
269328

270329
```bash
271330
npx monilla upgrade
@@ -277,7 +336,7 @@ Perform an interactive upgrade of the dependencies for all the packages within y
277336

278337
---
279338

280-
## 7. Appreciation
339+
## 8. Appreciation
281340

282341
A huge thank you goes to [@wclr](https://github.com/wclr) for the outstanding work on [Yalc](https://github.com/wclr/yalc). The Yalc workflow is the specific seed which enabled this idea to grow. 🌻
283342

@@ -287,7 +346,7 @@ An additional thank you is extended to [@raineorshine](https://github.com/raineo
287346

288347
---
289348

290-
## 8. Further Reading / References
349+
## 9. Further Reading / References
291350

292351
- [monorepo.tools - Everything you need to know about monorepos, and the tools to build them.](https://monorepo.tools/)
293352
- [An abbreviated history of JavaScript package managers](https://javascript.plainenglish.io/an-abbreviated-history-of-javascript-package-managers-f9797be7cf0e)

0 commit comments

Comments
 (0)