forbidden-imports

Learn how to set custom rules to disallow one or more files from importing one or more predefined modules
Table of Contents

Conformance is available on Enterprise plans

The forbidden-imports rule type enables you to disallow one or more files from importing one or more predefined modules.

Unlike forbidden-dependencies, this rule type wont check for indirect (transitive) dependencies. This makes this rule faster, but limits its effectiveness.

  • Deprecating packages or versions
    • You want to disallow importing a deprecated package, and to recommend a different approach
  • Recommending an alternative package
    • You want to require that users import custom/wrapped methods from test-utils instead of directly from a testing library

If you want to prevent depending on a module for performance or security reasons, you should instead use the forbidden-dependencies rule type.

To create a custom forbidden-imports rule, you'll need to configure the below required properties:

PropertyTypeDescription
ruleType"forbidden-imports"The custom rule's type.
ruleNamestringThe custom rule's name.
categories("nextjs" | "performance" | "security" | "code-health")[] (optional)The custom rule's categories. Default is ["code-health"].
errorMessagestringThe error message, which is shown to users when they encounter this rule.
errorLinkstring (optional)An optional link to show alongside the error message.
descriptionstring (optional)The rule description, which is shown in the Vercel Compass dashboard and included in allowlist files.
severity"major" | "minor" (optional)The rule severity added to the allowlists and used to calculate a project's conformance score.
moduleNamesstring[]An array of exact module names or glob expressions*.

*Note that paths containing square brackets need to be escaped, i.e. [folder-name]\page.tsx would become \[folder-name\]\page.tsx.
importNamesstring[] (optional)An array of exact module names of import names.
pathsstring[] (optional)Added in Conformance 1.4.0. An optional array of exact paths or glob expressions, which restricts the paths that this custom rule applies to. This acts as the overridable default value for paths*.

*Note that paths containing square brackets need to be escaped, i.e. [folder-name]\page.tsx would become \[folder-name\]\page.tsx.
disallowDefaultImportsboolean (optional)Flags default imports (i.e. import foo from 'foo';) as errors.
disallowNamespaceImportsboolean (optional)Flags namespace imports (i.e. import * as foo from 'foo';) as errors.

Note that when using moduleNames alone, imports are not allowed at all from that module. When used with conditions like importNames, the custom rule will only report an error when those conditions are also met.

The example below configures a rule named NO_TEAM_IMPORTS that disallows importing any package from the team workspace except for @team/utils. It also configures a rule that disallows importing oldMethod from @team/utils, but restricts that rule to the src/new/ directory.

conformance.config.jsonc
{
  "customRules": [
    {
      "ruleType": "forbidden-imports",
      "ruleName": "NO_TEAM_IMPORTS",
      "categories": ["security"],
      "errorMessage": "Packages from the team workspace have been deprecated in favour of '@team/utils'.",
      "description": "Disallows importing packages from the team workspace.",
      "severity": "major",
      "moduleNames": ["@team/*", "!@team/utils"],
    },
    {
      "ruleType": "forbidden-imports",
      "ruleName": "NO_TEAM_OLD_METHOD_IMPORTS",
      "categories": ["performance"],
      "errorMessage": "'oldMethod' has been deprecated in favour of 'newMethod'.",
      "description": "Disallows using the deprecated method 'oldMethod' from '@team/utils'.",
      "severity": "minor",
      "moduleNames": ["@team/utils"],
      "importNames": ["oldMethod"],
      "paths": ["src/new/**"],
    },
  ],
}

To enable this rule type, you can set the rule to true, or provide the following configuration.

PropertyTypeDescription
pathsstring[] (optional)An optional array of exact paths or glob expressions, which restricts the paths that this custom rule applies to*.

*Note that paths containing square brackets need to be escaped, i.e. [folder-name]\page.tsx would become \[folder-name\]\page.tsx.

The example below enables the NO_TEAM_IMPORTS custom rule for all files in the src/ directory, excluding files in src/legacy/. In this example, the custom rule is also restricted to the dashboard and marketing-site workspaces, which is optional.

conformance.config.jsonc
{
  "overrides": [
    {
      "restrictTo": {
        "workspaces": ["dashboard", "marketing-site"],
      },
      "rules": {
        "CUSTOM.NO_TEAM_IMPORTS": {
          "paths": ["src", "!src/legacy"],
        },
      },
    },
  ],
  "customRules": [
    // ...
  ],
}

;

Last updated on July 23, 2024