diff --git a/docs/frontend.md b/docs/frontend.md index 8d52d00f167..78dabc7b2d6 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -68,25 +68,6 @@ automatically by running `yarn run lint --fix`. You may also consider one of the [available editor integrations](https://prettier.io/docs/en/editors.html), which can simplify your workflow to apply formatting automatically on save. -### Dependencies - -Since the IDP is not a Node.js application or library, the distinction between `dependencies` and -`devDependencies` is largely one of communicating intent to other developers on the team based on -whether they are brought in to benefit the user or the developer. It does not have a meaningful -difference on how those dependencies are used by the application. - -In most situations, the following advice should apply: - -- `dependencies` include modules which are relevant for runtime (user-facing) features. - - Examples: Component libraries, input validation libraries -- `devDependencies` include modules which largely support the developer. - - Examples: Build tools, testing libraries - -When installing a dependency, you can make this distinction by including or omitting the `--dev` -(`-D`) flag when using `yarn add` or `yarn remove`. Refer to the -[Yarn CLI documentation](https://classic.yarnpkg.com/en/docs/cli/) for more information about -installing, removing, and upgrading packages. - ### Yarn Workspaces [Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) allow a developer to create and @@ -117,6 +98,42 @@ workspace packages using symlinks, you can reference a package using the name yo guidelines above for `package.json` `name` field (for example, `import { Button } from '@18f/identity-components';`). +### Dependencies + +While the project is not a Node.js application or library, the distinction between `dependencies` +and `devDependencies` is important due to how assets are precompiled in deployed environments. +During a deployment, dependencies are installed using [the `--production` flag](https://classic.yarnpkg.com/lang/en/docs/cli/install/#toc-yarn-install-production-true-false), +meaning that all dependencies which are required to build the project must be defined as +`dependencies`, not as `devDependencies`. + +`devDependencies` should be reserved for dependencies which are not required to compile application +assets, such as testing-related libraries or [DefinitelyTyped](https://www.typescriptlang.org/dt/) +TypeScript declaration packages. When possible, it is still useful to define `devDependencies` to +improve the performance of application asset compilation. + +When installing new dependencies, consider whether the dependency is relevant for an individual +workspace package, or for the entire project. By default, Yarn will warn when trying to install a +dependency in the root package, since dependencies should typically be installed for a specific +workspace. + +To install a dependency to a workspace: + +```bash +yarn workspace @18f/identity-build-sass add sass-embedded +``` + +To install a dependency to the project: + +```bash +# Note the `-W` flag +yarn add -W webpack +``` + +As much as possible, try to use the same version of a dependency when it is used across multiple +workspace packages. Otherwise, it can inflate the size of the compiled bundles and have a negative +performance impact on users. Similarly, consider using a tool like [`yarn-deduplicate`](https://github.com/scinos/yarn-deduplicate) +to deduplicate resolved package versions within the Yarn lockfile. + ### Components We use a mixture of complementary component implementation approaches to support both server-side