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.jsoncstill has the Pages fieldpages_build_output_dir; replace it withassets.directory. - The build or deploy asks for a D1 database or a
DBbinding. The build produced a server instead of a static folder; pinnitro.preset: 'static'. /aboutanswers 307 to/about/.autoSubfolderIndexis stilltrue; set it tofalse.- An unknown URL returns the home page with a 200.
not_found_handlingissingle-page-application; use404-pagewithprerenderErrorPages. - An old URL redirects with a 302. There is no status code in
_redirects; add301.
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.