eslint-plugin-export-scope

Don't leak LOCAL utils, states, contexts, components into the global scope.

Demo

Scopes

Scoped Exports

1/** @scopeDefault ../.. */
2/** ☝ Applies to all exports in the file unless overriden with a local `@scope` */
3
4/** @scope * */
5export const helper1 = ""; // 👈 Available everywhere
6
7export const helper2 = ""; // 👈 inherits scope `../..` from `@scopeDefault`
8
9/** @scope src/components */
10export default "";

Default folder scope with .scope.ts files

1└── src
2  └── `common`
3    ├── utils.ts
4    ├── context.ts
5    └── `.scope.ts`
6             │
7             │
8  ╭────────────────────╮
9  │ export default '*' │
10  ╰────────────────────╯
11// ⬆ this will make all exports within `common`
12// importable from anywhere unless a
13// specific export is overriden on a lower level
14

Exceptions

Export scope exceptions

1// schema.ts
2/**
3 * @scope ..
4 * @scopeException src/schemaConsumer 👈 whole folder has access
5 * @scopeException src/schemaConsumer/index.ts 👈 whole file has access
6 */
7export default "";

Folder scope exceptions in .scope.ts files

1└── src
2  └── `generated`
3    ├── schema.ts
4    └── `.scope.ts`
5             │
6             │
7  ╭──────────────────────────────────╮
8  │ export default '.';              │
9  │                                  │
10  │ export const exceptions = [      │
11  │   'src/schemaConsumer',          │
12  │   'src/scripts/schemaParser.ts', │
13  │ ]                                │
14  ╰──────────────────────────────────╯
15// ⬆ by default exports are only importable
16// within `generated` folder, but
17// folders/files in `exceptions` are exempt.
18

Installation

Install ESLint and the export-scope package. This package includes both an ESLint plugin and a TS Language Server plugin.

ESLint plugin will highlight imports outside the scope

1npm i -D eslint typescript-eslint eslint-plugin-export-scope

1// package.json
2
3{
4  "type": "module"
5}

1// eslint.config.js
2
3// @ts-check
4
5import tseslint from "typescript-eslint";
6import exportScope from "eslint-plugin-export-scope";
7
8export default tseslint.config(
9  // other configs,
10  exportScope.configs.flatConfigRecommended,
11);

1// eslint.config.js
2
3// @ts-check
4
5import tseslint from "typescript-eslint";
6import exportScope from "eslint-plugin-export-scope";
7
8export default tseslint.config(
9  // other configs,
10  {
11    files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mts", "**/*.mjs", "**/*.cjs"],
12    plugins: { "export-scope": exportScope.plugin },
13    rules: { "export-scope/no-imports-outside-export-scope": "error" },
14    languageOptions: { parser: tseslint.parser, parserOptions: { project: true } },
15  },
16);

1npm i -D eslint @typescript-eslint/parser eslint-plugin-export-scope
2                    # ⬆ v6 or above

1// .eslintrc.js
2module.exports = {
3  // ...
4  extends: ["plugin:eslint-plugin-export-scope/recommended"],
5  parser: "@typescript-eslint/parser",
6  parserOptions: { project: true, tsconfigRootDir: __dirname },
7  ignorePatterns: ["!.scope.ts"],
8};

1// .eslintrc.js
2module.exports = {
3  // ...
4  parser: "@typescript-eslint/parser",
5  parserOptions: { project: true, tsconfigRootDir: __dirname },
6  plugins: ["export-scope"],
7  rules: { "export-scope/no-imports-outside-export-scope": "error" },
8  ignorePatterns: ["!.scope.ts"],
9};

TS plugin will disable autocompletion for exports outside the scope

1// tsconfig.json
2"compilerOptions": {
3  "plugins": [{ "name": "eslint-plugin-export-scope" }],
4},
5"include": ["**/*", "**/.scope.ts"]
6//                  "../../**/.scope.ts" for monorepos

Tell VSCode to Use Workspace Version of TypeScript. Otherwise TS plugin won't work.

Upgrading from v1 to v2

• Replace all // comments with jsDocs /** */
• Replace @scope default with @scopeDefault
• Relace @.. file/folder prefixes with .scope.ts files.
• Make sure .eslintrc.js and tsconfig.json configs are updated

Hints

• Type @ above exports for automatic jsDoc generation.
• Use autocompletion provided within jsDocs and .scope.ts files.
• Root .scope.ts file (next to package.json) sets the default for the whole project. Having export default '*' there will make all exports global by default if you prefer a less strict approach.

Issues

⚠️ To re-lint an import in VSCode after updating a scope declaration either touch this import or restart the ESLint Server (ESLint limitation).