The Seek Style Guide

Introduction

This repository is the Seek style guide for JavaScript and TypeScript projects. It is a set of rules and configurations that we use to ensure consistency and quality in our code.

The configuration is based on StandardJS and Prettier, and it is meant to be used with ESLint and TypeScript ESLint.

Installation

All of our configs are contained in one package @yomarsanchez/style-guide, so you can install it with a single command.

# If you use npm
npm i --save-dev @yomarsanchez/style-guide

# If you use pmpm
pnpm i --save-dev @yomarsanchez/style-guide

# If you use yarn
yarn add --dev @yomarsanchez/style-guide

Note

Some of our ESLint configs require peer dependencies. We'll note those alongside the available configs in the ESLint section.

If this is your first time using @yomarsanchez/style-guide, you'll need to create a .npmrc file in the root of your project. This file is used to specify the registry where npm will look for the @yomarsanchez/ packages (in this case, GitHub Packages).

//npm.pkg.github.com/:_authToken=TOKEN
@yomarsanchez:registry=https://npm.pkg.github.com

Usage

Prettier and ESLint are a peer-dependency of this package, and should be installed in the root of your project. See Prettier documentation and ESLint documentation

# If you use npm
npm i --save-dev prettier eslint

# If you use pmpm
pnpm i --save-dev prettier eslint

# If you use yarn
yarn add --dev prettier eslint

If you are using TypeScript, you'll also need to install typescript and @typescript-eslint/eslint-plugin.

# If you use npm
npm i --save-dev typescript @typescript-eslint/eslint-plugin

# If you use pmpm
pnpm i --save-dev typescript @typescript-eslint/eslint-plugin

# If you use yarn
yarn add --dev typescript @typescript-eslint/eslint-plugin

Prettier

To use the shared Prettier config, set the following in package.json.

{
  "prettier": "@yomarsanchez/style-guide/prettier"
}

ESLint

This ESLint config is designed to be composable.

The following base configs are available. You can use one or both of these configs:

• @yomarsanchez/style-guide/eslint/browser
• @yomarsanchez/style-guide/eslint/node

Note that you can scope configs, so that configs only target specific files. For more information, see: Scoped configuration with overrides.

The following additional configs are available:

• @yomarsanchez/style-guide/eslint/next
• @yomarsanchez/style-guide/eslint/playwright-test
• @yomarsanchez/style-guide/eslint/react
• @yomarsanchez/style-guide/eslint/typescript (requires typescript and @typescript-eslint/eslint-plugin to be installed and additional configuration)

You'll need to use require.resolve to provide ESLint with absolute paths, due to an issue around ESLint config resolution (see eslint/eslint#9188).

For example, use the shared ESLint config(s) in a Next.js project, set the following in .eslintrc.js.

/**
 * ESLint configuration.
 * @type {import('eslint').Linter.Config}
 */
module.exports = {
  extends: [
    require.resolve('@yomarsanchez/style-guide/eslint/browser'),
    require.resolve('@yomarsanchez/style-guide/eslint/react')
  ]
}

Configuring ESLint for TypeScript

Some of the rules enabled in the TypeScript config require additional type information, you'll need to provide the path to your tsconfig.json.

For more information, see: Linting with Type Information

const { resolve } = require('node:path')

const project = resolve(__dirname, 'tsconfig.json')

/**
 * ESLint configuration.
 * @type {import('eslint').Linter.Config}
 */
module.exports = {
  root: true,
  extends: [
    require.resolve('@yomarsanchez/style-guide/eslint/browser'),
    require.resolve('@yomarsanchez/style-guide/eslint/typescript')
  ],
  parserOptions: {
    project
  },
  settings: {
    'import/resolver': {
      typescript: {
        project
      }
    }
  }
}

Note

Please note that some of the rules enabled by default require that you have strict: true in your tsconfig.json.

Scoped configuration with overrides

ESLint configs can be scoped to include/exclude specific paths. This ensures that rules don't "leak" into places where those rules don't apply.

In this example, TypeScript rules only apply to files that match the *.ts and *.tsx extensions..

/**
 * ESLint configuration.
 * @type {import('eslint').Linter.Config}
 */
module.exports = {
  extends: [require.resolve('@yomarsanchez/style-guide/eslint/browser')],
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      extends: [require.resolve('@yomarsanchez/style-guide/eslint/typescript')]
    }
  ]
}

A note on file extensions

By default, all TypeScript rules are scoped to files ending with .ts and .tsx.

However, when using overrides, file extensions must be included or ESLint will only include .js files.

/**
 * ESLint configuration.
 * @type {import('eslint').Linter.Config}
 */
module.exports = {
  overrides: [{ files: [`directory/**/*.[jt]s?(x)`], rules: { 'my-rule': 'off' } }]
}

Automatic Formatting in VSCode

To automatically format your code in VSCode, install the following extensions:

• ESLint
• Prettier
• JavaScript and TypeScript Nightly

Then, create a .vscode/settings.json file in your project with the following configuration:

{
  "editor.formatOnPaste": true,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.fixAll.eslint": "explicit",
    "source.fixAll.format": "explicit",
    "source.organizeImports": "never",
    "source.sortMembers": "explicit"
  },
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "typescript.tsdk": "node_modules\\typescript\\lib",
  "[javascript, javascriptreact, typescript, typescriptreact]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint",
    "editor.formatOnSave": true
  },
  "[scss, css]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

Tip

If you want to highlight errors in your code, you can add the extension Error Lens to your VSCode.

Contributing

• Add a CONTRIBUTING.md file with instructions on how to contribute.

Note

This project is still in its early stages. We are still working on the rules and configurations, and we are open to feedback and contributions.