GitBook 4.0 CLI v2: Legacy book.json Support – Re‑enable or Enforce Migration?

Question

My goal is to migrate an existing GitBook project that still relies on the legacy book.json configuration into the new CLI v2 environment introduced in GitBook 4.0. The migration must preserve custom plugins, themes, and build outputs while satisfying the new Node.js 14+ requirement.
CLI v2 removes automatic parsing of book.json and only accepts .js or .ts modules via the --config flag. The official gitbook migrate helper only copies basic metadata, leaving many custom settings unhandled, which forces manual edits after migration.
Because the documentation states this is a “future decision,” it is unclear whether CLI v2 will ever re‑enable book.json support or enforce a complete migration to book.config.js. This ambiguity impacts long‑term maintenance and CI pipelines.
1. Will GitBook CLI v2 re‑enable parsing of book.json in a future release? 2. If not, what is the expected migration strategy for projects that rely heavily on custom plugins? 3. Are there any plans to extend the gitbook migrate tool to automatically translate plugin configurations into the new format?

Tasadduq Burney · Answer

Answer
GitBook CLI v2 will not re‑enable automatic parsing of legacy book.json; the format is treated as deprecated and future releases will continue to require a JavaScript/TypeScript config file via --config.
Migration strategy for heavy custom‑plugin usage

Install the same Node.js version (≥14) and the GitBook CLI v2 you intend to pin.
Create a new configuration file, e.g. book.config.js (or .ts), that exports an object matching the shape expected by CLI v2.
Re‑declare each plugin from book.json using require (or import) and copy its options verbatim.
Transfer theme, output directory, and any custom fields (e.g. styles, variables) into the new config.
Run gitbook build --config ./book.config.js and compare the generated _book directory with the legacy build (file count, checksums) to confirm functional equivalence.
Commit the new config and update CI pipelines to point to --config.

Plans for extending gitbook migrate
There is no announced plan to enhance the gitbook migrate helper to translate plugin sections automatically; the tool currently copies only basic metadata.
Verification steps

Check CLI version: gitbook --version (should be 4.x).
Attempt a build with a stray book.json present and no --config; the build should fail or ignore the file.
After creating book.config.js, run the build and diff the output against the legacy build.

GitBook 4.0 CLI v2: Legacy book.json Support – Re‑enable or Enforce Migration?

1 answer

Answer

Migration strategy for heavy custom‑plugin usage

Plans for extending `gitbook migrate`

Verification steps

Your perspective belongs here.

0 question comments