Configuration File

Learn how to configure Versu for your project.

Basic Structure

Versu uses cosmiconfig to load configuration from various file formats. It supports several file types, including Typescript and JavaScript files. The configuration file should export an object with the following structure:

versu.config.ts

import type { VersuConfig } from "@versu/core";

const config: VersuConfig = {
  // Your configuration options here
};

export default config;

Configuration Options

plugins (optional)

An array of plugins to use. Each plugin can be specified as a string (the package name).

Versu can work with zero configuration by automatically searching for installed plugins.

However, for performance and reliability reasons, it's recommended to explicitly specify the plugins you want to use in your configuration file. This helps avoid issues with plugin discovery and ensures that Versu loads the correct plugins for your project.

versu.config.js

export default {
  plugins: [
    "@versu/plugin-gradle",
    //... other plugins
  ],
  // Other configuration options
};

versioning (optional)

Defines how version bumps are determined based on commit types and dependency updates. This configuration allows you to specify which commit types trigger which version bumps, as well as how to handle unknown commit types and breaking changes. You can also customize how version bumps cascade through dependencies.

versu.config.js

export default {
  // Other configuration options
  versioning: {
    breakingChange: {
      // major, minor, patch, or none
      stable: "major",
      // premajor, preminor, prepatch, prerelease, or none
      prerelease: "premajor",
    },
    unknownCommitType: {
      stable: "patch",
      prerelease: "prepatch",
    },
    commitTypes: {
      feat: {
        stable: "minor",
        prerelease: "preminor",
      },
      fix: {
        stable: "patch",
        prerelease: "prepatch",
      },
      perf: {
        stable: "patch",
        prerelease: "prepatch",
      },
      refactor: {
        stable: "patch",
        prerelease: "prepatch",
      },
      docs: {
        stable: "none",
        prerelease: "none",
      },
      test: {
        stable: "none",
        prerelease: "none",
      },
      chore: {
        stable: "none",
        prerelease: "none",
      },
      style: {
        stable: "none",
        prerelease: "none",
      },
      ci: {
        stable: "none",
        prerelease: "none",
      },
      build: {
        stable: "none",
        prerelease: "none",
      },
      //... other custom commit types
    },
    cascadeRules: {
      // Each rule set can also be the shorthand string "match",
      // meaning dependents get the same bump as their dependency
      stable: {
        // major, minor, patch, or none
        major: "major",
        minor: "minor",
        patch: "patch",
      },
      prerelease: {
        // premajor, preminor, prepatch, prerelease, or none
        premajor: "premajor",
        preminor: "preminor",
        prepatch: "prepatch",
        prerelease: "prerelease",
      },
    },
  },
};

Defaults

Unless overridden, every recognized commit type triggers at least a patch bump (feat triggers minor; breaking changes trigger major), unknown types fall back to unknownCommitType (patch), and cascade bumps match the dependency's bump level. The example above deviates from the defaults by mapping non-code types (docs, test, chore, style, ci, build) to "none".

changelog (optional)

The changelog configuration allows you to customize how changelogs are generated. You can specify different configurations for the root project and for individual modules if you're working in a monorepo setup.

Versu uses conventional-changelog-writer under the hood, so the options you provide here will be passed to the underlying changelog generation process. This allows you to customize the output of your changelogs based on your specific needs.

versu.config.js

export default {
  // Other configuration options
  changelog: {
    // Changelog configuration options
    root: {
      // Root changelog configuration (optional)
      context: { /* */ }, // Context<Commit> (1)
      options: { /* */ }, // Options<Commit> (2)
    },
    module: {
      // Module changelog configuration (optional)
      context: { /* */ }, // Context<Commit> (1)
      options: { /* */ }, // Options<Commit> (2)
    },
  },
};

¹ The context property allows you to provide additional information about the commits being processed. This can include details about the commit types, scopes, and any other relevant metadata that can be used to customize the changelog output.

² The options property allows you to specify various options for how the changelog is generated. This can include settings for how commit messages are formatted, how sections are organized, and any other customization options provided by the underlying changelog generation library.

For more details on changelog configuration check out the changelog configuration guide and the conventional-changelog-writer documentation.

release (optional)

The release configuration customizes how release notes (RELEASE.md files) are generated. It has exactly the same structure as changelog - separate root and module sections, each accepting a context and options passed to conventional-changelog-writer - but it applies to the release notes renderer instead of the changelog renderer.

versu.config.js

export default {
  // Other configuration options
  release: {
    // Release notes configuration options
    root: {
      // Root release notes configuration (optional)
      context: { /* */ }, // Context<Commit>
      options: { /* */ }, // Options<Commit>
    },
    module: {
      // Module release notes configuration (optional)
      context: { /* */ }, // Context<Commit>
      options: { /* */ }, // Options<Commit>
    },
  },
};

This lets you style changelogs and release notes independently - for example, a full historical CHANGELOG.md with compare links, and leaner release notes (default RELEASE.md) used as the body of a GitHub release.

For more details on release notes configuration check out the release notes guide.

Alternative Formats

Versu uses cosmiconfig to load configuration files. This allows you to use different file formats and locations for your configuration. Below are examples of how to structure your configuration file in different formats.

WARNING

If you choose to use a non-JavaScript format (like JSON or YAML), you won't be able to include features like functions or variables in your configuration, that are required for some configuration options. In such cases, you would need to use JavaScript or TypeScript for your configuration file to take full advantage of all the features Versu offers.

ES Module

versu.config.js

export default {
  plugins: [ /* ... */ ],
  versioning: { /* ... */ },
  changelog: { /* ... */ },
  release: { /* ... */ },
};

CommonJS

versu.config.cjs

module.exports = {
  plugins: [ /* ... */ ],
  versioning: { /* ... */ },
  changelog: { /* ... */ },
  release: { /* ... */ },
};

TypeScript (with type checking)

versu.config.ts

import type { VersuConfig } from "@versu/core";

export default {
  plugins: [ /* ... */ ],
  versioning: { /* ... */ },
  changelog: { /* ... */ },
  release: { /* ... */ },
} satisfies VersuConfig;

Next Steps

• Changelog Generation - Customize changelogs
• Pre-release Versions - Pre-release setup
• Examples - Real configuration examples

---

Ready to customize your changelog? Check out the Changelog Generation Guide!