Custom Rules

Learn how Conformance improves collaboration, productivity, and software quality at scale.
Table of Contents

Conformance is available on Enterprise plans

Vercel's built-in Conformance rules are crafted from extensive experience in developing large-scale codebases and high-quality web applications. Recognizing the unique needs of different companies, teams, and products, Vercel offers configurable, no-code custom rules. These allow for tailored solutions to specific challenges.

Custom rules in Vercel feature unique error names and messages, providing deeper context and actionable resolution guidance. For example, they may include:

  • Links to internal documentation
  • Alternative methods for logging issues
  • Information on who to contact for help

You can use custom rules to proactively prevent future issues, to reactively prevent issues from reoccuring, and/or as a mitigation tool.

We support the following custom rules types:

TypeDescription
forbidden-codeDisallows code and code patterns through string and regular expression matches.
forbidden-propertiesDisallows properties from being read, written, and/or called.
forbidden-dependenciesDisallows one or more files from depending on one or more predefined modules.
forbidden-importsDisallows one or more files from importing one or more predefined modules.
forbidden-packagesDisallows packages from being listed as dependencies in package.json files.

The no-code custom rules are defined and configured in conformance.config.jsonc.

In this example, you will set up a custom rule with the forbidden-imports type. This rule disallows importing a package called api-utils, and suggests to users that they should instead use a newer version of that package.

  1. At the root of your directory, create a file named conformance.config.jsonc. If one already exists, skip to the next step.

  2. First, define a new custom rule in conformance.customRules.

    All custom rules require the properties:

    • ruleType
    • ruleName
    • errorMessage

    Other required and optional configuration depends on the custom rule type. In this example, we're using the forbidden-imports type, which requires an moduleNames property.

    conformance.config.jsonc
    {
      "customRules": [
        {
          "ruleType": "forbidden-imports",
          "ruleName": "NO_API_UTILS",
          "categories": ["code-health"],
          "errorMessage": "The `api-utils` package has been deprecated. Please use 'api-utils-v2' instead, which includes more features.",
          "errorLink": "https://vercel.com/docs",
          "description": "Don't allow importing the deprecated `api-utils` package.",
          "severity": "major",
          "moduleNames": ["my-utils"],
        },
      ],
    }
  3. As all custom rules are disabled by default, you'll need to enable rules in conformance.overrides. Refer to the documentation for each custom rule type for more information.

    Rule names must be prefixed with "CUSTOM" when enabled, and any allowlist files and entries will also be prefixed with "CUSTOM". This prefix is added to ensure that the names of custom rules don't conflict with built-in rules.

    In the example below, we're enabling the rule for the entire project by providing it with the required configuration (targeting all files in src).

    conformance.config.jsonc
    {
      "overrides": [
        {
          "rules": {
            "CUSTOM.NO_API_UTILS": {
              "paths": ["src"],
            },
          },
        },
      ],
      "customRules": [
        // ...
      ],
    }

    In this example, we've used the same configuration as above, but have also restricted the rule and configuration to the api-teams workspace.

    conformance.config.jsonc
    {
      "overrides": [
        {
          "restrictTo": {
            "workspaces": ["api-teams"],
          },
          "rules": {
            "CUSTOM.NO_API_UTILS": {
              "paths": ["src", "!src/**/*.test.ts"],
            },
          },
        },
      ],
      "customRules": [
        // ...
      ],
    }
  4. In this example used the same configuration as above, but have also restricted the rule and configuration to the api-teams workspace:

    conformance.config.jsonc
    {
      "overrides": [
        {
          "restrictTo": {
            "workspaces": ["api-teams"],
          },
          "rules": {
            "CUSTOM.NO_API_UTILS": {
              "paths": ["src", "!src/**/*.test.ts"],
            },
          },
        },
      ],
      "customRules": [
        // ...
      ],
    }
Last updated on July 23, 2024