Datarockets Style Guide

This repository is the home of Datarockets' style guide, which includes configs for popular linting and styling tools.

The following configs are available, and are designed to be used together.

• Prettier
• ESLint
• TypeScript

Contributing

Please read our contributing guide before creating a pull request.

Installation

All of our configs are contained in one package, @datarockets/style-guide. To install:

npm i -D @datarockets/style-guide

Some of our configs require peer dependencies. Install them depending on which configs you use:

# If you use @datarockets/style-guide/prettier
npm i -D prettier
# If you use @datarockets/style-guide/eslint
npm i -D eslint
# If you use Next.js and @datarockets/style-guide/eslint/next
npm i -D @next/eslint-plugin-next
# If you use @datarockets/style-guide/typescript
npm i -D typescript

Prettier

Note: Prettier is a peer-dependency of this package, and should be installed at the root of your project.

See: https://prettier.io/docs/en/install.html

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

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

If you need to override the configuration (see: https://prettier.io/docs/en/configuration#sharing-configurations):

importdatarocketsPrettierConfigfrom'@datarockets/style-guide/prettier';exportdefault{
...datarocketsPrettierConfig,semi: false,};

ESLint

Note: ESLint is a peer-dependency of this package, and should be installed at the root of your project.

See: https://eslint.org/docs/user-guide/getting-started#installation-and-usage

This ESLint config is designed to be composable.

The following base configs are available. You can use one or both of these configs, but they should always be first in the configs order:

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

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

The following additional configs are available:

• @datarockets/style-guide/eslint/jest
• @datarockets/style-guide/eslint/jest-react (includes rules for @testing-library/react)
• @datarockets/style-guide/eslint/next (requires @next/eslint-plugin-next to be installed at the same version as next)
  • extends @datarockets/style-guide/eslint/react
• @datarockets/style-guide/eslint/playwright
• @datarockets/style-guide/eslint/react
• @datarockets/style-guide/eslint/storybook
• @datarockets/style-guide/eslint/typescript (requires typescript to be installed)

Plugins

Base

• eslint-plugin-eslint-comments
• eslint-plugin-import
• eslint-plugin-simple-import-sort
• eslint-plugin-unicorn
• eslint-plugin-prettier

TypeScript

• typescript-eslint
• eslint-plugin-tsdoc

React

• eslint-react
• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-jsx-a11y

Next

• @next/eslint-plugin-next

Jest

• eslint-plugin-jest
• eslint-plugin-testing-library (React)

Playwright

• eslint-plugin-playwright

Storybook

• eslint-plugin-storybook

Examples

Next.js

Note: you might need to clear ESLint's cache for the first usage.

Here is a recommended approach of using ESLint configs in Next.js projects.

eslint.config.js:

importpathfrom'node:path';importbrowserfrom'@datarockets/style-guide/eslint/browser';importjestfrom'@datarockets/style-guide/eslint/jest';importjestReactfrom'@datarockets/style-guide/eslint/jest-react';importnextfrom'@datarockets/style-guide/eslint/next';importnodefrom'@datarockets/style-guide/eslint/node';importplaywrightfrom'@datarockets/style-guide/eslint/playwright';importstorybookfrom'@datarockets/style-guide/eslint/storybook';importtsfrom'@datarockets/style-guide/eslint/typescript';import{includeIgnoreFile}from'@datarockets/style-guide/eslint/utils';import{defineConfig,globalIgnores}from'eslint/config';constgitignorePath=path.resolve(import.meta.dirname,'.gitignore');exportdefaultdefineConfig(includeIgnoreFile(gitignorePath),globalIgnores([// Any directories/files which makes sense to ignore to improve ESLint// performance.]),node,browser,ts,next,// Unit tests (Jest){files: ['src/**/__tests__/**/*.{js,jsx,ts,tsx}','src/**/?(*.)+(spec|test).{js,jsx,ts,tsx}','jest.setup.{js,ts}',],extends: [jest,jestReact],settings: {jest: {version: 20}},},// E2E tests (Playwright){files: ['tests/**/?(*.)+(spec|test).{js,jsx,ts,tsx}'],extends: [playwright],},// Storybook{files: ['*.stories.{js,jsx,ts,tsx}'],extends: [storybook],},);

next.config.js:

/** @type {NextConfig} */constnextConfig={eslint: {dirs: [// By default, Next.js lints only `app`, `pages`, `components`, `lib`, `src`// directories. Here we overwrite it to lint all files in the project.'.',],},};

Scoped configuration with files

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.

exportdefault[// ...intial configuration{files: ['**/*.{ts,tsx}'],rules: {'@typescript-eslint/restrict-template-expressions': ['error',{allowAny: true,allowBoolean: true,allowNumber: true},],'@typescript-eslint/no-misused-promises': ['error',{checksVoidReturn: {attributes: false}},],},},];

In case you need to apply multiple configs to certain files, you can use extends from defineConfig.:

import{defineConfig}from'eslint/config';exportdefaultdefineConfig(// ...intial configuration{files: ['some-dir/**/*'],extends: [externalConfig,// Here, the final `files` should match both 'some-dir/**/*' and '**/*.{ts,tsx}'.{files: ['**/*.{ts,tsx}'],rules: {'some-rule': 'off'}},],},);

Configuring rules/settings

There are some rules/settings that you probably want to configure manually to fit your project needs.

jsx-a11y custom components

It's common practice for React apps to have shared components like Button, which wrap native elements. You can pass this information along to jsx-a11y via the components setting.

For example,

exportdefault[// ...intial configuration{settings: {'jsx-a11y': {components: {Article: 'article',Button: 'button',Image: 'img',Input: 'input',Link: 'a',Video: 'video',// ...},},},},];

unicorn/filename-case

By default, it's configured to ensure that all files are in kebab-case. If your project already have a convention for file names, you can configure this rule to fit the convention (see Documentation):

exportdefault[{rules: {// Your project uses both `camelCase` and `PascalCase`'unicorn/filename-case': ['error',{cases: {camelCase: true,pascalCase: true,},},],},},];

simple-import-sort/imports (import order)

We enforce a certain import order by default. For example:

// Side effectsimport'./global.css';// Node.js builtins prefixed with `node:`.importpathfrom'node:path';// External packagesimportImagefrom'next/image';// 1. Absolute imports and other imports such as Vue-style `@/foo`.// 2. Relative imports.import{SomeComponent}from'@/components';import{parent}from'../parent';import{sibling}from'./sibling';

You can configure it by modifying simple-import-sort/imports rule (see Documentation):

exportdefault[{rules: {'simple-import-sort/imports': ['error',{groups: [// Type imports.['\\u0000$'],// Side effect imports.['^\\u0000'],// Node.js builtins prefixed with `node:`.['^node:'],// Packages.['^@?\\w'],// 1. Absolute imports and other imports such as Vue-style `@/foo`.// 2. Relative imports.['^','^\\.'],],},],},},];

import/no-cycle

By default, this rule is only enabled in CI for the performance sake since it's the slowest rule. If you want to enable it in the development or completely disable it, you can overwrite it in your config:

exportdefault[{rules: {'import/no-cycle': 'off',},},];

Debugging ESLint

Sometimes you need to debug ESLint to understand what actually happens and why something doesn't work.

To output ESLint debug logs:

DEBUG=eslint* npx eslint .# For Next.js projects
DEBUG=eslint* npx next lint

To show final ESLint config:

npx eslint --print-config <some-file>

TypeScript

We provide a base config for TypeScript which contains some defaults we usually use.

To use it, just extend it in your tsconfig.json:

{
"extends": "@datarockets/style-guide/typescript"
}

The base config isn't intended to be used as a complete one, so you might need to add more settings in your tsconfig.json. For example:

{
"extends": "@datarockets/style-guide/typescript",
"compilerOptions": {
"target": "es5",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"noEmit": true,
"module": "esnext",
"moduleResolution": "bundler",
"resolveJsonModule": true,
"isolatedModules": true,
"jsx": "preserve",
"plugins": [
{
"name": "next"
}
],
"paths": {
"@/*": ["./src/*"]
}
},
"include": [
"next-env.d.ts",
"**/*.ts",
"**/*.tsx",
".next/types/**/*.ts",
".storybook/**/*"
],
"exclude": ["node_modules"]
}

Acknowledge

Inspired by https://github.com/vercel/style-guide.