All articles

Engineering

Deploying a static Nuxt site to Cloudflare Workers

How we deploy a prerendered Nuxt site to Cloudflare Workers: the static preset, an assets-only Worker, 404 handling and the errors each one throws.

By Sugata S7 min read

Our site is a prerendered Nuxt app served by Cloudflare Workers. Cloudflare's own Nuxt guide would have set it up for server-side rendering: its automatic configuration puts main at .output/server/index.mjs and switches Nuxt to the cloudflare preset. A static site has no server to run. The build is a folder of HTML, and Workers only has to serve the files.

The difference is not cosmetic. On Workers, Nuxt Content expects a D1 database bound as DB, so the server can answer content queries (Nuxt Content's Workers guide). On static hosting it needs no database: Nuxt Content ships SQLite compiled to WebAssembly, and queries made in the browser run there (static hosting). Nothing to bind, nothing to back up.

We use Nuxt for most of our web work (the reasons are here), and this is the setup we start from for a static site. The only dynamic piece of this one is a contact form that posts straight from the browser to an API on another domain, so the build needs no runtime at all. Here is the whole configuration, and the error each wrong setting produces.

Pin the static preset in the config

nuxt generate prerenders every page. nuxt build builds whatever preset the project configures, and Cloudflare's automatic Nuxt detection has its own idea: when a project has no Wrangler config, Wrangler writes one with a main script and sets preset: 'cloudflare' (Cloudflare's Nuxt guide). That is an SSR deployment, and it drags the D1 requirement in with it.

Pinning nitro.preset: 'static' means the build has the same shape on a laptop, in CI and on Cloudflare. The prerender options sit beside it:

export default defineNuxtConfig({
  nitro: {
    preset: 'static',
    prerender: {
      // Nitro routes that no page links to
      routes: ['/', '/sitemap.xml', '/rss.xml'],
      crawlLinks: true,
      // about.html, not about/index.html
      autoSubfolderIndex: false,
    },
  },

  experimental: {
    // A real 404.html, not the empty SPA shell
    prerenderErrorPages: true,
  },
})

routes covers the sitemap and the RSS feed, which are server routes rather than pages, so the crawler would never reach them. crawlLinks follows the links it finds, which is how every blog post, service page and case study ends up in the build.

The two options commented above are the ones behind the confusing bugs, so they get their own sections.

wrangler.jsonc for an assets-only Worker

An assets-only Worker has no main. The file gives Wrangler a directory to upload and a rule for URLs that match nothing:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "your-worker-name",
  "compatibility_date": "2026-11-16",
  "assets": {
    "directory": ".output/public",
    "not_found_handling": "404-page"
  }
}

If you start from a Pages project, the same file still says pages_build_output_dir. Wrangler reads that field, treats the project as a Pages project, and never looks for an assets directory. wrangler deploy stops with:

Missing entry-point to Worker script or to assets directory

The message then offers main: "src/index.ts" or assets.directory. For a static site only the second applies. Deleting pages_build_output_dir and adding assets is the whole fix.

not_found_handling: "404-page" makes Workers serve the nearest 404.html with a 404 status when nothing matches. The alternative, "single-page-application", returns the app shell with a 200 for every unknown URL. That suits a client-rendered app. On a site whose pages are files, Google would see the same shell at every address.

The 404 page needs its own prerender flag

Nuxt writes a 404.html either way. Without experimental.prerenderErrorPages, that file is the empty SPA shell: the error page exists in JavaScript, but the HTML is blank, so a crawler or a reader with scripts blocked sees nothing. Nuxt's schema describes the option as server-rendering static error pages "rather than emitting an empty SPA shell". It defaults to false.

The same build emits 200.html, Nuxt's SPA fallback. Nothing on this site uses it, but Cloudflare serves it at /200 with a 200 status, so it needs to stay out of the index. That is one block in _headers:

/200
  X-Robots-Tag: noindex

Why /about should not redirect to /about/

Cloudflare serves HTML with html_handling: "auto-trailing-slash" unless you change it. The rule is short. A file about.html is served at /about. A folder about/index.html makes /about answer 307 to /about/.

Nuxt's autoSubfolderIndex defaults to true, which produces the second shape, so every page URL without a trailing slash takes a redirect before anything renders. The canonical URL and the URL actually served are then different. autoSubfolderIndex: false emits about.html, which makes /about a 200 with no redirect and leaves /about/ as the one that gets moved.

That is a small win on each page and a larger one across a site: fewer hops for a crawler, and one URL per page to reason about.

Redirects and headers are files in the build output

Cloudflare reads _redirects and _headers from the assets directory and does not serve either file. Nuxt copies public/ into .output/public, so both live in public/ and travel with the build.

_redirects is one rule per line: source, destination, status.

/about-us              /about    301
/case-studies          /work     301
/contact-us            /contact  301

The status is optional and defaults to 302. That default is the trap when you move old URLs: a temporary redirect doesn't do the job of a permanent one, and some crawlers keep the old address. Write 301 on every line. Rules apply from the top, so put a specific path above a wildcard.

_headers takes a URL or a pattern followed by an indented list of headers. Redirects run before headers, so a request that matches both gets the redirect.

Build, preview, then check the status codes

npm run build runs nuxt generate, and the output lands in .output/public. Most of it is what you would expect:

.output/public
  about.html
  blog.html
  blog/
    deploying-static-nuxt-to-cloudflare-workers.html
  404.html
  200.html
  _redirects
  _headers
  sitemap.xml
  rss.xml

npm run preview starts wrangler dev on port 8788, serving that folder with the same asset rules as production. A plain static file server has none of them, so a page that looks fine at npx serve can still redirect in production.

Four requests cover most of the setup:

curl -sI http://localhost:8788/about | head -1         # 200
curl -sI http://localhost:8788/about/ | head -1        # 307 to /about
curl -sI http://localhost:8788/about-us | head -1      # 301 to /about
curl -sI http://localhost:8788/no-such-page | head -1  # 404

Then curl -sI http://localhost:8788/200 | grep -i x-robots-tag to confirm the SPA shell is noindexed.

Status codes don't tell you whether a page works. We load every sitemap URL in headless Chrome at desktop and phone widths, in both themes. The run fails on a console error, a redirect, or a page wider than the viewport, which is how a JavaScript error gets caught despite a 200.

When a deploy fails, check these

  • The deploy stops with Missing entry-point to Worker script or to assets directory. wrangler.jsonc still has the Pages field pages_build_output_dir; replace it with assets.directory.
  • The build or deploy asks for a D1 database or a DB binding. The build produced a server instead of a static folder; pin nitro.preset: 'static'.
  • /about answers 307 to /about/. autoSubfolderIndex is still true; set it to false.
  • An unknown URL returns the home page with a 200. not_found_handling is single-page-application; use 404-page with prerenderErrorPages.
  • An old URL redirects with a 302. There is no status code in _redirects; add 301.

Two more traps produce no error at all. Environment variables are baked into the build, so a value added in the Cloudflare dashboard takes effect only after the next build and deploy. And wrangler dev serves the built folder, so an edit you forgot to build is invisible; if a change doesn't appear, rebuild before debugging.

For a site like this, release is a file upload. No server to patch, no database to back up, and a rollback that restores the previous version. The practices around it, from staging to a canary release, are in our guide to software development; the Cloudflare setup above is what makes them cheap.

If you're moving a Nuxt site onto Workers and want the build checked before it goes live, that is the sort of work our DevOps and deployment service covers.