From 9aa64546291bef4b62807c74bbdbe509eb4d8ab3 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Wed, 20 Dec 2023 12:08:49 -0500 Subject: [PATCH 1/3] Improve accuracy of Frontend packages, events documentation changelog: Internal, Documentation, Improve accuracy of frontend architecture documentation --- docs/frontend.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/frontend.md b/docs/frontend.md index af4f5c431a4..21c7b4c6ce4 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -66,8 +66,8 @@ workflow to apply formatting automatically on save. [Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/) allow a developer to create and organize code which is used just like any other NPM package, but which doesn't require the overhead -involved in publishing those modules and keeping versions in sync across multiple repositories. The -IDP uses Yarn workspaces to keep JavaScript code organized, reusable, and to encourage good coding +involved in publishing those modules and keeping versions in sync across multiple repositories. We +use Yarn workspaces to keep JavaScript code organized, reusable, and to encourage good coding practices in abstractions. In practice: @@ -75,21 +75,17 @@ In practice: - All folders within `app/javascript/packages` are treated as workspace packages. - Each package should have its own `package.json` that includes... - ...a `name` starting with `@18f/identity-` and ending with the name of the package folder. - - ...a listing of its own dependencies, including to other workspace packages using - [`file:` prefix](https://classic.yarnpkg.com/en/docs/cli/add/). - - ...[`"private": true`](https://docs.npmjs.com/files/package.json#private) if the workspace - package is not intended to be published to NPM. + - ...a [`private`](https://docs.npmjs.com/files/package.json#private) value indicating whether the + package is intended to be published to NPM. - ...a value for the `version` field, since it is required. The value value can be anything, and `"1.0.0"` is a good default. -- Each package should include an `index.js` which serves as the entry-point and public API for the - package. - -A package might have a corresponding file by the same package name contained within -`app/javascript/packs` that serves as the integration point between packages and the Rails -application. This is to encourage packages to be reusable, where the file in `packs` contains any -logic required to wire the package to the running Rails application. Because Yarn will alias -workspace packages using symlinks, you can reference a package using the name you assigned using the -guidelines above for `package.json` `name` field (for example, + +As with any public NPM package, a workspace package should ideally be reusable and avoid direct +references to page elements. In order to integrate a package within a particular page, you should +either reference it within [a ViewComponent component's accompanying script](https://github.com/18F/identity-idp/blob/main/app/components/README.md), or by creating a new `app/javascript/packs` file to be loaded on a page. + +Because Yarn will alias workspace packages using symlinks, you can reference a package using the +name you assigned using the guidelines above for `package.json` `name` field (for example, `import { Button } from '@18f/identity-components';`). ### Dependencies @@ -138,9 +134,9 @@ See [`@18f/identity-analytics` package documentation][analytics_package] for cod how to track an event in JavaScript. Any event logged from the frontend must be added to the `ALLOWED_EVENTS` allowlist in [`FrontendLogController`][frontend_log_controller.rb]. -This mapping associates the event name logged from the frontend with the corresponding method from -[AnalyticsEvents][analytics_events.rb] to be called. All properties will be passed automatically to -the event from the frontend as long as they are defined in the method argument signature. +This is an allowlist of events defined in [AnalyticsEvents][analytics_events.rb] which are allowed +to be logged from the frontend. All properties will be passed automatically to the event from the +frontend as long as they are defined in the method argument signature. There may be some situations where you need to append a value known by the server to an event logged in the frontend, such as an A/B test bucket descriptor. In these scenarios, you have a few options: From c7fa569251f696dc8d25799a9490bef207b5fed1 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Wed, 20 Dec 2023 12:12:52 -0500 Subject: [PATCH 2/3] Restore bare import recommendation --- docs/frontend.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/frontend.md b/docs/frontend.md index 21c7b4c6ce4..ac3a7b6428c 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -79,6 +79,8 @@ In practice: package is intended to be published to NPM. - ...a value for the `version` field, since it is required. The value value can be anything, and `"1.0.0"` is a good default. +- The package should be importable by its bare name, either with an `index.ts` or equivalent + [package entrypoints](https://nodejs.org/api/packages.html#package-entry-points) As with any public NPM package, a workspace package should ideally be reusable and avoid direct references to page elements. In order to integrate a package within a particular page, you should From 6a5f5c3030ecf9f4b6cf703521fbc1f0241e3289 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Wed, 20 Dec 2023 12:52:16 -0500 Subject: [PATCH 3/3] Use consistent line length convention --- docs/frontend.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/frontend.md b/docs/frontend.md index ac3a7b6428c..a1fc13ebe57 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -84,7 +84,8 @@ In practice: As with any public NPM package, a workspace package should ideally be reusable and avoid direct references to page elements. In order to integrate a package within a particular page, you should -either reference it within [a ViewComponent component's accompanying script](https://github.com/18F/identity-idp/blob/main/app/components/README.md), or by creating a new `app/javascript/packs` file to be loaded on a page. +either reference it within [a ViewComponent component's accompanying script](https://github.com/18F/identity-idp/blob/main/app/components/README.md), +or by creating a new `app/javascript/packs` file to be loaded on a page. Because Yarn will alias workspace packages using symlinks, you can reference a package using the name you assigned using the guidelines above for `package.json` `name` field (for example,