3 min read

Customizing Conformance

Learn how to manage and configure your Conformance rules.
Table of Contents

Conformance is available on Enterprise plans

The Conformance framework may be customized so that you can manage rules for different workspaces in your repository or to pass configuration to the rules.

To customize Conformance, first define a conformance.config.jsonc file in the root of your directory.

Both conformance.config.jsonc and conformance.config.json are supported, and both support JSONC (JSON with JavaScript-style comments). We recommend using the .jsonc extension as it helps other tools (i.e. VS Code) to provide syntax highlighting and validation.

Each Conformance override accepts a restrictTo parameter which controls what workspaces the configuration will apply to. If no restrictTo is specified, then the configuration will apply globally to every workspace.

conformance.config.jsonc
{
  "overrides": [
    {
      // NOTE: No `restrictTo` is specified here so this applies globally.
      "rules": {},
    },
  ],
}

Conformance configuration can be applied to specific workspaces using either the name of the workspace or the directory of the workspace on the restrictTo field:

  • Use the workspaces field, which accepts a list of workspace names:
    conformance.config.jsonc
    {
      "overrides": [
        {
          "restrictTo": {
            "workspaces": ["eslint-config-custom"],
          },
          "rules": {},
        },
      ],
    }
  • Use the directories field to specify a directory. All workspaces that live under that directory will be matched:
    conformance.config.json
    {
      "overrides": [
        {
          "restrictTo": {
            "directories": ["configs/"],
          },
          "rules": {},
        },
      ],
    }
    This will match configs/tsconfig and configs/eslint-config-custom.
  • Set the root field to true to match the root of the repository:
    conformance.config.jsonc
    {
      "overrides": [
        {
          "restrictTo": {
            "root": true,
          },
          "rules": {},
        },
      ],
    }

If multiple overrides are specified that affect the same workspace, the configurations will be unioned together. If there are conflicts between the overrides, the last specified value will be used.

To enable or disable a Conformance rule, use the rules field. This field is an object literal where the keys are the name of the rule and the values are booleans or another object literal containing a rule-specific configuration.

For example, this configuration will disable the TYPESCRIPT_CONFIGURATION rule:

conformance.config.jsonc
{
  "overrides": [
    {
      "rules": {
        "TYPESCRIPT_CONFIGURATION": false,
      },
    },
  ],
}

All rules are enabled by default unless explicitly disabled in the config.

Some Conformance rules can be configured to alter behavior based on the project settings. Instead of a boolean being provided in the rules configuration, an object literal could be passed with the configuration for that rule.

For example, this configuration will require a specific list of ESLint plugins in every workspace:

conformance.config.jsonc
{
  "overrides": [
    {
      "rules": {
        "ESLINT_CONFIGURATION": {
          "requiredPlugins": ["@typescript-eslint"],
        },
      },
    },
  ],
}

If you want to specify additional information or link to project-specific documentation, you can add custom error messages to the output of any conformance rule. These messages can be added globally to all rules or on a per-rule basis.

To add an error message to the output of all rules, add globalErrorMessage to the configuration section of the override:

conformance.config.jsonc
{
  "overrides": [
    {
      "configuration": {
        "globalErrorMessage": "See link_to_docs for more information.",
      },
    },
  ],
}

To add an error message to the output of one specific rule, add an entry for that test to the additionalErrorMessages field:

conformance.config.jsonc
{
  "overrides": [
    {
      "configuration": {
        "additionalErrorMessages": {
          "TYPESCRIPT_CONFIGURATION": "Please see project_link_to_typescript_docs for more information.",
        },
      },
    },
  ],
}
Last updated on February 21, 2024