SPFx project managed with Rush: a Very Quick Start

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.

Initial configuration

Setting up a 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 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? and how?).
• repository.url used by rush change to determine which files are affected by a PR diff

rush.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, (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.

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

[
  {
    "definitionName": "individualVersion",
    "policyName": "sPFx"
  }
]

rush.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

rush list

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

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.

There's rush add command to add dependencies to a project.