Migration

Migrating to Root.js v4

Root.js v4 turns on several features by default that were opt-in in v3, removes the legacy EditorJS rich text editor, and rebrands the CMS UI. Most projects only need to update their packages, but check the sections below if you relied on the old defaults.

Upgrade with an AI agent

A coding agent, such as Claude Code, can run the upgrade for you. Start it in your project's folder on a clean git checkout and paste this prompt:

Upgrade this project to Root.js v4. Follow the instructions at
https://rootjs.dev/skills/root-v4-upgrade.md

Or start Claude Code with the prompt in one line: claude "Upgrade this project to Root.js v4. Follow https://rootjs.dev/skills/root-v4-upgrade.md"

The agent works on a new branch, one commit per step. It snapshots your site's pages before changing anything and updates the packages. It also suggests moving CMS routes to createRoute(), secrets to root secrets and CMS reads to batch requests, and applies the changes you agree to. It then compares the pages before and after, runs your build and tests, and offers to file GitHub issues for anything left.

Translations

The v1 translations system is still the default, so your translations don't need to be migrated. The v2 translations manager stays opt-in while it's experimental. If you set experiments: {v2TranslationsManager: true}, keep it. To try it, see Translations manager v2.

Dependency graph

The dependency graph, which tracks references between docs, is now on by default. If you set dependencyGraph: true, you can remove it.

The graph and global search are kept up to date by the CMS cron job. If you haven't set one up, see cron jobs.

To opt out:

cmsPlugin({
  dependencyGraph: false,
});

Module preloading

Root.js now adds <link rel="modulepreload"> tags for the shared JS chunks that a page's scripts import, so the browser can fetch them in parallel. Your pages' HTML will include these new tags. If you set modulePreload: true, you can remove it.

To opt out:

// @/root.config.ts

import {defineConfig} from '@blinkk/root';

export default defineConfig({
  modulePreload: false,
});

Task manager

The task manager is now on by default, with a Tasks page in the CMS sidebar. It no longer appears on the CMS home page. If you set experiments: {taskManager: true}, you can remove it.

To hide it:

cmsPlugin({
  experiments: {taskManager: false},
});

EditorJS removed

The legacy EditorJS rich text editor and its "Enable EditorJS Editor (legacy)" setting have been removed. Rich text fields always use the Lexical editor, which has been the default since v2. Rich text is stored in the same format, so existing content doesn't need to be migrated.

CMS branding

The CMS UI now uses the Root.js name and the beet logo. The default accent color is now pink instead of light blue, and the default favicon is the beet. To change the look, use the favicon and minimalBranding cmsPlugin options, or themes to override the --cms-* CSS properties, such as --cms-accent.

Other issues

Found an issue that isn't covered here? File an issue on GitHub.