quartz/docs/cli/migrate.md

title
quartz migrate

The migrate command helps you transition your project from Quartz 4 to Quartz v5 by converting your configuration files.

When to Use

Use this command if you have an existing Quartz 4 project and want to upgrade to the new YAML-based configuration system introduced in v5.

What it Does

When you run npx quartz migrate, the CLI performs several automated steps:

1. Read Configuration: It parses your existing quartz.config.ts and quartz.layout.ts files.
2. Map Plugins: It identifies the plugins you are using and maps them to their v5 equivalents.
3. Generate YAML: It creates a new quartz.config.yaml file that contains all your settings, theme colors, and plugin configurations.
4. Backup: It keeps your old .ts files so you can refer back to them if needed.

npx quartz migrate

Verification

After running the migration, you should check the following:

• Theme Colors: Ensure your custom colors were correctly transferred to the theme section of quartz.config.yaml.
• Plugin Options: Verify that any custom options you passed to plugins (like linkClickBehavior) are present in the new config.
• Layout: Check that your component order in the layout section matches your previous setup.

For a comprehensive guide on the entire migration process, including manual steps, see getting-started/migrating.