SPFx project managed with Rush: a Very Quick Start
Tags: rush, node, monorepo, spfx
Published: 2022-03-02 10:42:39

It's a vey quick recap on how to start using Rush. 
I'm going to use this solution in the next posts of this series, so if you are interested, the source is [here] (https://github.com/kkazala/rush-conventionalcommits/tree/237c251c4ccf856b34805692a3764f5e1d485fc8).

## Initial configuration
[Setting up a new repo](https://rushjs.io/pages/maintainer/setup_new_repo/) is a very good article to start with.

`rush init` initializes rush in the repo, by provisioning config file templates. In case you already have some content in your repo (even if it's an empty folder structure), use `rush init rush --overwrite-existing`

### rush.json
Freshly created file has tonnes of comments and explanations. You may safely delete them, as you will find them [here](https://rushjs.io/pages/configs/rush_json/) anyway.

There are some important configuration settings in the **rush.json**: 
- the default **package manager** is pnpm
- `nodeSupportedVersionRange` defines supported versions for Node
- **commit messages** `gitPolicy.versionBumpCommitMessage` and `gitPolicy.changeLogUpdateCommitMessage` that rush will use after bumping versions or generating changelogs. 
- `gitPolicy.allowedEmailRegExps` for validating the commit email ([why?](https://rushjs.io/pages/maintainer/setup_policies/#allowedemailregexps-avoiding-private-e-mail-addresses) and [how?](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address)).
- `repository.url` used by rush change to determine which files are affected by a PR diff

#### rush.json
```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",
  "rushVersion": "5.61.4",
  "pnpmVersion": "6.7.1",
  "pnpmOptions": {
    "useWorkspaces": true
  },
  "nodeSupportedVersionRange": ">=14.15.0 <15.0.0",
  "gitPolicy": {
    "versionBumpCommitMessage": "Bump versions [skip ci]",
    "changeLogUpdateCommitMessage": "Update changelogs [skip ci]",
    "allowedEmailRegExps": [
      "[^@]+@users\\.noreply\\.github\\.com"
    ],
    "sampleEmail": "mrexample@users.noreply.github.com"
  },
  "repository": {
    "url": "https://github.com/xxx/xxx.git",
    //"defaultBranch": "master", //The default value is "master"
    "defaultRemote": "origin"
  },
  "projects": []
}
```

## Provisioning [SPFx] projects
When [adding projects to a repo](https://rushjs.io/pages/maintainer/add_to_repo/), (and assuming you start from the scratch), remember to run the **yo** generator with `--skip-install` to avoid the packages to be installed. Rush will take care of it once you are ready.

```powershell
yo @microsoft/sharepoint --skip-install --package-manager pnpm
```

### Add your projects to rush
Rush requires a list of project it should manage, and it does not support wildcards. 
Add your projects to **rush.json**:
- `projects.packageName` is the value of **name** parameter in your project's **package.json** file. 
- either set `projects.shouldPublish` to `true` to ensure the project will be published, or define
- `projects.versionPolicyName` pointing out to a policy you created in the **version-policies.json** file.

#### common\config\rush\version-policies.json
```json
[
  {
    "definitionName": "individualVersion",
    "policyName": "sPFx"
  }
]
```

#### rush.json
```json
{
  //...
  "projects": [
    {
      "packageName": "spfx-utils",
      "projectFolder": "spfx-libraries\\spfx-utils",
      "versionPolicyName": "sPFx"
    },
    {
      "packageName": "org-app",
      "projectFolder": "spfx-apps\\org-app",
      "versionPolicyName": "sPFx"
    }
  ]
}
```

You may run `rush list` to ensure you added your projects correctly
```powershell
rush list
```

Update the shrinkwrap file and install dependencies with `rush update` and build your projects with `rush build`: 
```powershell
rush update
rush build
```

## Installing project dependencies

Since Rush is managing the installation of dependency packages, you should avoid using package managers to install/link the dependencies:
> For example, `npm run` will work fine, but these commands will get confused by Rush's symlinks: `npm install`, `npm update`, `npm link`, `npm dedupe`, etc. (The same goes for other package managers: Avoid commands such as `pnpm install` or `yarn install`.) If you want to use those commands, first run rush unlink to delete the symlinks created by Rush. _Source: [Getting started as a developer / A couple caveats](https://rushjs.io/pages/developer/new_developer/#a-couple-caveats)._

There's `rush add` command to [add dependencies](https://rushjs.io/pages/commands/rush_add/) to a project.