forbidden-code
3 min read

forbidden-code

Learn how to set custom rules to disallow code and code patterns through string and regular expression matches.
Table of Contents

Conformance is available on Enterprise plans

The forbidden-code rule type enables you to disallow code and code patterns through string and regular expression matches.

When to use this rule type

  • Disallowing comments
    • You want to disallow // TODO comments
    • You want to disallow usage of @ts-ignore
  • Disallowing specific strings
    • You want to enforce a certain casing for one or more strings
    • You want to disallow specific strings from being used within code

If you want to disallow specific operations on a property, you should instead use the forbidden-properties rule type.

Configuring this rule type

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

PropertyTypeDescription
ruleType"forbidden-code"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.
patterns(string | { pattern: string, flags: string })[]An array of regular expression patterns to match against.
stringsstring[]An array of exact string to match against (case sensitive).

Multi-line strings and patterns are currently unsupported by this custom rule type.

Example configuration

The example below configures a rule named NO_DISALLOWED_USAGE that disallows:

  • Any usage of "and" at the start of a line (case-sensitive).
  • Any usage of "but" in any case.
  • Any usage of "TODO" (case-sensitive).
conformance.config.jsonc
{
  "customRules": [
    {
      "ruleType": "forbidden-imports",
      "ruleName": "NO_DISALLOWED_USAGE",
      "categories": ["code-health"],
      "errorMessage": "References to \"and\" at the start of a line are not allowed.",
      "description": "Disallows using \"and\" at the start of a line.",
      "severity": "major",
      "patterns": ["^and", { "pattern": "but", "flags": "i" }],
      "strings": ["TODO"],
    },
  ],
}

Using flags with patterns

This custom rule type always sets the "g" (or global) flag for regular expressions. This ensures that all regular expression matches are reported, opposed to only reporting on the first match.

When providing flags through an object in patterns, you can omit the "g" as this will automatically be set.

To learn more about regular expression flags, see the MDN guide on advanced searching with flags.

Writing patterns

If you're not familiar with regular expressions, you can use tools like regex101 and/or RegExr to help you understand and write regular expressions.

Regular expressions can vary in complexity, depending on what you're trying to achieve. We've added some examples below to help you get started.

PatternDescription
^andMatches "and", but only if it occurs at the start of a line (^).
(B|a)ar$Matches "But" and "but", but only if it occurs at the end of a line ($).
regexp?Matches "regexp" and "regex", with or without the "p" (?).
(?<!-)soMatches "so", but only when not following a hyphen ((?<!-)).

Enabling this rule type

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

*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_DISALLOWED_USAGE 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_DISALLOWED_USAGE": {
          "paths": ["src", "!src/legacy"],
        },
      },
    },
  ],
  "customRules": [
    // ...
  ],
}

This next example enables the NO_DISALLOWED_USAGE custom rule for all files, and without workspace restrictions.

conformance.config.jsonc
{
  "overrides": [
    {
      "rules": {
        "CUSTOM.NO_DISALLOWED_USAGE": true,
      },
    },
  ],
  "customRules": [
    // ...
  ],
}

;

Last updated on May 18, 2024
Previous
Custom Rules
Next
forbidden-dependencies