Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[rush] Update subspace docs to reflect recent design changes #235

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[rush] Update subspace docs to reflect recent design changes #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a38fe1
Update subspace docs to reflect recent design changes
octogonz May 23, 2024
5874f9f
Fix table header alignment
octogonz May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions websites/rushjs.io/docs/pages/advanced/subspaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,30 +33,30 @@ Each subspace must have its name registered centrally in the [common/config/subs

The configuration for each subspace goes in a folder `common/config/subspaces/<subspace-name>/`, which may contain the following files:

| File | Purpose |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`common-versions.json`](../configs/common-versions_json.md) | Rush version overrides |
| [`pnpm-config.json`](../configs/pnpm-config_json.md) | PNPM version overrides |
| `pnpm-lock.yaml` | The PNPM lockfile |
| `repo-state.json` | A config file generated by Rush to prevent manual lockfile changes |
| [`.npmrc`](../configs/npmrc.md) | package manager configuration |
| `.pnpmfile-subspace.cjs` | Programmatic version overrides, following the same specification as [`.pnpmfile.cjs`](../configs/pnpmfile_cjs.md) but specific to the subspace |

Some files can be configured globally (applying across the entire monorepo) in addition to subspace level:

| Subspace config file | Global config file | Inheritance |
| ------------------------ | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `common-versions.json` | none | global file is forbidden with subspaces enabled |
| `pnpm-config.json` | `common/config/rush/pnpm-config.json` | **(STILL UNDER DEVELOPMENT)** subspace takes precedence, but certain fields are ignored |
| `pnpm-lock.yaml` | none | global file is forbidden with subspaces enabled |
| `repo-state.json` | none | global file is forbidden with subspaces enabled |
| `.npmrc` | `common/config/rush/.npmrc` | subspace overrides take precedence |
| `.pnpmfile-subspace.cjs` | `common/config/rush/.pnpmfile.cjs` | subspace overrides take precedence |

Note that the following config files are NOT moved:

- `common/config/.npmrc-publish`: This file is used for Rush NPM publishing, regardless of which subspaces the published projects belong to
- `common/config/.pnpmfile.cjs`: This file can apply versioning overrides that will affect all subspaces in the monorepo. To avoid confusing interactions across lockfiles, in most cases it is better to use `.pnpmfile-subspace.cjs` instead.
| Subspace file | Purpose |
| :----------------------------------------------------------- | :----------------------------------------------------------------- |
| [`common-versions.json`](../configs/common-versions_json.md) | Rush version overrides |
| [`pnpm-config.json`](../configs/pnpm-config_json.md) | PNPM version overrides |
| `pnpm-lock.yaml` | The PNPM lockfile |
| `repo-state.json` | A config file generated by Rush to prevent manual lockfile changes |
| [`.npmrc`](../configs/npmrc.md) | package manager configuration |
| [`.pnpmfile.cjs`](../configs/pnpmfile_cjs.md) | programmatic version overrides |

> Note that `common/config/.npmrc-publish` is not specified for subspaces. Package publishing is generally unrelated to package installation.

Some of these files can be defined at both levels, as summarized in the table below:

- Subspace config folder: `common/config/subspaces/<subspace-name>/`
- Monorepo config folder: `common/config/rush/`

| Subspace file | Monorepo file | Inheritance |
| :--------------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code style={{whiteSpace: 'nowrap'}}>common-versions.json</code> | none | _When using subspaces, the monorepo file is forbidden._ |
| `pnpm-config.json` | <code style={{whiteSpace: 'nowrap'}}>pnpm-config.json</code> | **Fallback**: The monorepo file is used only if the subspace's file is absent. |
| `pnpm-lock.yaml` | none | _When using subspaces, the monorepo file is forbidden._ |
| `repo-state.json` | none | _When using subspaces, the monorepo file is forbidden._ |
| `.npmrc` | `.npmrc` | **Merged**: The two files are merged, with subspace settings taking precedence. (This merging occurs when Rush generates the temporary `.npmrc` file in the working directory of the operation.) |
| `.pnpmfile.cjs` | none | _When using subspaces, the monorepo file is forbidden._ |

Without subspaces, Rush generates and installs the PNPM workspace in the `common/temp/` folder. With subspaces enabled, this will be performed separately in folders such as `common/temp/<subspace-name>/`.

Expand Down
2 changes: 1 addition & 1 deletion websites/rushjs.io/docs/pages/extensibility/creating_plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ with the same filename as the `"pluginName"` field from the manifest.
Here's a complete example of this naming pattern:

| Plugin component | Example naming pattern |
| ------------------------------------------------ | ------------------------------------------------------------- |
| :----------------------------------------------- | :------------------------------------------------------------ |
| NPM package name: | `@your-company/rush-policy-plugins` |
| `"pluginName"` in **rush-plugin-manifest.json**: | `"email-policy"` |
| end user config file: | **&lt;repo&gt;/common/config/rush-plugins/email-policy.json** |
Expand Down
20 changes: 10 additions & 10 deletions websites/rushjs.io/docs/pages/maintainer/using_rush_plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ The config filename will have the same as the `pluginName`, for example:
## First-party plugins

| NPM Package | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| :------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
| [@rushstack/rush-amazon-s3-build-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-amazon-s3-build-cache-plugin) | Cloud build cache provider for Amazon S3 |
| [@rushstack/rush-azure-storage-build-cache-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-azure-storage-build-cache-plugin) | Cloud build cache provider for Azure Storage |
| [@rushstack/rush-serve-plugin](https://github.com/microsoft/rushstack/tree/main/rush-plugins/rush-serve-plugin) | (Experimental) A Rush plugin that hooks into action execution and runs an express server to serve project outputs |
Expand All @@ -123,15 +123,15 @@ The config filename will have the same as the `pluginName`, for example:

Here's a gallery of some community contributed plugins.

| NPM Package | Description |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [rush-archive-project-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-archive-project-plugin) | Archive Rush projects that are no longer maintained |
| [rush-github-action-build-cache-plugin](https://github.com/gigara/rush-github-action-build-cache-plugin) | Save and restore the build cache in Github actions |
| [rush-init-project-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-init-project-plugin) | Initialize new Rush projects |
| [rush-lint-staged-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-lint-staged-plugin) | Integrate [lint-staged](https://www.npmjs.com/package/lint-staged) with a Rush monorepo |
| [rush-print-log-if-error-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-print-log-if-error-plugin) | Print a project's entire log file when an error occurs |
| [rush-sort-package-json](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-sort-package-json) | Sort the package.json file entries for Rush projects |
| [rush-upgrade-self-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-upgrade-self-plugin) | A helper for upgrading to the latest release of Rush |
| NPM Package | Description |
| :----------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| [rush-archive-project-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-archive-project-plugin) | Archive Rush projects that are no longer maintained |
| [rush-github-action-build-cache-plugin](https://github.com/gigara/rush-github-action-build-cache-plugin) | Save and restore the build cache in Github actions |
| [rush-init-project-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-init-project-plugin) | Initialize new Rush projects |
| [rush-lint-staged-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-lint-staged-plugin) | Integrate [lint-staged](https://www.npmjs.com/package/lint-staged) with a Rush monorepo |
| [rush-print-log-if-error-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-print-log-if-error-plugin) | Print a project's entire log file when an error occurs |
| [rush-sort-package-json](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-sort-package-json) | Sort the package.json file entries for Rush projects |
| [rush-upgrade-self-plugin](https://github.com/tiktok/rush-plugins/tree/main/rush-plugins/rush-upgrade-self-plugin) | A helper for upgrading to the latest release of Rush |

If you created an interesting plugin for Rush, let us know in a GitHub issue. Thanks!

Expand Down