Skip to content

JavaScript

  1. Approach
    1. JavaScript MUST only be used for progressive enhancement - do not rely on libraries such as React, Vue or Angular
    2. JavaScript MUST be served as a static file and MUST NOT be compiled at runtime
    3. Compiled JavaScript files SHOULD have a .min.js suffix
    4. Compiled JavaScript MUST NOT contain a source file map in the .js file itself
    5. Compiled JavaScript SHOULD contain a link to a separate source file (.map.js)
  2. Version
    1. JavaScript COULD use ESNext
    2. If written in ESNext, JavaScript MUST be transpiled down to ES5 with Babel
    3. Babel SHOULD use the @babel/preset-env preset
    4. JavaScript COULD be transpiled with Webpack
    5. The version of NodeJS MUST be 22 or above
    6. The version of NodeJS SHOULD be 24 or above
    7. The version of NodeJS SHOULD be a LTS release
    8. The version of NodeJS SHOULD be managed with nvm and a .nvmrc file in the root of the project
  3. Style/linting
    1. JavaScript MUST be linted with ESLint
      1. ESLint MUST extend @nationalarchives/eslint-config
      2. ESLint COULD be configured to ignore some rules
    2. JavaScript MUST be styled with Prettier
    3. Styling JavaScript with Prettier SHOULD NOT use any custom options (Prettier's philosophy on options)
  4. Dependencies
    1. JavaScript dependencies MUST be managed with npm
  5. Frameworks, tools and libraries
    1. JavaScript components COULD be developed using Storybook - (the rationale behind using Storybook)
    2. JavaScript tests SHOULD be written with Jest
    3. Single page applications MUST not be developed
  6. Packages
    1. Packages SHOULD be deployed to npm
    2. Packages on npm MUST be deployed with OIDC
    3. Packages on npm MUST be published under the @nationalarchives scope
    4. Packages COULD be deployed to GitHub Packages
    5. Packages COULD be deployed to AWS CodeArtifact
    6. Packages SHOULD use semver (see using version numbers)
    7. Source files COULD be included in distributed packages alongside the compiled ES5 to allow for the consumer to compile

TypeScript

  1. Approach
    1. As TypeScript is a superset of JavaScript, the same JavaScript standards above MUST also apply to TypeScript
    2. TypeScript COULD be used as an enhancement to JavaScript
  2. Packages
    1. TypeScript MUST be compiled down to ES5 before distribution

NVM

Use nvm to ensure your project can be worked on in the future without having to guess which version of Node.js is required to run it.

Add an .nvmrc file in your project to declare the version of Node required. For example:

lts/krypton

LTS releases have codenames. This ensures that you always use the latest version of that release:

Version LTS Codename
24.x krypton
22.x jod

Check a full list of latest versions for each branch of Node.js.

To ensure the correct version of Node is used, you can add the following line to your .bashrc, .zshrc or similar in order to set up the correct version of Node when you open your terminal for that project:

# If an .nvmrc file exists then install and use that version of Node
[[ -f .nvmrc ]] && nvm install