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 parameter	Value
`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?

Type: Object

changes.filenames?

Type: "hash" | "human"
Default: 'hash'

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

changes.prompts?

Type: "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?

Type: Object
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?

Type: 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?

Type: 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?

Type: 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?

Type: Object

Configuration for custom commands.

commands.directory?

Type: 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?

Type: 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?

Type: Object

dependencies.mode?

Type: "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?

Type: 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?

Type: 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?

Type: 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?

Type: 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?

Type: 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?

Type: 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?

Type: Object

Optional extra configuration for tasks.

taskConfig.lifecycles?

Type: 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?

Type: 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?

Type: string
Default: './config/templates'

Folder path for generate command’s templates.

validation?

Type: Object

validation.schema?

Type: string | null
Default: undefined

File path for custom Graph and configuration file validation schema.

vcs?

Type: Object

Version control system settings.

vcs.autoSyncHooks?

Type: 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?

Type: 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?

Type: "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?

Type: 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.

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 parameter	Value
`CustomLifecycles` extends `string` \| `void`	`void`

codeowners?

Type: 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?

Type: Object

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

commands.passthrough

Type: Record<string, Object>
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?

Type: 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?

Type: 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.