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 MUST NOT contain a source file map in the .js file itself
   4. 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 18 or above
   6. The version of NodeJS SHOULD be 22 or above
   7. The version of NodeJS SHOULD be a LTS release
   8. The version of NodeJS MUST be managed with nvm and a .nvmrc file in the root of the project
3. Style/linting
   1. JavaScript MUST be linted with ESLint
   2. ESLint MUST extend eslint:recommended
   3. JavaScript MUST be styled with Prettier
   4. 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. JavaScript packages SHOULD be made using npm
   2. JavaScript packages SHOULD be deployed to npm
   3. If using NPM, packages MUST be published under the @nationalarchives organisation
   4. JavaScript packages COULD be hosted in AWS CodeArtifact
   5. JavaScript MUST be compiled down to ES5 before distribution
   6. 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/jod

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

Version	LTS Codename
22.x	jod
20.x	iron
18.x	hydrogen

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

ESLint

ESLint is a static code analyser for JavaScript.

npm install eslint

An example .eslintrc.js file that addresses all the standards above:

module.exports = {
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": ["eslint:recommended"],
  "overrides": [{
    "env": {
      "node": true
    },
    "files": [".eslintrc.{js,cjs}"],
    "parserOptions": {
      "sourceType": "script"
    }
  }],
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "rules": {}
};

# Run eslint against all JS files in the src directory
eslint 'src/**/*.js'

TNA Frontend ESLint config

TNA Frontend comes with an ESLint config which you can use in your project.