Workspace Maintenance: Overview

This document is a guide for engineers are maintaining a yarn workspace—after it has been set up.

Workspace Maintainer's overview

Am I a workspace maintainer?

You're on a Platform or VFS team
You're working on code within src/platform, or src/applictations for an app on the allow-list
The code you are working on, within src/applictations or src/platform, has been already set up as a Yarn Workspace [how to check this].

Release Tools has set up the existing child directories of src/platform as workspaces. As such, all Platform teams can be considered workspace maintainers by default.

If the answer to all three question is ‘yes’ then you're considered a workspace maintainer and the rest of this document applies to you. If only 1) and 2) apply you can create an issue and request that your application be set up as a Yarn Workspace.

How to check if you're working within a Yarn Workspace?

To confirm if you're in a properly setup yarn workspace check in the directory of your application for a package.json file with a version and a name field with a value beginning with:”@department-of-veterans-affairs/platform-" or @department-of-veterans-affairs/applications- depending on whether you're working inside a src/platform or src/applications directory. This is a good indication that your project has been set up as a workspace. You can fully confirm this by checking the workspaces.packages field in the vets-website root level package.json and looking for a blob leading to your project’s directory, e.g. "src/applications/vaos", this means your project has been set up as a workspace.

Additionally, the package may have been set up with a demo command in the scripts field. If this is the case, you can run yarn workspace <your-workspace-name> run demo where <your-workspace-name> is the full value in the name field in the package.json file. If the demo script successfully runs, you have confirmed you're working in a workspace. See details here.

As a final check, after running yarn install , your app should appear as a sim-linked package in the @department-of-veterans-affairs sub directory of the repository’s root node_modules folder. Example: ./node_modules/@department-of-veterans-affairs/applications-vaos.

Benefits of Yarn Workspaces

Yarn Workspaces allows for a siloed ‘environment’ in which dependencies can be managed and/or shared, and scripts, tests, and other commands executed. It also begins to set up your project for further encapsulation with the eventual option of publication to NPM.

Managing your workspace

I. `package.json` in your project directory

As a workspace maintainer you can work with the following workspace related fields.

dependencies excepting peerDependencies, all your project’s production dependencies go here. When yarn install is run, workspaces compares the packages listed in this field, hoisting packages which are shared (common to multiple projects) to the root level of the repository and placing those that are unique to your project inside your project's node_modules.
devDependencies Similar to dependencies but used only for development. Note yarn workspaces will install these in locally in node_modules/.bin and sim link them to node_modules/.bin at the root level. In other words, all dev_dependencies are automatically managed and shared by the repo.
peerDependencies Use only “*” as version value. Keep in mind that peerDependencies are not hoisted/installed by workspaces, so use this only when referring to a dependency or package that you're 100% certain is already present and has been installed at the root level.
scripts see scrips instructions.

As a workspace maintainer you should not alter with the following workspace related fields.

name this field identifies your workspace and altering it will cause many breaking issues.
version this field is related to publishing to NPM; a functionality which at the time of writing is not available to our set up.
private should be set to: true. Do not alter this field.

II. `nohoist` field in the repo's root level `package.json`

Other than checking or managing items that belong specifically to your app in the nohoist array, workspace maintainers should have no need to alter the repo's root level package.json

The nohoist array is found in the root directory’s package.json file’s inside the workspaces field. Dependencies listed here will not be hoisted to the root level node_modules folder and thus won't be shared by other applications.

If you're installing a dependency which you think might be unique to your project, it's advisable (though not mandatory) to list it in the nohoist. Another good use of nohoist is if you need to use a dependency version other than the one shared/installed at the root directory.

Do not list something in nohoist that is listed as a peerDependency in your app.

The blob pattern for nohoist is **/ + the part of your package name that follows @department-of-veterans-affairs + / + the name of your dependency. For example: If the vaos app, whose package name is @department-of-veterans-affairs/applications-vaos wanted to nohoist their docdash dependency, they would add **/applications-vaos/docdash to the nohoist array. Note that this makes the nohoist specific to the package directory. So it would only affect vaos. If, for example, burials also wanted to nohoist docdash they would need to add their own blob **/applications-burrials/docdash.

It’s a good idea to check the nohoist array to see if other teams have listed the same dependency, as it may indicate the need for communication between teams—and possibly removing the dependency from the nohoist array.

III. The node_modules folder

You should not alter the contents of the node_modules folders, however there are some use cases in which you may want to delete node_modules; to do a fresh yarn install, for example. This is perfectly acceptable. The node_modules folders act as a cache and the deletion of these does not actually delete the install instructions, only the files. You can delete any and all as deemed necessary and for this purpose a utility script has been provided for convenience.

Installing and removing dependencies

The preferred way to install/remove a dependency in a workspace is with

yarn workspace <worpsapce_name> add (<package>, ...) [flag]

yarn workspace <worpsapce_name> remove <package>

Example:
yarn workspace @department-of-veterans-affairs/applications-vaos add lodash

[Adds lodash to vaos’ dependencies]

yarn workspace @department-of-veterans-affairs/applications-vaos add react react-dom --dev

[Adds both React and React Dom to vaos’ devDependencies]

yarn workspace @department-of-veterans-affairs/applications-vaos remove react
[removes react from vaos]

You can still do a yarn add/ yarn remove if you like, but your present working directory must be the root directory of your project. Or you can edit the package.json directly.

Workspace scripts and commands

Workspaces gives you the ability to run script within your project; this particularly useful for unit testing and build scripts.

Script’s code can be added inline (written in the field itself) or imported from files within or outside your project.

Note for writing inline scripts: when running a yarn workspace command, the script will look in the project’s package.json

To run a script, make sure the script is defined in the scripts field in your project's package.json then call it in as follows: yarn workspace <your-workspace-name> run <script-name> [<arguments>]

Example:
yarn workspace @department-of-veterans-affairs/applications-vaos run demo

Useful utility commands

In the process of setting up Yarn workspaces, Release Tools created these scripts which you may find useful:

`src/platform` code

Importing

All Yarn Workspaces act as packages. As such they will appear as a sim-linked package in the @department-of-veterans-affairs sub directory of the repository’s root node_modules folder. It's recommended that from this point on you use the module imports format for importing src/platform code.
Example: import {objectKeysToCamelCase} from @department-of-veterans-affairs/platform-utilities

Maintaining `src/platform` Code

Platform teams, or in select cases a VFS engineer, may need to maintain code pertinent to their application residing in src/platform. Please refer to Workspace Maintenance: A Deeper Dive.

Testing

Delete all pertinent node_modules folders
Run yarn install
Check ./node_modules/@department-of-veterans-affairs/applications-<your-application-name> exist
Check your application’s root node_modules to make sure non hoisted dependencies are present and correct
Run yarn watch to test for compilation and runtime errors; the yarn workspaces installation should NOT affect the import/export running of current code (only provide a new option)
Run unit tests
Confirm imports using the format @department-of-veterans-affairs/... function properly

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.