Skip to main content
Version: 7.4.1

TypeScript Support

The plugin ships TypeScript type definitions for all configuration objects. This guide explains how to configure a TypeScript project and use the exported types for autocomplete and compile-time checking of your eslint-plugin-boundaries config.

Prerequisites​

To use this plugin in a TypeScript project, you'll need to install the following dependencies:

npm install --save-dev @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-import-resolver-typescript

These packages provide:

  • @typescript-eslint/parser: Parses TypeScript code for ESLint
  • @typescript-eslint/eslint-plugin: Core TypeScript ESLint rules
  • eslint-import-resolver-typescript: Resolves TypeScript imports and path mappings

Configuration​

Configure your eslint.config.js file to use the TypeScript parser and resolver:

import boundaries from "eslint-plugin-boundaries";
import typescriptParser from "@typescript-eslint/parser";
import typescriptEslintPlugin from "@typescript-eslint/eslint-plugin";

export default [{
  languageOptions: {
    parser: typescriptParser,
  },
  plugins: {
    "@typescript-eslint": typescriptEslintPlugin,
    boundaries,
  },
  settings: {
    "import/resolver": {
      typescript: {
        alwaysTryTypes: true,
      },
    },
  },
}];

Path Mapping Support​

The eslint-import-resolver-typescript automatically detects custom path mappings defined in your tsconfig.json file, making it fully compatible with TypeScript path aliases. Without baseUrl, which TypeScript 6 deprecates, the paths are relative to the tsconfig.json file, so they start with ./:

{
  "compilerOptions": {
    "paths": {
      "@modules/*": ["./src/modules/*"],
      "@shared/*": ["./src/shared/*"]
    }
  }
}

Type Definitions​

The plugin exports comprehensive TypeScript type definitions to provide autocomplete and type safety for your configuration.

Main Config Type​

The primary export is the Config type, which represents a fully typed Flat Config:

import type { Config } from "eslint-plugin-boundaries";

const config: Config = {
  plugins: {
    boundaries,
  },
  settings: {
    "boundaries/elements": [],
    "boundaries/ignore": ["**/ignored/**/*.js"],
  },
  rules: {
    "boundaries/dependencies": [
      "error",
      { default: "disallow", policies: [] },
    ],
  },
};
Tip

For a more strongly-typed setup that also registers the plugin and validates rule prefixes for you, use createConfig imported from eslint-plugin-boundaries/config. The manual Config object above remains a valid alternative when you need to compose configs by hand.

Custom Plugin Names​

The type system supports renaming the plugin when loading it in the plugins property:

import type { Config } from "eslint-plugin-boundaries";

const config: Config<"custom-boundaries"> = {
  plugins: {
    "custom-boundaries": boundaries, // Renamed prefix
  },
  settings: {
    "boundaries/elements": [], // Always uses original prefix in settings
    "boundaries/ignore": ["**/ignored/**/*.js"],
  },
  rules: {
    "custom-boundaries/dependencies": 2, // Must use renamed prefix
  },
};
Warning

Settings always use the boundaries/ prefix regardless of the plugin name, as ESLint doesn't namespace settings by plugin name.

Granular Type Exports​

In addition to the main Config type, the plugin exports individual subtypes for fine-grained type safety. The most common ones:

  • Settings - the settings object (typed boundaries/* keys).
  • Rules - mapping of rule names to their configurations.
  • ElementDescriptor - an entry of the boundaries/elements setting.
  • DependenciesPolicy - one entry of the dependencies rule's policies array (DependenciesRule is a deprecated alias).
  • DependenciesRuleOptions - options for the dependencies rule.
  • ElementSelector - an element selector.
  • DependencyKind - dependency kind union ("value" | "type" | "typeof"); replaces the deprecated ImportKind.
  • CapturedValuesSelector - captured-values selector.
  • DependencyNodeKey, DependencyNodeSelector - dependency-node configuration.
  • IgnoreSetting, IncludeSetting, RootPathSetting, DebugSetting, SettingsKey - other settings types.
  • FileDescriptor, FileDescriptors - an entry (or array) of the boundaries/files setting.

The deprecated-rule option types (EntryPointPolicy, EntryPointRuleOptions, ExternalPolicy, ExternalRuleOptions, NoPrivateOptions) are also exported; see the package types for the complete list. The constants and type guards (SETTINGS_KEYS_MAP, RULE_NAMES_MAP, DEPENDENCY_KINDS_MAP, isSettingsKey, isDependencyKind, isFileDescriptor, and more) are exported from eslint-plugin-boundaries/config, along with every type: see Type Constants and Guards.

This modular approach lets you import only what you need while keeping autocomplete and type checking:

import type {
  Config,
  Settings,
  Rules,
  ElementDescriptor,
  DependenciesRuleOptions,
} from "eslint-plugin-boundaries";

const elementDescriptor: ElementDescriptor = {
  type: "module",
  pattern: "modules/*",
  capture: ["elementName"],
};

const settings: Settings = {
  "boundaries/elements": [elementDescriptor],
};

const dependenciesRuleOptions: DependenciesRuleOptions = {
  default: "disallow",
  policies: [
    {
      from: { element: { type: "module" } },
      allow: { to: { element: { type: "helper" } } },
    },
  ],
};

const rules: Rules = {
  "boundaries/dependencies": ["error", dependenciesRuleOptions],
};

const config: Config = {
  files: ["**/*.js", "**/*.ts"],
  settings,
  rules,
};
Entity selectors

The example above uses entity selectors (from: { element: { type: "..." } }). Flat element selectors (from: { type: "..." }) still work and are converted internally, but the entity selector form also gives you access to file and module matching.

TypeScript breaking changes from v6

If you are upgrading from v6, the following type exports were removed: ElementTypesRule, ElementTypesRuleOptions, ElementSelectors, ElementsSelector, ElementSelectorWithOptions, the guards isElementsSelector, isElementDescriptorMode, isImportKind, and the constant IMPORT_KINDS_MAP. Replace them with DependenciesPolicy, DependenciesRuleOptions, ElementSelector, isDependencyKind, and DEPENDENCY_KINDS_MAP. The deprecated ImportKind type still exists but prefer DependencyKind. See the v6 to v7 migration guide for details.

Troubleshooting​

If you encounter issues with TypeScript support:

  1. Ensure all dependencies are installed with compatible versions
  2. Verify that eslint-import-resolver-typescript is configured in settings
  3. Check that your tsconfig.json is valid and accessible
  4. Confirm that the TypeScript parser is correctly specified in languageOptions
  5. Refer to the TypeScript example in the repository for a known working configuration

Default imports fail to type-check with nodenext, node16 or require()​

With module and moduleResolution set to nodenext or node16, the default imports of eslint-plugin-boundaries, eslint-plugin-boundaries/recommended and eslint-plugin-boundaries/strict fail to type-check in an ES module file (a .mts file, or a .ts file in a package with "type": "module"), and so does their require() in a CommonJS file that TypeScript checks. The errors look like:

error TS2339: Property 'rules' does not exist on type 'typeof import(".../dist/Config/Strict")'.

Import the configs and createConfig, which registers the plugin, from eslint-plugin-boundaries/config instead:

import { createConfig, recommended, strict } from "eslint-plugin-boundaries/config";

Don't read .default to silence the error: it type-checks, but it is undefined at runtime.

Why it happens, and a full example

The type declarations say export default, which describes a module.exports with a default property, but the CommonJS build sets module.exports to the plugin or the config itself. TypeScript types require() and, in an ES module file with nodenext or node16, the default import as that module.exports, so it sees { default: ... } where Node.js returns the plugin or the config. The named exports of /config are typed right with any module resolution, with import and with require(). The fix of the declarations is planned for v8.0.0 (#584).

import { createConfig, recommended } from "eslint-plugin-boundaries/config";

export default [
  createConfig({
    files: ["**/*.ts"],
    settings: {
      ...recommended.settings,
      "boundaries/elements": [{ type: "module", pattern: "src/modules/*" }],
    },
    rules: {
      ...recommended.rules,
    },
  }),
];

Further Reading​