Configuration

Root configuration

oneRepo configuration files can be any flavor of JavaScript or TypeScript, as long as they are parseable and have a valid default export. The only requirement for your repository’s root config is that root must be set to true:

export default {
  root: true,
};

import type { Config } from 'onerepo';

export default {
  root: true,
} satisfies Config;

module.exports = {
  root: true,
};

RootConfig<CustomLifecycles>

Type: object

Setup configuration for the root of the repository.

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

root

Type: true

Must be set to true in order to denote that this is the root of the repository.

changes?

optional changes: object

Type declaration

changes.filenames?

optional filenames: "hash" | "human"

Default: 'hash'

To generate human-readable unique filenames for change files, ensure human-id is installed.

changes.prompts?

optional prompts: "guided" | "semver"

Default: 'guided'

Change the prompt question & answer style when adding change entries.

'guided': Gives more detailed explanations when release types.
'semver': A simple choice list of semver release types.

changes.formatting?

optional formatting: object

Type declaration

Default: {}

Override some formatting strings in generated changelog files.

export default {
  root: true,
  changes: {
    formatting: {
      commit: '([${ref.short}](https://github.com/paularmstrong/onerepo/commit/${ref}))',
      footer:
        '> Full changelog [${fromRef.short}...${throughRef.short}](https://github.com/my-repo/commits/${fromRef}...${throughRef})',
    },
  },
};

changes.formatting.commit?

optional commit: string

Default: '(${ref.short})'

Format how the commit ref will appear at the end of the first line of each change entry.

Available replacement strings:

Replacement	Description
`${ref.short}`	8-character version of the commit ref
`${ref}`	Full commit ref

changes.formatting.footer?

optional footer: string

Default: '_View git logs for full change list._'

Format the footer at the end of each version in the generated changelog files.

Available replacement strings:

Replacement	Description
`${fromRef.short}`	8-character version of the first commit ref in the version
`${fromRef}`	Full commit ref of the first commit in the version
`${through.short}`	8-character version of the last commit ref in the version
`${through}`	Full commit ref of the last commit in the version
`${version}`	New version string

codeowners?

optional codeowners: Record<string, string[]>

Default: {}

Map of paths to array of owners.

When used with the codeowners commands, this configuration enables syncing configurations from Workspaces to the appropriate root level CODEOWNERS file given your vcsProvider as well as verifying that the root file is up to date.

export default {
  root: true,
  codeowners: {
    '*': ['@my-team', '@person'],
    scripts: ['@infra-team'],
  },
};

commands?

optional commands: object

Configuration for custom commands.

Type declaration

commands.directory?

optional directory: string | false

Default: 'commands'

A string to use as filepaths to subcommands. We’ll look for commands in all Workspaces using this string. If any are found, they’ll be available from the CLI.

export default {
  root: true,
  commands: {
    directory: 'commands',
  },
};

Given the preceding configuration, commands will be searched for within the commands/ directory at the root of the repository as well as a directory of the same name at the root of each Workspace:

<root>/commands/*
<root>/<workspaces>/commands/*

commands.ignore?

optional ignore: RegExp

Default: /(/__\w+__/|\.test\.|\.spec\.|\.config\.)/

Prevent reading matched files in the commands.directory as commands.

When writing custom commands and Workspace-level subcommands, we may need to ignore certain files like tests, fixtures, and other helpers. Use a regular expression here to configure which files will be ignored when oneRepo parses and executes commands.

export default {
  root: true,
  commands: {
    ignore: /(/__\w+__/|\.test\.|\.spec\.|\.config\.)/,
  },
};

dependencies?

optional dependencies: object

Type declaration

dependencies.mode?

optional mode: "strict" | "loose" | "off"

Default: 'loose'

The dependency mode will be used for node module dependency management and verification.

off: No validation will occur. Everything goes.
loose: Reused third-party dependencies will be required to have semantic version overlap across unique branches of the Graph.
strict: Versions of all dependencies across each discrete Workspace dependency tree must be strictly equal.

dependencies.dedupe?

optional dedupe: boolean

Default: true

When modifying dependencies using the one dependencies command, a dedupe will automatically be run to reduce duplicate package versions that overlap the requested ranges. Set this to false to disable this behavior.

head?

optional head: string

Default: 'main'

The default branch of your repo? Probably main, but it might be something else, so it’s helpful to put that here so that we can determine changed files accurately.

export default {
  root: true,
  head: 'develop',
};

ignore?

optional ignore: string[]

Default: []

Array of fileglobs to ignore when calculating the changed Workspaces.

Periodically we may find that there are certain files or types of files that we know for a fact do not affect the validity of the repository or any code. When this happens and the files are modified, unnecessary tasks and processes will be spun up that don’t have any bearing on the outcome of the change.

To avoid extra processing, we can add file globs to ignore when calculated the afected Workspace graph.

export default {
  root: true,
  ignore: ['.github/\*'],
};

meta?

optional meta: Record<string, unknown>

Default: {}

A place to put any custom information or configuration. A helpful space for you to extend Workspace configurations for your own custom commands.

export default {
  root: true,
  meta: {
    tacos: 'are delicious',
  },
};

plugins?

optional plugins: Plugin[]

Default: []

Add shared commands and extra handlers. See the official plugin list for more information.

import { eslint } from '@onerepo/plugins-eslint';
export default {
  plugins: [eslint()],
};

tasks?

optional tasks: TaskConfig<CustomLifecycles>

Default: {}

Globally defined tasks per lifecycle. Tasks defined here will be assumed to run for all changes, regardless of affected Workspaces. Refer to the tasks command specifications for details and examples.

taskConfig?

optional taskConfig: object

Optional extra configuration for tasks.

Type declaration

taskConfig.lifecycles?

optional lifecycles: CustomLifecycles[]

Default: []

Additional task lifecycles to make available.

See Lifecycle | `Lifecycle` for a list of pre-configured lifecycles.

export default {
  root: true,
  tasks: {
    lifecycles: ['deploy-staging'],
  },
};

taskConfig.stashUnstaged?

optional stashUnstaged: CustomLifecycles extends string ? Lifecycle | CustomLifecycles : Lifecycle[]

Default: ['pre-commit']

Stash unstaged changes before running these tasks and re-apply them after the task has completed.

export default {
  root: true,
  tasks: {
    stashUnstaged: ['pre-commit', 'post-checkout'],
  },
};

templateDir?

optional templateDir: string

Default: './config/templates'

Folder path for generate command’s templates.

validation?

optional validation: object

Type declaration

validation.schema?

optional schema: string | null

Default: undefined

File path for custom Graph and configuration file validation schema.

vcs?

optional vcs: object

Version control system settings.

Type declaration

vcs.autoSyncHooks?

optional autoSyncHooks: boolean

Default: false

Automatically set and sync oneRepo-managed git hooks. Change the directory for your git hooks with the vcs.hooksPath setting. Refer to the Git hooks documentation to learn more.

export default {
  root: true,
  vcs: {
    autoSyncHooks: false,
  },
};

vcs.hooksPath?

optional hooksPath: string

Default: '.hooks'

Modify the default git hooks path for the repository. This will automatically be synchronized via one hooks sync unless explicitly disabled by setting vcs.autoSyncHooks to false.

export default {
  root: true,
  vcs: {
    hooksPath: '.githooks',
  },
};

vcs.provider?

optional provider: "github" | "gitlab" | "bitbucket" | "gitea"

Default: 'github'

The provider will be factored in to various commands, like CODEOWNERS generation.

export default {
  root: true,
  vcs: {
    provider: 'github',
  },
};

visualizationUrl?

optional visualizationUrl: string

Default: 'https://onerepo.tools/visualize/'

Override the URL used to visualize the Graph. The Graph data will be attached the the g query parameter as a JSON string of the DAG, compressed using zLib deflate.

Defined in

config-root.d.ts:7

Workspace configurations

Workspace configuration files are not required unless a workspace has explicit tasks, codeowners, or other needs. Workspace configuration files share the same name and format as the root configuration and are able to be any flavor of JavaScript or TypeScript:

export default {
  codeowners: {},
  tasks: {},
};

import type { Config } from 'onerepo';

export default {
  codeowners: {},
  tasks: {},
} satisfies Config;

module.exports = {
  codeowners: {},
  tasks: {},
};

WorkspaceConfig<CustomLifecycles>

Type: object

Type Parameters

Type Parameter	Default type
`CustomLifecycles` extends `string` \| `void`	`void`

codeowners?

optional codeowners: Record<string, string[]>

Default: {}.

Map of paths to array of owners.

When used with the codeowners commands, this configuration enables syncing configurations from Workspaces to the appropriate root level CODEOWNERS file given your RootConfig.vcs.provider as well as verifying that the root file is up to date.

export default {
  codeowners: {
    '*': ['@my-team', '@person'],
    scripts: ['@infra-team'],
  },
};

commands?

optional commands: object

Configuration for custom commands. To configure the commands directory, see RootConfig commands.directory.

Type declaration

commands.passthrough

Type: Record<string, { description: string; command: string; }>
Default: {}

Enable commands from installed dependencies. Similar to running npx <command>, but pulled into the oneRepo CLI and able to be limited by Workspace. Passthrough commands must have helpful descriptions.

export default {
  commands: {
    passthrough: {
      astro: { description: 'Run Astro commands directly.' },
      start: { description: 'Run the Astro dev server.', command: 'astro dev --port=8000' },
    },
  },
};

meta?

optional meta: Record<string, unknown>

Default: {}

A place to put any custom information or configuration. A helpful space for you to extend Workspace configurations for your own custom commands.

export default {
  meta: {
    tacos: 'are delicious',
  },
};

tasks?

optional tasks: TaskConfig<CustomLifecycles>

Default: {}

Tasks for this Workspace. These will be merged with global tasks and any other affected Workspace tasks. Refer to the tasks command specifications for details and examples.

Defined in

config-workspace.d.ts:5