Skip to content

A-Shleifman/eslint-plugin-export-scope

Repository files navigation

eslint-plugin-export-scope

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

Basics

Demo

Demo

Scopes

scope importable from
. current directory and children default for all exports
.. parent directory and children default for index files
../.. two directories above and children
src/consumer within specified directory and children
src/consumer.ts within specified file
* anywhere

Scoped Exports

/** @scopeDefault ../.. */
/** ☝ Applies to all exports in the file unless overriden with a local `@scope` */

/** @scope * */
export const helper1 = ""; // 👈 Available everywhere

export const helper2 = ""; // 👈 inherits scope `../..` from `@scopeDefault`

/** @scope src/components */
export default "";

Default folder scope with .scope.ts files

└── src
  └── `common`
    ├── utils.ts
    ├── context.ts
    └── `.scope.ts`
             
             
  ╭────────────────────╮
   export default '*' 
  ╰────────────────────╯
// ⬆ this will make all exports within `common`
// importable from anywhere unless a
// specific export is overriden on a lower level

Exceptions

Export scope exceptions

// schema.ts
/**
 * @scope ..
 * @scopeException src/schemaConsumer 👈 whole folder has access
 * @scopeException src/schemaConsumer/index.ts 👈 whole file has access
 */
export default "";

Folder scope exceptions in .scope.ts files

└── src
  └── `generated`
    ├── schema.ts
    └── `.scope.ts`
             
             
  ╭──────────────────────────────────╮
   export default '.';              
                                    
   export const exceptions = [      
     'src/schemaConsumer',          
     'src/scripts/schemaParser.ts', 
   ]                                
  ╰──────────────────────────────────╯
// ⬆ by default exports are only importable
// within `generated` folder, but
// folders/files in `exceptions` are exempt.

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

Using ESLint Flat Config (ESLint v8 if enabled, ESLint v9)
npm i -D eslint typescript-eslint eslint-plugin-export-scope
// package.json

{
  "type": "module"
}
// eslint.config.js

// @ts-check

import tseslint from "typescript-eslint";
import exportScope from "eslint-plugin-export-scope";

export default tseslint.config(
  // other configs,
  exportScope.configs.flatConfigRecommended,
);
Manual Flat Config
// eslint.config.js

// @ts-check

import tseslint from "typescript-eslint";
import exportScope from "eslint-plugin-export-scope";

export default tseslint.config(
  // other configs,
  {
    files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.mts", "**/*.mjs", "**/*.cjs"],
    plugins: { "export-scope": exportScope.plugin },
    rules: { "export-scope/no-imports-outside-export-scope": "error" },
    languageOptions: { parser: tseslint.parser, parserOptions: { project: true } },
  },
);
Using Legacy Config
npm i -D eslint @typescript-eslint/parser eslint-plugin-export-scope
                    # ⬆ v6 or above
// .eslintrc.js
module.exports = {
  // ...
  extends: ["plugin:eslint-plugin-export-scope/recommended"],
  parser: "@typescript-eslint/parser",
  parserOptions: { project: true, tsconfigRootDir: __dirname },
  ignorePatterns: ["!.scope.ts"],
};
Manual Legacy Config
// .eslintrc.js
module.exports = {
  // ...
  parser: "@typescript-eslint/parser",
  parserOptions: { project: true, tsconfigRootDir: __dirname },
  plugins: ["export-scope"],
  rules: { "export-scope/no-imports-outside-export-scope": "error" },
  ignorePatterns: ["!.scope.ts"],
};

TS plugin will disable autocompletion for exports outside the scope

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

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

Select TS version

Configuration for JS projects
  • tsconfig.json file is still required for the plugin to work
  • replace .scope.ts in both configs with .scope.js
  • set compilerOptions.allowJsto true in tsconfig.json

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).

Restart ESLint Server