Vivliostyle.js turns HTML and CSS into paginated, EPUB ready reading

A typesetting engine that treats the browser as a page

Vivliostyle.js is an open source project for a typesetting system built on web standard technology. The claim is narrow and specific: HTML plus CSS typesetting with rich paged viewing, plus EPUB and web publication support. That means the engine takes a document written for a screen and reflows it into pages with the kind of control a print layout expects, margins, columns, running heads, footnotes, page breaks, all expressed in CSS rather than in a desktop publishing tool. The alternative to competing with it is usually to export from a word processor to PDF, which fixes the output at one size and one page count. Vivliostyle keeps the output live and scriptable, which is what makes it useful for a publisher with a catalogue, a university producing course books in several editions, or a developer who wants to print a long document from a website without destroying the original layout.

Eight packages, each with a different job

The repository is a monorepo whose package split does most of the explaining. @vivliostyle/core is the core library for HTML plus CSS typesetting with EPUB and web publication support, and it is the piece that other packages build on. @vivliostyle/viewer is the web application that gives you an interface for working with it, and the project points readers at an officially hosted viewer as well as a downloadable distribution package. @vivliostyle/cli is the command line interface. @vivliostyle/react exposes a React component that acts as a Vivliostyle renderer, which is the entry point for teams who already build their reading surface in React. @vivliostyle/print allows page layout using Vivliostyle Core for printing within a website. @vivliostyle/vfm defines Vivliostyle Flavored Markdown, a Markdown syntax optimised for book authoring that is standardised and published for Vivliostyle and its sibling projects. Two scaffolding packages sit alongside: create-book, described as the fastest way to start writing a book with the ecosystem, and create-vivliostyle-theme for starting a theme. Each of these lives in its own repository with its own npm package, so you install only the part of the stack you need.

Building the workspace with the scripts in package.json

The project documentation does not give a one line install for a hosted service, so the practical entry points are the npm packages and the source repository. The viewer can be tried in the officially hosted version or downloaded as a distribution package, and the sources for the monorepo are published on GitHub on the master branch. From a checkout, the root package.json defines the workflow through scripts that delegate to lerna, and the entry points you will use first are:

    "build": "lerna run build",
    "build-dev": "lerna run build-dev",
    "dev": "node scripts/dev.mjs",
    "test": "cross-env NODE_OPTIONS=--disable-warning=DEP0169 yarn workspace @vivliostyle/core test",
    "test:layout-regression": "node scripts/layout-regression.mjs",

The repository carries a yarn.lock file, a tsconfig.json and a lerna.json, so the packages are built and versioned together. A separate development entry point starts the local development server, and a React flavoured script runs the package builds in parallel while leaving the viewer out of the way. Note what is not here: no script in the visible portion of the manifest prepares a distribution bundle for the viewer itself, so the viewer is served from the hosted application or taken from the published distribution rather than produced by the root build alone.

Layout regression as the guard on page output

Paged layout is exactly the kind of feature where a small change produces a large visual difference, so the test story is unusually important here. Alongside the core test script, the manifest carries a set of layout regression commands:

    "test:layout-regression": "node scripts/layout-regression.mjs",
    "test:reftest": "node scripts/layout-regression.mjs --mode reftest",
    "test:reftest-diff": "node scripts/layout-regression.mjs --mode reftest-diff",
    "test:layout-regression:triage": "node scripts/triage-summary.mjs",

The three modes imply a workflow: run the regression suite, re-run the failing cases, and diff the results to see what moved. The triage script then summarises the failures, and a separate command writes the triage file back into the scripts directory so it can be committed as a known baseline. That is a telling detail about the project, because it means the reference state of page rendering is treated as something to be checked in rather than rediscovered by eye. There is also a command that downloads the web platform tests manifest, which suggests conformance against browser test data is part of the checking, and the repository has a dedicated scripts directory for all of this. For an adopter, the practical consequence is that layout changes can be judged against stored expectations instead of by opening a page.

Canary builds, publish flows and how versions ship

Releases are cut from the monorepo and published package by package. The manifest shows the shipping commands:

    "now-build": "VIVLIOSTYLE_VERSION=canary yarn build && ./scripts/create-archive.js vivliostyle-canary vivliostyle-viewer-canary.zip",
    "ship": "lerna publish from-package",
    "ship:canary": "lerna publish --canary",
    "ship:prerelease": "yarn ship --dist-tag next",

So a normal release publishes from the packages themselves, a canary build sets VIVLIOSTYLE_VERSION and produces a zip archive, and prereleases are pushed under the next dist tag. Tagged releases include v2.45.0 on 2026-08-22, v2.45.1 on 2026-09-06 and v2.45.2 on 2026-09-23, and the last push was on 2026-10-20. This is a project that ships on a visible cadence across several npm packages at once, so upgrading means tracking a coordinated set of versions rather than a single dependency.

AGPL-3.0 and the AI policy files in the repository

The repository is published under the AGPL-3.0 licence. That matters more for Vivliostyle.js than for a typical tool, because the viewer and the core are designed to be embedded in a website that serves publications to the public. The copyleft terms in AGPL-3.0 reach network use of modified versions, so a team planning to run the viewer or the core inside a hosted reading product has to read the licence text before shipping rather than after. This is not legal advice, it is the practical reason the licence is the first thing to check. The repository also carries policy files that a reader should look at before contributing: AI_POLICY.md at the top level, alongside AGENTS.md and CLAUDE.md, and directories named .agents and .claude. The project asks contributors to follow its contribution guide and development wiki for setup. Note also that @vivliostyle/vfm is standardised for Vivliostyle and its sibling projects, so a Markdown corpus written for it is portable only inside that family, which is a real constraint for teams considering it as a long term authoring format.

Editorial conclusion

Adopt Vivliostyle.js if your output has to be paginated HTML and CSS, especially EPUB, and you want to run the layout engine inside your own site rather than exporting to PDF. Do not adopt it as a general PDF generator, and do not embed the viewer in a hosted product before reading the AGPL-3.0 terms and the repository AI_POLICY.md, because the copyleft obligations attach to the code you distribute. Before you commit, verify that your CSS uses the paged media features the core package implements, that the layout regression suite passes on your content, and that the npm scope you intend to depend on matches the package you need.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. vivliostyle/vivliostyle.js on GitHub