eslint-plugin-import-access

3.1.0 verified Sat Apr 25 auth: no javascript

ESLint plugin (v3.1.0) and TypeScript Language Service Plugin that enforces package-private imports via @package JSDoc annotations. The plugin restricts importing variables marked as @package from outside the same directory, providing a directory-level encapsulation layer beyond file-level exports. It requires TypeScript 5.0+, Node.js 20+, and @typescript-eslint/parser 8+. Key differentiators: supports both flat config and eslintrc, offers a language service plugin to prevent auto-completion of non-importable symbols, and is actively maintained with frequent releases.

Common errors

error Error: Failed to load plugin 'import-access' declared in '...': Cannot find module 'eslint-plugin-import-access' ↓

cause The plugin is not installed or not properly resolved in the ESLint configuration.

fix

Run 'npm i -D eslint-plugin-import-access' and ensure it is listed in your dependencies.

error Parsing error: ESLint was configured to run on `<tsconfigRootDir>/...` using `parserOptions.project` but was not found. ↓

cause Missing or incorrect TypeScript project configuration for @typescript-eslint/parser.

fix

Ensure parserOptions.project is set to true or a valid tsconfig.json path, and that the file is included in the project.

error Definition for rule 'import-access/jsdoc' was not found. ↓

cause The plugin is not registered in ESLint's plugins section, or the rule name is misspelled.

fix

Add the plugin to the 'plugins' array in flat config or eslintrc, and use the correct rule name 'import-access/jsdoc'.

error The 'import-access/jsdoc' rule requires typed linting. ↓

cause The rule needs TypeScript type information, but the parser is not set up to provide it.

fix

Enable 'parserOptions.project: true' and ensure the file is included in your tsconfig.

Warnings

breaking v3.0.0 drops support for Node.js <20, TypeScript <5.0, and @typescript-eslint <8. ↓

fix Upgrade to Node.js >=20, TypeScript >=5.0, and @typescript-eslint >=8.

breaking Flat config import path changed: import from 'eslint-plugin-import-access/flat-config' instead of 'eslint-plugin-import-access'. ↓

fix Update import statement to use '/flat-config' subpath.

gotcha The @package JSDoc annotation is case-sensitive and must be exactly @package. @Package or @package-private will not work. ↓

fix Use /** @package */ exactly.

deprecated eslintrc configuration style is deprecated; flat config is recommended. ↓

fix Migrate to flat config using eslint.config.js.

gotcha The TypeScript Language Service Plugin requires using TypeScript from node_modules, not the VSCode bundled version. ↓

fix Ensure your project uses a local TypeScript installation (e.g., 'npx tsc').

Install

npm install eslint-plugin-import-access

yarn add eslint-plugin-import-access

pnpm add eslint-plugin-import-access

Imports

importAccess (flat config plugin)
wrong
```
import importAccess from 'eslint-plugin-import-access'
```
correct
```
import importAccess from 'eslint-plugin-import-access/flat-config'
```
v3.x requires importing from the /flat-config subpath for flat config. Direct import is only for eslintrc.
Plugin for eslintrc
wrong
```
plugins: ['eslint-plugin-import-access']
```
correct
```
plugins: ['import-access']
```
In eslintrc, the plugin name is 'import-access' (without prefix). The prefix is automatically resolved.
Rule: import-access/jsdoc
wrong
```
"import-access/jsdoc": "error"
```
correct
```
"import-access/jsdoc": ["error"]
```
The rule requires an array with severity and options. String form is invalid.

Quickstart

Full setup of eslint-plugin-import-access with flat config, plus a code example showing valid and invalid package-private imports.

// Install
npm i -D eslint-plugin-import-access @typescript-eslint/parser @typescript-eslint/eslint-plugin

// eslint.config.js (flat config)
import tsParser from '@typescript-eslint/parser';
import importAccess from 'eslint-plugin-import-access/flat-config';

export default [
  {
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: true,
        sourceType: 'module',
      },
    },
  },
  {
    plugins: {
      'import-access': importAccess,
    },
  },
  {
    rules: {
      'import-access/jsdoc': ['error'],
    },
  },
];

// sub/foo.ts
/** @package */
export const secret = 'private';

// sub/bar.ts (valid)
import { secret } from './foo';

// baz.ts (invalid)
import { secret } from './sub/foo'; // error