Workspace Maintainence: A Deeper Dive

The following is a deeper dive into the technical nuances of maintaining your team’s workspace within vets-website/src/platform

TL:DR;

1. Create the new directory and files as a child of src/platform

2. Add yarn workspaces, following the instructions in this doc.

3. Create an exportsFile.js and populate it with the methods, modules, etc. which you wish to readily expose to VFS developers.

   • Keep in mind when importing into exportsFile.js tho use relative paths for imports from that same directory

4. Add exports: {..., './alias':'path/to/file'} to the package.json file.

5. Update ./babel.config.json plugin for module resolver to include aliases for ALL desired imports from this new directory.

If you get a linting error, at this step , stating the path to your import cannot be resolved try restarting VS Code.

Workspaces inside src/platform

Similar to code within src/applications, the Release Tools Team is responsible for initial setup of any yarn workspaces inside src/platform code. After the initial set up, Platform teams and approved app-teams can maintain their corresponding workspaces.

Workspaces have been added to the top-level directories in src/platform. Currently, the main difference from the workspaces in src/applications is that the workspaces in src/platform export modules, which are defined in the project's package.json's exports filed. To add exports:

1. in the package.json of a src/platform workspace, add an "exports" field. Then, for every module/export you want to be made available outside of the workspace, add an alias, e.g.

   CODE

   "exports": {
     "./someModule": "./path/to/some/module.js"
   }

Adding the exports field means that only those modules specified can be exported - this prevents applications from importing modules not meant to be exported.

We make use of aliases, e.g. ./someModule to make importing simpler. This would be used in an application like so:

import module from "@department-of-veterans-affairs/platform-{directory}/someModule"

2. Aggregate all the exported modules in a given src/platform directory into a file called

src/platform/{directory}/exportsFile.js, then re-export them from this file; we then add an alias, "./" , for the file in "exports":

"exports": {
  "./": "./exportsFile.js",
  "./someModule": "./path/to/some/module.js"
}

This aggregation gives VFS engineers a shorter way to import modules in their applications, especially if they are using many functions from different places in the package, e.g.:

import { someModule } from "@department-of-veterans-affairs/platform-{directory}"

as opposed to

import { someModule } from "@department-of-veterans-affairs/platform-{directory}/path/to/some/module"

Watch out for naming collisions among the different exports of a src/platform directory (e.g. two modules might export a function with the same name). Use your best judgment in resolving these conflicts by choosing alternate names or by including part of the path to the module in the alias.

3. Eslint will not resolve modules imported using Yarn Workspace syntax (e.g. "@department-of-veterans-affairs/platform-{directory}/someModule") unless an alias is added to the module-resolver plugin in the vets-website root level babel.config.json. So for every module listed in "exports" of platform/{directory}/package.json add an alias to the babel file, e.g.:

"module-resolver",
      {
        "root": "./src",
        "alias": {
          ...
          "@department-of-veterans-affairs/platform-forms/labels": "./src/platform/forms/address/data/labels.js",
...

If you add an alias to babel.config.json and are still getting an ESlint error that the module can’t be resolved try restarting VS Code.

Platform and VFS team engineers working with code in src/platform, if you have added new files and/or exports to your code do not neglect to curate your entry points (exports) and exportsFile.js.

Files not in listed in the exports field will not be available for import by code external to the package (via import <package-name>. List any file which has at least one export that you want to make available. Alternatively, you could export to your exportsFile.js, making sure the exportsFile.js is present in the exports field.

The exportsFile.js serves as a convention, allowing you more granular control of the exports, as well as serving as a convenient hub and giving engineers in other team the ability to see what can be imported from the package.

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.