@nx/owners

This package is part of the Nx Powerpack extensions for Nx.

This plugin provides the ability to configure and maintain codeowners for projects in Nx workspaces.

Usage

Use of this package is governed by the following LICENSE. Please be sure to read through the license carefully before using this plugin. This license is also included in the package in a LICENSE file.

Use Case

The atomic unit of code in an Nx workspace is a project. Tasks, module boundaries and the Nx graph all train us to conceptualize the workspace as a collection of projects. The CODEOWNERS file, however, requires you to switch from a project mental model to a more low-level definition based on the folder structure of your workspace. The @nx/powerpack-owners plugin enables you to stay in the mental model that your workspace is a collection of projects as you define the ownership rules for your workspace. Nx will take care of compiling the project ownership rules into file-based ownership rules that GitHub, Bitbucket or GitLab can understand in the CODEOWNERS file.

Getting Started

Initialize the plugin in your workspace:

npx nx g @nx/owners:init

This registers the @nx/owners plugin in nx.json, sets up the sync generator, and infers the correct VCS format from your workspace.

After configuring your ownership patterns (see below), generate or update the CODEOWNERS file:

npx nx sync

Configuration

Ownership is configured in the owners property of nx.json. The simplest form enables the feature and delegates entirely to project.json files:

{
  "owners": true
}

For root-level configuration, provide an object:

{
  "owners": {
    "format": "github",
    "patterns": []
  }
}

Root Config Options

| Property | Type | Default | Description | | ------------ | ----------------------------------- | ------------------------------------------- | ----------------------------------------------------- | | format | "github" "gitlab" "bitbucket" | "github" | VCS provider format | | outputPath | string | Based on format (e.g. .github/CODEOWNERS) | Path to the generated CODEOWNERS file | | prefix | string | — | Prefix applied to all owner strings (e.g. "@MyOrg") | | patterns | Array | [] | Ownership pattern entries (see below) | | sections | Array | — | GitLab-only sections with optional approvals |

Patterns

Each entry in the patterns array defines an ownership rule. There are three pattern types:

Project Patterns

Assign owners to entire projects using Nx project name patterns.

{
  "owners": {
    "patterns": [
      {
        "projects": ["ui-*"],
        "owners": ["@frontend-team"]
      },
      {
        "projects": ["api-*", "data-*"],
        "owners": ["@backend-team"]
      }
    ]
  }
}

Generates entries like:

/libs/ui-buttons/ @frontend-team
/libs/ui-dropdown/ @frontend-team
/apps/api-gateway/ @backend-team

File Patterns

Assign owners to files matching glob patterns across the entire workspace.

{
  "owners": {
    "patterns": [
      {
        "files": ["*.ts"],
        "owners": ["@typescript-team"]
      },
      {
        "files": ["**/jest.config.ts", "**/tsconfig*.json"],
        "owners": ["@platform-team"]
      }
    ]
  }
}

Combined Project + File Patterns

Assign owners to specific files scoped to matched projects. When both projects and files are provided, the file patterns are evaluated relative to each matched project root instead of the workspace root.

{
  "owners": {
    "patterns": [
      {
        "projects": ["ui-*"],
        "owners": ["@frontend-team"]
      },
      {
        "projects": ["ui-*"],
        "files": ["project.json", "tsconfig.json"],
        "owners": ["@ops-team"]
      }
    ]
  }
}

Generates:

/libs/ui-buttons/ @frontend-team
/libs/ui-buttons/project.json @ops-team
/libs/ui-buttons/tsconfig.json @ops-team

/libs/ui-dropdown/ @frontend-team
/libs/ui-dropdown/project.json @ops-team
/libs/ui-dropdown/tsconfig.json @ops-team

This is useful when you want a team to own specific config files across a set of projects without affecting ownership of the rest of the project.

Glob patterns also work in the files array:

{
  "projects": ["ui-*"],
  "files": ["**/*.config.json"],
  "owners": ["@config-team"]
}

Project-Level Configuration

Individual projects can define their own ownership rules in project.json. These take precedence over root config for the same file patterns.

{
  "name": "ui-buttons",
  "owners": {
    "**/*": ["@ui-buttons-team"],
    "project.json": ["@project-json-owner"]
  }
}

The **/* pattern assigns a default owner for the entire project, overriding whatever the root config specifies. Specific file patterns (like project.json) further override for those paths.

When combined with root-level combined project + file patterns, project-level entries always win for the same file pattern:

// nx.json
{
  "owners": {
    "patterns": [
      { "projects": ["ui-*"], "files": ["project.json"], "owners": ["@ops-team"] }
    ]
  }
}

// libs/ui-buttons/project.json
{
  "name": "ui-buttons",
  "owners": {
    "project.json": ["@ui-buttons-lead"]
  }
}

Result for ui-buttons:

/libs/ui-buttons/project.json @ui-buttons-lead

Advanced Options

Owner Prefix

Apply a prefix to all owner strings:

{
  "owners": {
    "prefix": "@MyOrg",
    "patterns": [
      {
        "projects": ["ui-*"],
        "owners": ["frontend-team"]
      }
    ]
  }
}

Generates @MyOrg/frontend-team. Individual patterns can override the prefix or opt out:

{
  "projects": ["shared-*"],
  "owners": ["platform-team"],
  "prefix": "@DifferentOrg"
}

{
  "projects": ["external-*"],
  "owners": ["[email protected]"],
  "applyPrefix": false
}

Explicitly Unowned Files

Set owners to false to mark files or projects as explicitly having no owner. These entries are written last in the CODEOWNERS file:

{
  "files": ["**/generated/**"],
  "owners": false
}

Note: Bitbucket does not support owners: false.

Descriptions

Add a description to any pattern to include a comment above the generated entry:

{
  "projects": ["ui-*"],
  "owners": ["@frontend-team"],
  "description": "Frontend team owns all UI libraries"
}

GitLab Sections

When using the gitlab format, you can group patterns into sections with optional approval requirements:

{
  "owners": {
    "format": "gitlab",
    "sections": [
      {
        "name": "Frontend",
        "defaultOwners": ["@frontend-team"],
        "patterns": [{ "projects": ["ui-*"], "owners": ["@ui-team"] }]
      },
      {
        "name": "Security",
        "numberOfRequiredApprovals": 2,
        "patterns": [{ "files": ["**/auth/**"], "owners": ["@security-team"] }]
      }
    ],
    "patterns": []
  }
}