j40-cejst-2/client

Justice40 Client

Linting and Formatting

This project uses ESLint for code linting and Prettier for formatting. They are integrated via gatsby-plugin-prettier-eslint.

Linting is a required check before merges can happen, please lint your code, for the sake of consistency!

To use:

1. During development:

   1. npx gatsby develop will automatically run prettier and eslint during development as files change, watch the console for updates.
   2. Alternatively, if you're using VSCode:
      1. Install the Prettier and ESLint plugins
      2. Enable editor.formatOnSave, and optionally "editor.codeActionsOnSave": {"source.fixAll": true}, to apply settings on save

2. Before a PR: npm run lint:fix can be run locally to apply auto-fixes to issues that can be fixed

3. Before merge (automatic): npm run lint is run against all PRs by a github action.

The ruleset is simply the base ruleset + Google.

Testing

This project uses jest for unit testing, using react-test-renderer to output to text-based snapshot files.

To run tests: npm test To rebuild snapshots when you know a component has changed: npm run test:update

Localization

About

This project uses Gatsby Plugin Intl to manage internationalization and localization.

There are a number of components to this, but for the purposes of localization, this utizes the popular react-intl package from FormatJS.

This works by directing users to a locale-appropriate version of the page they wish to visit based on their browser settings, populated automatically at build time by the contents of json files in the src/intl directory.

Writing

For this library to work optimally, the following principles should be obeyed (see here for more detail):

• All user-visible strings should be wrapped with the intl.formatMessage function or the <FormattedMessage> tag, with a description and defaultMessage set. Do not yet set the "id" tag, it will be generated for you. To generate files for localization, run npm run intl:extract to update the file at src/intl/en.json with the extracted contents of all FormattedMessage components.
• Take note of the id in this file, and add this back as a parameter of your function/prop for your component (this is done to avoid naming collisions as detailed here)
• All Link components should be imported from gatsby-plugin-intl instead to get the locale-appropriate link
• All pages should import and use useIntl from gatsby-plugin-intl

We will later add integration with Github Actions to ensure that all messages have been formatted as a condition/check for committed code.

Translating

From there, send src/intl/en.json to translators. (Depending on the TMS (Translation Management System) in use, we may need a different format, so we can alter the settings in package.json if needbe). When they return with the other language file, e.g. es.json, place this in src/intl/ as a sibling to en.json.

Consuming

React-Intl works according to Google SEO best practices by creating locale-specific URLs.

To access a translated version of a page, e.g. pages/index.js, add the locale as a portion of the URL path, as follows:

• English: localhost:8000/en/, or localhost:8000/ (the default fallback is English)

Feature Toggling

We have implemented very simple feature flagging for this app, accessible via URL parameters.

There are a lot of benefits to using feature toggles -- see Martin Fowler for a longer justification, but in short, they enable shipping in-progress work to production without enabling particular features for all users.

Viewing Features

To view features, add the flags parameter to the URL, and set the value to a comma-delimited list of features to enable, e.g. localhost:8000?flags=1,2,3 will enable features 1, 2, and 3.

In the future we may add other means of audience-targeting, but for now we will be sharing links with flags enabled as a means of sharing in-development funcitonality

Using Flags

When developing, to use a flag:

1. Pass the Gatsby-provided location variable to your component. You have several options here:
   1. If your page uses the Layout component, you automatically get URLFlagProvider (see FlagContext for more info).
   2. If your page does not use Layout, you need to surround your component with a URLFlagProvider component and pass location. You can get location from the default props of the page (more here). See Index.tsx for an example.
2. Use the useFlags() hook to get access to an array of flags, and check this array for the presence of the correct feature identifier. See J40Header for an example.

And that's it!