Lerna-based monorepo containing the SFDX-Falcon Library, a framework for building beautiful, engaging plugins for the Salesforce CLI

There are two critical third-party tools used to manage this monorepo. Lerna and Yarn.

This project uses Yarn Workspaces to manage local inter-package dependencies. Yarn handles the addition, removal, installation, and upgrading of package dependencies within the workspace.

This project uses Lerna to coordinate the publishing of packages to the @sfdx-falcon scope at npmjs.com.

Because all SFDX-Falcon Library packages are published as part of the @sfdx-falcon scope, each package must add the following key to its package.json file.

"publishConfig": {
  "access": "public"
}

For more about per-package configuration options, see the Lerna Documentation.

List of the most common commands used to managed this monorepo. Unless otherwise indicated, all of these commands should be executed from the repository's root directory.

When run at the root of the workspace installs all dependencies of all packages within the workspace and links any cross-dependencies.

Adds a common dependency to the entire workspace. Dependencies added in this way are available to all packages in the workspace. Use the --dev flag to add as a dev dependency.

Adds a dependency to the package that the command is called inside of.

Displays the workspace-specific dependency tree of this project. Can detect if any of the intra-workspace dependencies are mismatched (ie. one package depends on a version of a workspace sibling other than what's currently expressed in that sibling's package.json file.)

Runs the specified Yarn command inside each package in the workspace. Any specified flags will be passed forward by each command invocation.

Builds all packages in the workspace by executing yarn run build against each package.

Equivalent to yarn workspaces run build.

Builds a single package, as specified by the package-name passed as an argument to the command.

Equivalent to yarn install.

Installs the dependencies for a single package, as specified by the package-name passed as an argument to the command.

After building a package, VS Code's built in TypeScript linter can show false errors. This can be fixed by restarting the TS Server from inside the affected .ts source file.

Prints the username that's currently logged into the NPM registry. This is the user who will be used during the lerna publish operation.

Modifies the version of all packages in the repository, using an exaxt version number wherever inter-package references are kept. This means that inter-package references would go from version 1.0.0 to 1.0.1, instead of to ^1.0.1.

Publishes all workspace packages to NPM. Determines the list of packages to publish by inspecting each package.json and checking if that package version is present in the registry. Any versions not present in the registry will be published. This is useful when a previous lerna publish failed to publish all packages to the registry.

When publishing, Lerna executes specific npm lifecycle scripts in the following order:

In root package:

• prepublish
• prepare
• prepublishOnly
• prepack

In each subpackage:

• prepublish
• prepare
• prepublishOnly
• prepack

In each subpackage:

• postpack

In root package:

• postpack

In each subpackage:

• publish
• postpublish

In root package:

• publish
• postpublish

There are three types of dependencies that will need to be updated over time.

• System-wide dependencies like NVM, Node.js, NPM, and Yarn
• Repository-wide dependencies that are defined in package.json at the project directory root
• Package-specific dependencies that are defined in the package.json found inside of each directory located in the packages directory

Update NVM using the command below. For the most up-to-date version number, see the "Installing and Updating" instrcutions at https://github.com/nvm-sh/nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Once NVM is installed/updated, use this command to get the latest stable version of Node.js:

nvm install stable

To upgrade NPM use the following command:

npm install -g npm@latest

Update Yarn by running this command (assuming you followed best practices and installed Yarn using Homebrew).

brew update yarn

Stuff

1. Make sure there a no unstaged files or outstanding commits in your project.
2. Open DEPENDENCIES.MD in VS Code and scroll down to the "External Dependencies" section.
3. Highlight the dependency and version number you want to update, including the left-most and right-most double quotes, eg. "@oclif/command": "1.7.0".
4. Perform a find/replace in all files using the desired version number.
5. Repeat steps 3 and 4 for each dependency being updated.
6. Inspect all unstaged files to ensure everything was updated as expected.
7. Run ./install at the root of the repository. This will update the dependencies in each workspace.
8. Run ./build at the root of the repository. This will rebuild all package using the new dependencies.