Skip to main content
Version: 7.0.0

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:

{
  "compilerOptions": {
    "baseUrl": ".",
    "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) and constants/guards (SETTINGS_KEYS_MAP, RULE_NAMES_MAP, DEPENDENCY_KINDS_MAP, isSettingsKey, isDependencyKind, isFileDescriptor, and more) are also exported. See the package types for the complete list.

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 example repository for a known working configuration

Further Reading​