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
, orsrc/applictations
for an app on the allow-listThe code you are working on, within
src/applictations
orsrc/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
exceptingpeerDependencies
, all your project’s production dependencies go here. Whenyarn 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'snode_modules
.devDependencies
Similar to dependencies but used only for development. Note yarn workspaces will install these in locally innode_modules/.bin
and sim link them tonode_modules/.bin
at the root level. In other words, alldev_dependencies
are automatically managed and shared by the repo.peerDependencies
Use only “*” as version value. Keep in mind thatpeerDependencies
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>
existCheck 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
Create an issue ticket to suggest changes to this page