JavaScript and TypeScript

Note

Don’t use CoffeeScript. Unless the repository is a fork, use Decaffeinate to convert CoffeeScript to ECMAScript.

License

Use the MIT license.

Version

ECMAScript

Frontend code is written for ECMAScript 6 (ES6) (see the status of feature support in modern browsers). We don’t support Internet Explorer 11.

Tip

To transform older code to ECMAScript 6, use lebab, but be aware of its bugs. There is a lebab plugin for Sublime Text. Use these preferences (Preferences > Package Settings > Lebab > Settings - User):

{
  "transforms": [
    "arrow",
    "arrow-return",
    "let",
    "for-of",
    "for-each",
    "arg-rest",
    "arg-spread",
    "obj-method",
    "obj-shorthand",
    "no-strict",
    "exponent",
    "class",
    "commonjs",
    "template",
    "default-param",
    "includes"
  ]
}

To transform newer code to ECMAScript 6, use Babel with the defaults query from browserlist.

Node

Applications are written for the latest LTS version of Node. Packages are written for non-end-of-life versions (see the status of Node versions).

To upgrade Node, change the node-version key in GitHub Actions workflows and the node (or nikolaik/python-nodejs) image in Dockerfiles. Check the relevant changelog for breaking changes.

Preferences

Plain JavaScript is preferred to using jQuery, unless functionality depends on jQuery plugins. To replace jQuery in a project, refer to You Might Not Need jQuery. Similarly, use the Fetch API instead of the Axios package, etc.

Package manager

npm, the default package manager of Node.js. Do not use yarn. Yarn has no equivalent to npm audit fix.

User interface

Vue is preferred to React. That said, do not use frameworks for simple interfaces.

Asset management

webpack, unless a framework provides its own, like Vue.

Sass

sass (dart-sass). Do not use node-sass, which is deprecated.

Formatter

Biome.

Requirements

Use npm, not yarn. Set the Node version in package.json, as documented.

List outdated dependencies:

npm outdated

Upgrade outdated dependencies:

npm update

Upgrade Vue dependencies:

vue upgrade --next

Vulnerabilities

Dependabot alerts

If the Dependabot alert is for a build dependency (like node-sass) or a test dependency (like mocha), you can dismiss it with “Risk is tolerable for this project”. The npm ecosystem has false positives.

To check for vulnerable dependencies:

npm audit --production

Note

npm audit (without --production) has false positives (Vue example).

To upgrade vulnerable dependencies:

  1. Check the version of Node:

    node --version

  2. Upgrade npm:

    npm install -g npm@latest

  3. Run:

    npm audit fix

  4. Manually update version numbers in package.json:

    1. Find a “fix available” line

    2. Read its following line (“Will install <package>@<version>”)

    3. Check the package’s changelog for changes between the two versions

    4. Update package.json, and repeat

Code style

Vue

  • When navigating between “pages”, respect native browser behaviors (open in new tab, etc.) by using an <a> link or <router-link>.

Internationalization (i18n)

See the Transifex Native documentation for your framework.

Continuous integration

Create a .github/workflows/js.yml file. As a base, use:

name: Lint JavaScript
on: [push, pull_request]
jobs:
  build:
    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: biomejs/setup-biome@v2
      - run: biome ci --indent-style=space --line-width=119 .

Tip

In most cases, you can reuse the js workflow. For example:

jobs:
  lint:
    uses: open-contracting/.github/.github/workflows/js.yml@main
    with:
      filenames: path/to/file.js

Reference