eslint-plugin-atomic-design

ESLint rules that keep imports flowing downward through the layers of an Atomic Design project.

日本語版 README

Requirements

• ESLint >=9 (both flat config and, on ESLint 9, .eslintrc.* are supported)

Installation

npm install --save-dev eslint eslint-plugin-atomic-design

Usage

Flat config (eslint.config.js, ESLint 9 / 10)

import atomicDesign from 'eslint-plugin-atomic-design';

export default [
  atomicDesign.configs.recommended,
  {
    files: ['src/**/*.js'],
  },
];

configs.recommended registers the plugin and turns hierarchical-import on as an error. To configure the rule yourself, register the plugin directly:

import atomicDesign from 'eslint-plugin-atomic-design';

export default [
  {
    files: ['src/**/*.js'],
    plugins: { 'atomic-design': atomicDesign },
    rules: {
      'atomic-design/hierarchical-import': [
        'error',
        {
          levels: [
            ['elements', 'atoms'],
            'molecules',
            ['=organisms', 'sections'],
          ],
          module: 'strict',
        },
      ],
    },
  },
];

eslintrc (ESLint 9 only)

ESLint 10 removed .eslintrc.* support, but on ESLint 9 the legacy shape is still available:

{
  "extends": ["plugin:atomic-design/recommended-legacy"]
}

or

{
  "plugins": ["atomic-design"],
  "rules": {
    "atomic-design/hierarchical-import": "error"
  }
}

Resolving import paths

Import paths are resolved through eslint-module-utils, the same machinery eslint-plugin-import uses, so the import/resolver setting is shared with it. Without any setting, Node's own resolution is used, which covers relative paths and node_modules.

To resolve aliases such as @/ or ~/, point the setting at a resolver:

export default [
  atomicDesign.configs.recommended,
  {
    settings: {
      'import/resolver': {
        // e.g. eslint-import-resolver-typescript, or any resolver package
        typescript: {},
      },
    },
  },
];

Rules

atomic-design/hierarchical-import

Disallows importing components that sit on the same or a higher level of the hierarchy. Currently this is the only rule of this plugin.

Options

excludes: string[]

Regular expression patterns. A file is skipped when either the linted file path or the resolved import path matches.

default: ['node_modules/\\w']

levels: (string | string[])[]

Component levels in your project, listed from the smallest to the largest. A level prefixed with = may import other components on the same level. Levels that share a single rank can be written as an array:

{
  levels: [['elements', 'atoms'], 'molecules', ['=organisms', 'sections']],
}

default: ['atoms', 'molecules', '=organisms', 'templates', 'pages']

pathPatterns: string[]

Regular expressions containing one capturing group, used to read the level out of a path:

{
  pathPatterns: ['components/(\\w+)/', 'routes/(\\w+)/'],
}

When omitted, the level is taken from the last levels entry that appears in the path.

default: none (use the default parser)

module: 'strict' | 'loose' | 'off' | false

"module" mode lets a component directory own private children.

In loose mode (the default):

// in './components/molecules/SuperDatepicker/SuperDatepickerCalender.js'

// valid
import CommonLabel from '@/components/atoms/CommonLabel.js';
import SuperDatepickerCalenderInput from '@/components/molecules/SuperDatepicker/SuperDatepickerCalenderInput.js';

// invalid (module children are "private")
import OtherModuleChildren from '@/components/molecules/OtherModule/OtherModuleChildren.js';

In strict mode, private children are protected even from their own siblings:

// in './components/molecules/SuperDatepicker/SuperDatepickerCalender.js'

// valid
import CommonLabel from '@/components/atoms/CommonLabel.js';

// invalid (module children are "private")
import OtherModuleChildren from '@/components/molecules/OtherModule/OtherModuleChildren.js';

// invalid (only the module root component may import its children)
import SuperDatepickerCalenderInput from '@/components/molecules/SuperDatepicker/SuperDatepickerCalenderInput.js';
// ...which is valid in the root component './components/molecules/SuperDatepicker/SuperDatepicker.js'

With module mode turned off:

// in './components/molecules/SuperDatepicker/SuperDatepickerCalender.js'

// valid
import CommonLabel from '@/components/atoms/CommonLabel.js';

// invalid (molecules -> molecules)
import OtherModuleChildren from '@/components/molecules/OtherModule/OtherModuleChildren.js';
import SuperDatepickerCalenderInput from '@/components/molecules/SuperDatepicker/SuperDatepickerCalenderInput.js';

default: 'loose'

Migrating from v1

• ESLint 8 and older are no longer supported. The minimum is ESLint 9.
• configs.recommended is now a flat config object. The eslintrc shape moved to configs['recommended-legacy'].
• Unknown rule options are now rejected instead of being silently ignored.
• eslint-import-resolver-alias is no longer a dependency of this plugin. If you rely on it, install it yourself, or use another resolver such as eslint-import-resolver-typescript.

License

MIT © RyoNkmr