Netlify, Vercel and Cloudflare Pages

Page content:

These hosts connect to your Git repository and build the site themselves, each time you push. Each needs to know the same three things: the command that builds the site, the folder it writes, and a version of Node.js that Postdoc runs on.

What every host needs

Setting Value
Build command npx postdoc build
Output or publish directory out
Node.js version 22.18 or newer

If your project uses a different outputPath, use that folder instead.

The host installs what your package.json lists before it builds, so Postdoc has to be one of its dependencies, as it is in a project made with postdoc init.

A site that lives in a subfolder of its domain needs a base.

Netlify

Put the settings in a netlify.toml at the root of the repository, then create a Netlify project from the repository:

netlify.tomltoml
[build]
  command = "npx postdoc build"
  publish = "out"

[build.environment]
  NODE_VERSION = "22"

NODE_VERSION takes a major version, such as 22 for the newest Node.js 22, or an exact one. A .nvmrc or .node-version file in the repository sets it too.

Netlify shows the site's 404 page for an address that doesn't exist, with nothing to set up.

Vercel

Put the settings in a vercel.json at the root of the project, then import the repository in Vercel:

vercel.jsonjson
{
  "framework": null,
  "buildCommand": "npx postdoc build",
  "outputDirectory": "out"
}

"framework": null picks the Other preset, because Postdoc isn't one of the frameworks that Vercel sets up by itself.

New Vercel projects build with Node.js 24, which is new enough. To pick the version yourself, set Node.js Version in the project's Build and Deployment settings. An engines.node entry in package.json, such as "22.x", wins over that setting.

Vercel shows the site's 404 page for an address that doesn't exist.

Cloudflare Pages

Create a Pages project from the repository, with these build settings:

Setting Value
Framework preset None
Build command npx postdoc build
Build output directory out

Then set the Node.js version. Add an environment variable named NODE_VERSION with a version such as 22.18.0, or put the version in a .nvmrc or .node-version file. Without it, the build runs on the Node.js that comes with the build image, which is 22.16 at the time of writing and too old for Postdoc.

Two things work differently on Cloudflare Pages:

  • A site without a 404.html is taken for a single-page app. An address that doesn't exist then shows the home page rather than an error. Add a 404 page to get a proper one.
  • Pages are served without .html. /guide/install.html redirects to /guide/install, and /guide/index.html to /guide/. Links that end in .html keep working.

Check the site before it's published

These hosts build the site, but they don't check it: postdoc test needs a browser, which a host's build machine may not have. There are two ways to keep the checks.

Check pull requests in CI. Let the host deploy, and run postdoc test in CI on every pull request. Make that job required for merging, and only changes that pass reach the branch the host publishes.

Deploy from CI. Each of these hosts also takes a site that was built somewhere else. A CI job can then run postdoc test and hand over the result, as the GitHub Pages workflow does. The hosts describe how:

Edit this page on GitHub