> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript configuration

> Write your configuration as a .coderabbit.config.ts file to share fragments across repositories and adapt settings to each pull request.

`.coderabbit.config.ts` lets you author configuration as code. You get autocomplete and type checking, shared fragments, and settings that change with the pull request or the way a review starts. For example, you can use a stricter profile for hotfixes and a different one for local CLI reviews.

Start with `.coderabbit.yaml`, which is simpler to write and review. Switch to TypeScript when static YAML no longer fits, for example when you generate many path instructions from a list, change settings by the pull request's base branch or changed files, or combine shared fragments with settings of your own.

## When CodeRabbit uses the TypeScript file

A committed `.coderabbit.yaml` or `.coderabbit.yml` always wins. If either exists, CodeRabbit ignores the TypeScript file. Exactly one file in a repository is used, and the files never merge.

> [!WARNING]
>
> Delete the YAML file to activate `.coderabbit.config.ts`. Then confirm with `@coderabbitai configuration`.

The same rule applies in the [central configuration](https://docs.coderabbit.ai/configuration/central.md) repository. A TypeScript file takes the same layer as the YAML file it replaces, so it takes part in [inheritance](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md) and global overrides like any YAML file.

## Install the SDK

The SDK is optional. CodeRabbit evaluates the file on the server with its own implementations of `defineConfig`, `mergeConfig` and `includeRemote`, so the file behaves the same with or without the package. Installing it adds types, editor autocomplete, and type checking in CI. Stable releases go to the default `latest` tag, so install the package without a tag.

```bash npm theme={null}
npm install --save-dev @coderabbitai/config
```

```bash pnpm theme={null}
pnpm add --save-dev @coderabbitai/config
```

```bash yarn theme={null}
yarn add --dev @coderabbitai/config
```

```bash bun theme={null}
bun add --dev @coderabbitai/config
```

The [TypeScript configuration reference](https://docs.coderabbit.ai/configuration/typescript-reference.md#api-reference) lists every function and type the SDK exports.

## Write a configuration

The default export is a configuration object or a function that returns one, and the function can be `async`.

For type checking, wrap it in `defineConfig`. It returns its argument unchanged, so evaluation works without it.

> [tab] TypeScript
>
> ```ts .coderabbit.config.ts theme={null}
> import { defineConfig } from "@coderabbitai/config"
>
> export default defineConfig({
>   language: "en-US",
>   reviews: { profile: "chill", poem: false },
> })
> ```

> [tab] Equivalent YAML
>
> ```yaml .coderabbit.yaml theme={null}
> language: "en-US"
> reviews:
>   profile: "chill"
>   poem: false
> ```

CodeRabbit validates the result against the same schema as `.coderabbit.yaml`. See the [configuration reference](https://docs.coderabbit.ai/reference/configuration.md) for every setting.

## Adapt configuration to the pull request

Pass a function to `defineConfig` to receive a context object that describes the platform, repository and pull request. Annotate the function's return type with `CodeRabbitConfig`. Without the annotation, type checking can reject a valid value that the function returns, such as a profile name.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, type CodeRabbitConfig } from "@coderabbitai/config"

export default defineConfig((ctx): CodeRabbitConfig => ({
  reviews: {
    profile: ctx.pr?.authorAssociation === "FIRST_TIME_CONTRIBUTOR" ? "assertive" : "chill",
  },
}))
```

`ctx.pr` is `null` for events with no pull request, so guard with `ctx.pr?.`. A field that can't be resolved degrades instead of failing the configuration.

| Field | What it holds |
| - | - |
| `ctx.invocation.source` | `"cli"` for a local `coderabbit review`, `"review"` for every other start |
| `ctx.platform` | The platform or surface, such as `GitHub`, `GitLab`, `Azure DevOps`, `cli` or `vscode` |
| `ctx.repo` | `owner`, `name`, `fullName`, `language`, `isPrivate`, `isSelfHosted`, `defaultBranch`, `topics`, `customProperties` |
| `ctx.org` | `{ name }` of the owning organization, or `null` |
| `ctx.pr` | `number`, `title`, `baseBranch`, `headBranch`, `author`, `authorAssociation`, `authorGroups`, `labels`, `isDraft`, `changedFiles` |

Four fields come from lookups on the platform: `ctx.pr.authorGroups`, `ctx.pr.changedFiles`, `ctx.repo.topics` and `ctx.repo.customProperties`. Each carries a `status`. Rely on the values only when `status` is `"resolved"`, because an empty list with any other status means "unknown", not "none". The [TypeScript configuration reference](https://docs.coderabbit.ai/configuration/typescript-reference.md#context-object) gives the type and meaning of every field and status.

### Review hotfixes more strictly

Detect a hotfix from the title, the branch name or a label.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, type CodeRabbitConfig, type CodeRabbitContext } from "@coderabbitai/config"

function isHotfix(ctx: CodeRabbitContext): boolean {
  const pr = ctx.pr
  if (!pr) return false
  return (
    /hotfix/i.test(pr.title) ||
    pr.headBranch.startsWith("hotfix/") ||
    pr.labels.some((label) => label.toLowerCase() === "hotfix")
  )
}

export default defineConfig((ctx): CodeRabbitConfig => ({
  reviews: {
    profile: isHotfix(ctx) ? "assertive" : "chill",
    poem: !isHotfix(ctx),
  },
}))
```

### Choose settings by the author's team

On GitHub and GitLab, `ctx.pr.authorGroups` lists the author's teams or groups.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, type CodeRabbitConfig } from "@coderabbitai/config"

export default defineConfig((ctx): CodeRabbitConfig => {
  const authorGroups = ctx.pr?.authorGroups
  const groupPaths =
    authorGroups?.status === "resolved"
      ? authorGroups.groups.map((group) => group.fullPath)
      : []

  return {
    reviews: {
      profile: groupPaths.includes("acme/platform-usa") ? "assertive" : "chill",
    },
  }
})
```

On GitHub, the list holds the author's teams in the repository's organization that CodeRabbit can see. On GitLab, it holds the author's direct group memberships under the repository's top-level group. Inherited and shared memberships aren't included.

### Use repository topics and custom properties

On GitHub, select settings by repository topics and custom properties instead of keeping a separate file per repository.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, type CodeRabbitConfig } from "@coderabbitai/config"

export default defineConfig((ctx): CodeRabbitConfig => {
  const topics = ctx.repo.topics.status === "resolved" ? ctx.repo.topics.names : []
  const properties = ctx.repo.customProperties.status === "resolved" ? ctx.repo.customProperties.values : {}
  const isCriticalService = topics.includes("critical") && properties.repo_type === "service"

  return {
    reviews: {
      profile: isCriticalService ? "assertive" : "chill",
    },
  }
})
```

`topics.names` is a sorted list of topic names. `customProperties.values` is keyed by property name, and each value is a string, a list of strings, or `null`.

### Use a different profile for CLI reviews

`ctx.invocation.source` tells a local [CodeRabbit CLI](https://docs.coderabbit.ai/cli/index.md) review apart from every other review. Use it instead of `ctx.platform` when a setting depends on whether the CLI started the review.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, type CodeRabbitConfig } from "@coderabbitai/config"

export default defineConfig((ctx): CodeRabbitConfig => ({
  reviews: {
    profile: ctx.invocation.source === "cli" ? "chill" : "assertive",
    poem: ctx.invocation.source === "cli",
  },
}))
```

To choose settings by the files a pull request changes, see [Vary settings by changed paths](https://docs.coderabbit.ai/configuration/guides/monorepo.md#vary-settings-by-changed-paths).

## Generate settings in code

Build repetitive settings from data instead of writing each entry by hand.

```ts .coderabbit.config.ts theme={null}
import { defineConfig } from "@coderabbitai/config"

const teams = ["api", "web", "worker"]

export default defineConfig({
  reviews: {
    path_instructions: teams.map((team) => ({
      path: `packages/${team}/**`,
      instructions: `Follow the ${team} team's conventions.`,
    })),
  },
})
```

## Compose configuration from fragments

Split shared settings into fragments and combine them.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, includeRemote, mergeConfig } from "@coderabbitai/config"

export default defineConfig(
  mergeConfig(
    includeRemote({ path: "base.ts" }),
    { reviews: { profile: "assertive" } },
  ),
)
```

* **Local files.** Use relative imports, such as `import security from "./coderabbit/security"`. A path resolves against the importing file, at the commit under review. YAML imports (`.yaml`, `.yml`) give you the parsed object. Imports can't leave the repository root.
* **Imports without an extension.** CodeRabbit tries `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`, `.yaml` and `.yml` in that order, then the same extensions under `<path>/index`. Each try counts toward the file fetch limit.
* **`includeRemote`.** Pulls a fragment from another repository. When you omit `repo`, it reads the `coderabbit` repository. `ref` pins a branch, tag or commit; without it, the default branch applies and edits propagate. A relative import inside a remote fragment resolves in that fragment's repository and `ref`. See [Read a fragment from another repository](#read-a-fragment-from-another-repository) for the access rules.
* **Build-time only.** The argument of `includeRemote` must be an inline object literal with string-literal values. CodeRabbit resolves every call while it bundles the file, before any of your code runs.
* **`mergeConfig`.** Deep-merges fragments from left to right. An omitted key never overwrites a value, so an empty object `{}` adds nothing.

| Merge type | Objects | Arrays | Scalars |
| - | - | - | - |
| `mergeConfig` | Merge recursively | Concatenated in order | Later fragment wins |
| Inheritance | Merge recursively | Child entries first; parent entries with the same key are dropped | Child wins |
| Global overrides | Merge recursively | Override entries first; base entries with a different key are kept | Override wins |

Because `mergeConfig` concatenates arrays, two `path_instructions` entries for the same glob both stay in the result. See [Inheritance and merging](https://docs.coderabbit.ai/configuration/inheritance-and-merging.md) for the full rules.

### Read a fragment from another repository

Set `repo` to read a fragment from a repository other than `coderabbit`, and `ref` to pin a branch, tag or commit.

```ts .coderabbit.config.ts theme={null}
import { defineConfig, includeRemote, mergeConfig } from "@coderabbitai/config"

export default defineConfig(
  mergeConfig(
    includeRemote({ repo: "acme/coderabbit-shared", path: "base.ts", ref: "v1" }),
    { reviews: { profile: "assertive" } },
  ),
)
```

`includeRemote` follows the same access rules as [`remote_config`](https://docs.coderabbit.ai/configuration/central#who-can-read-a-shared-repository):

* **Same owner.** The repository must have the same owner as the reviewed repository. A bare name, such as `coderabbit-shared`, resolves under that owner. On GitLab, `repo` is the full `group/subgroup/project` path, and any namespace the CodeRabbit connection can read works.
* **Installation access.** The CodeRabbit installation must be able to read the repository.
* **Pull request branches.** When the configuration comes from a pull request branch, the pull request author and the person who started the review must both be able to read the repository.
* **Fail closed.** If access is denied or can't be confirmed, the configuration fails instead of skipping the fragment.
* **Exempt repositories.** The reviewed repository and the `coderabbit` repository skip the same-owner and pull request branch checks.

### Layer settings by condition

Pass `condition ? fragment : {}` to `mergeConfig` to add settings only when the condition holds. This example adds stricter settings for pull requests into `main` or a release branch.

```ts .coderabbit.config.ts theme={null}
import {
  defineConfig,
  mergeConfig,
  type CodeRabbitConfig,
  type CodeRabbitContext,
} from "@coderabbitai/config"

const base = {
  reviews: {
    profile: "chill",
    tools: { gitleaks: { enabled: true } },
  },
} satisfies CodeRabbitConfig

const targetsRelease = (ctx: CodeRabbitContext) =>
  /^(main|release\/.*)$/.test(ctx.pr?.baseBranch ?? "")

export default defineConfig((ctx) =>
  mergeConfig(
    base,
    targetsRelease(ctx)
      ? {
          reviews: {
            profile: "assertive",
            assess_linked_issues: true,
          },
        }
      : {},
  ),
)
```

### Choose a remote fragment by condition

An `includeRemote` call can sit anywhere in an expression, including either branch of a condition. To replace the whole configuration, choose between two calls:

```ts .coderabbit.config.ts theme={null}
import { defineConfig, includeRemote } from "@coderabbitai/config"

export default defineConfig((ctx) =>
  ctx.pr?.labels.includes("hotfix")
    ? includeRemote({ path: "hotfix.ts" })
    : includeRemote({ path: "base.ts" }),
)
```

To layer the fragment onto shared defaults instead, put the condition inside `mergeConfig`: `ctx.pr?.labels.includes("hotfix") ? includeRemote({ path: "hotfix.ts" }) : {}`.

> [!WARNING]
>
> CodeRabbit fetches every `includeRemote` file while it bundles the configuration, including the file in a branch that the condition doesn't take. If that file is missing or unreadable, the whole configuration fails. Every fetch also counts toward the file fetch limit.

## How CodeRabbit evaluates the file

```mermaid theme={null}
flowchart TD
  A[Discovery] --> B[Bundling]
  B --> C[Sandboxed evaluation]
  C --> D[Validation]
  D --> E[Resolution]
```

Discovery finds the file in the repository under review. Bundling fetches the entry file and every include. Evaluation runs in a sandbox with no network and no environment secrets. Validation checks the output against the YAML schema. Resolution then applies inheritance, web interface settings and global overrides.

| Limit | Value |
| - | - |
| Evaluation time | 10 seconds |
| File fetches per configuration | 100 attempts |
| Total source, entry file and includes | 2 MB |
| Output | 5 MB |
| Allowed imports | `@coderabbitai/config`, relative paths, `includeRemote` |

## Availability

TypeScript configuration has no plan requirement. CodeRabbit reads `.coderabbit.config.ts` on every supported Git platform, in [CLI reviews](https://docs.coderabbit.ai/configuration/local-reviews.md), and on [self-hosted CodeRabbit](https://docs.coderabbit.ai/configuration/self-hosted.md). The platform decides which context lookups resolve:

| Context field | GitHub and GitHub Enterprise Server | GitLab | Azure DevOps and Bitbucket | CLI reviews |
| - | - | - | - | - |
| `ctx.pr.authorGroups` | Organization teams | Direct group memberships | `unsupported` | `unsupported` |
| `ctx.repo.topics`, `ctx.repo.customProperties` | Yes | `unsupported` | `unsupported` | `unsupported` |
| `ctx.pr.authorAssociation` | Yes | `null` | `null` | `null` |

On GitHub Enterprise Server, a version without the topics or custom properties API reports `unavailable`.

## Troubleshoot TypeScript configuration

> [accordion] The file is ignored
>
> A `.coderabbit.yaml` or `.coderabbit.yml` exists. Delete it and confirm with `@coderabbitai configuration`.

> [accordion] A function passed to defineConfig fails type checking
>
> Annotate the return type, as in `defineConfig((ctx): CodeRabbitConfig => ({ ... }))`, or `Promise<CodeRabbitConfig>` for an `async` function. Without the annotation, TypeScript can widen a value such as `"chill"` to `string` and reject it. A function that returns the result of `mergeConfig` needs no annotation.

> [accordion] Unsupported import
>
> Only the SDK, relative includes and `includeRemote` are allowed. npm packages and Node built-ins fail at bundle time.

> [accordion] includeRemote needs a literal argument
>
> The argument can't be computed. Write each call with a literal `path`, and literal `repo` and `ref` when you set them. To choose between files, use a condition that selects between two calls.

> [accordion] An include can't be resolved
>
> Check the path, repository and pinned `ref`, including includes in a branch your condition doesn't take. For configuration on a pull request branch, the author and the person who started the review must both be able to read the repository.

> [accordion] Evaluation timed out
>
> Evaluation has a 10-second limit. Remove heavy computation.

> [accordion] The file must resolve to an object
>
> Add a default export that is an object or a function that returns one.

## What's next

> [card] [TypeScript configuration reference](https://docs.coderabbit.ai/configuration/typescript-reference.md)
>
> Look up every context field, status value and SDK export.

> [card] [Central configuration](https://docs.coderabbit.ai/configuration/central.md)
>
> Share fragments from the `coderabbit` repository.

> [card] [Validate and test a change](https://docs.coderabbit.ai/configuration/guides/validate-and-test.md)
>
> Test a configuration change before you merge it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.