Yarn Workspaces

This document is meant to serve as a rudimentary introduction to the set up and use of Yarn Workspaces in vets-website.

In this documentation, references to src/platform are meant to indicate the repository directory vets-website/tree/main/src/platform; similarly, src/applications indicates vets-website/tree/main/src/applications

What is a workspace

Yarn Workspaces is a feature that allows users to install dependencies from multiple package.json files in subfolders of a single root package.json file, all in one go. Yarn can also create symlinks between Workspaces that depend on each other, which will ensure the consistency and correctness of all directories.

Put simply, a workspace is a package of managed code.

Glossary:

Term	Definition
Workspace	A directory denoted via a valid `package.json` file. Example: `src/applications/vaos`... containing a `package.json` file such as: CODE `{ "name": "@department-of-veterans-affairs/applications-vaos", "version": "0.0.1", ... "private": true }` See: workpaces definition on the Yarn Documentation site
Worktree	A valid workspace at the root of `vets-website` that has a `workspaces` field in its `package.json` file, which connects it in some way to project-level `package.json` files. Example: In the root directory of `vets-website`, we have a `package.json` file such as: CODE `{ "name": "vets-website", "version": "0.0.1", ... "workspaces": [ "src/applications/vaos", ... ], "private": true }` See: worktree definition on the Yarn Documentation site
Worktree Maintainer *Only Release Tools Team	A worktree maintainer’s function is to ensure the health of the overall worktree, perform the initial set up of workspaces, consult with workspace maintainers, and deal with any issues stemming from the use of workspaces that affect the repo globally.
Workspace Maintainers *VFS or Platform Engineers	A workspace maintainer’s function the maintenance (not set up) of the workspace(s) specifically corresponding to their team's projects. This may entail tasks such as: managing dependencies, managing their apps entries in the `nohoist` field, writing scripts, curating entry points, etc.

User roles

Users can be categorized into two types: worktree maintainers and workspace maintainers.

The Release Tools team serves as the worktree maintainers. They, exclusively, define, set up and trouble shoot issues with the worktree. Release Tools sets up new workspaces for eligible teams. Release Tools also assists in maintaining workspaces within src/platform.

Workspace maintainers are members of app teams (VFS or Platform) that maintain the pre-existing workspaces corresponding to their own team's projects.

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.

Please consult the Workspace Maintenance: Overview.

If you are part of Release Tools you should familiarize yourself with both the Workspace Maintenance: Overview and the Worktree and Workspace Setup Guide.

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.