[{"data":1,"prerenderedAt":801},["ShallowReactive",2],{"\u002Fblog\u002Fdeploying-static-nuxt-to-cloudflare-workers":3},{"id":4,"title":5,"author":6,"body":7,"date":791,"description":792,"extension":793,"meta":794,"navigation":221,"path":795,"readingTime":177,"seo":796,"stem":797,"tag":798,"updated":799,"__hash__":800},"blog\u002Fblog\u002Fdeploying-static-nuxt-to-cloudflare-workers.md","Deploying a static Nuxt site to Cloudflare Workers","Sugata S",{"type":8,"value":9,"toc":782},"minimark",[10,27,48,56,61,84,91,256,266,269,273,279,331,342,353,371,385,389,402,417,432,436,461,484,487,491,512,517,537,548,553,557,569,629,643,646,673,680,683,687,756,762,770,778],[11,12,13,14,18,19,22,23,26],"p",{},"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 ",[15,16,17],"code",{},"main"," at ",[15,20,21],{},".output\u002Fserver\u002Findex.mjs"," and switches Nuxt to the ",[15,24,25],{},"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.",[11,28,29,30,33,34,41,42,47],{},"The difference is not cosmetic. On Workers, Nuxt Content expects a D1 database bound as ",[15,31,32],{},"DB",", so the server can answer content queries (",[35,36,40],"a",{"href":37,"rel":38},"https:\u002F\u002Fcontent.nuxt.com\u002Fdocs\u002Fdeploy\u002Fcloudflare-workers",[39],"nofollow","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 (",[35,43,46],{"href":44,"rel":45},"https:\u002F\u002Fcontent.nuxt.com\u002Fdocs\u002Fdeploy\u002Fstatic",[39],"static hosting","). Nothing to bind, nothing to back up.",[11,49,50,51,55],{},"We use Nuxt for most of our web work (",[35,52,54],{"href":53},"\u002Fblog\u002Fwhy-nuxt-is-our-default","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.",[57,58,60],"h2",{"id":59},"pin-the-static-preset-in-the-config","Pin the static preset in the config",[11,62,63,66,67,70,71,73,74,77,78,83],{},[15,64,65],{},"nuxt generate"," prerenders every page. ",[15,68,69],{},"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 ",[15,72,17],{}," script and sets ",[15,75,76],{},"preset: 'cloudflare'"," (",[35,79,82],{"href":80,"rel":81},"https:\u002F\u002Fdevelopers.cloudflare.com\u002Fworkers\u002Fframework-guides\u002Fweb-apps\u002Fmore-web-frameworks\u002Fnuxt\u002F",[39],"Cloudflare's Nuxt guide","). That is an SSR deployment, and it drags the D1 requirement in with it.",[11,85,86,87,90],{},"Pinning ",[15,88,89],{},"nitro.preset: 'static'"," means the build has the same shape on a laptop, in CI and on Cloudflare. The prerender options sit beside it:",[92,93,98],"pre",{"className":94,"code":95,"language":96,"meta":97,"style":97},"language-ts shiki shiki-themes github-dark","export default defineNuxtConfig({\n  nitro: {\n    preset: 'static',\n    prerender: {\n      \u002F\u002F Nitro routes that no page links to\n      routes: ['\u002F', '\u002Fsitemap.xml', '\u002Frss.xml'],\n      crawlLinks: true,\n      \u002F\u002F about.html, not about\u002Findex.html\n      autoSubfolderIndex: false,\n    },\n  },\n\n  experimental: {\n    \u002F\u002F A real 404.html, not the empty SPA shell\n    prerenderErrorPages: true,\n  },\n})\n","ts","",[15,99,100,120,126,139,145,152,175,187,193,204,210,216,223,229,235,245,250],{"__ignoreMap":97},[101,102,105,109,112,116],"span",{"class":103,"line":104},"line",1,[101,106,108],{"class":107},"snl16","export",[101,110,111],{"class":107}," default",[101,113,115],{"class":114},"svObZ"," defineNuxtConfig",[101,117,119],{"class":118},"s95oV","({\n",[101,121,123],{"class":103,"line":122},2,[101,124,125],{"class":118},"  nitro: {\n",[101,127,129,132,136],{"class":103,"line":128},3,[101,130,131],{"class":118},"    preset: ",[101,133,135],{"class":134},"sU2Wk","'static'",[101,137,138],{"class":118},",\n",[101,140,142],{"class":103,"line":141},4,[101,143,144],{"class":118},"    prerender: {\n",[101,146,148],{"class":103,"line":147},5,[101,149,151],{"class":150},"sAwPA","      \u002F\u002F Nitro routes that no page links to\n",[101,153,155,158,161,164,167,169,172],{"class":103,"line":154},6,[101,156,157],{"class":118},"      routes: [",[101,159,160],{"class":134},"'\u002F'",[101,162,163],{"class":118},", ",[101,165,166],{"class":134},"'\u002Fsitemap.xml'",[101,168,163],{"class":118},[101,170,171],{"class":134},"'\u002Frss.xml'",[101,173,174],{"class":118},"],\n",[101,176,178,181,185],{"class":103,"line":177},7,[101,179,180],{"class":118},"      crawlLinks: ",[101,182,184],{"class":183},"sDLfK","true",[101,186,138],{"class":118},[101,188,190],{"class":103,"line":189},8,[101,191,192],{"class":150},"      \u002F\u002F about.html, not about\u002Findex.html\n",[101,194,196,199,202],{"class":103,"line":195},9,[101,197,198],{"class":118},"      autoSubfolderIndex: ",[101,200,201],{"class":183},"false",[101,203,138],{"class":118},[101,205,207],{"class":103,"line":206},10,[101,208,209],{"class":118},"    },\n",[101,211,213],{"class":103,"line":212},11,[101,214,215],{"class":118},"  },\n",[101,217,219],{"class":103,"line":218},12,[101,220,222],{"emptyLinePlaceholder":221},true,"\n",[101,224,226],{"class":103,"line":225},13,[101,227,228],{"class":118},"  experimental: {\n",[101,230,232],{"class":103,"line":231},14,[101,233,234],{"class":150},"    \u002F\u002F A real 404.html, not the empty SPA shell\n",[101,236,238,241,243],{"class":103,"line":237},15,[101,239,240],{"class":118},"    prerenderErrorPages: ",[101,242,184],{"class":183},[101,244,138],{"class":118},[101,246,248],{"class":103,"line":247},16,[101,249,215],{"class":118},[101,251,253],{"class":103,"line":252},17,[101,254,255],{"class":118},"})\n",[11,257,258,261,262,265],{},[15,259,260],{},"routes"," covers the sitemap and the RSS feed, which are server routes rather than pages, so the crawler would never reach them. ",[15,263,264],{},"crawlLinks"," follows the links it finds, which is how every blog post, service page and case study ends up in the build.",[11,267,268],{},"The two options commented above are the ones behind the confusing bugs, so they get their own sections.",[57,270,272],{"id":271},"wranglerjsonc-for-an-assets-only-worker","wrangler.jsonc for an assets-only Worker",[11,274,275,276,278],{},"An assets-only Worker has no ",[15,277,17],{},". The file gives Wrangler a directory to upload and a rule for URLs that match nothing:",[92,280,284],{"className":281,"code":282,"language":283,"meta":97,"style":97},"language-jsonc shiki shiki-themes github-dark","{\n  \"$schema\": \".\u002Fnode_modules\u002Fwrangler\u002Fconfig-schema.json\",\n  \"name\": \"your-worker-name\",\n  \"compatibility_date\": \"2026-11-16\",\n  \"assets\": {\n    \"directory\": \".output\u002Fpublic\",\n    \"not_found_handling\": \"404-page\"\n  }\n}\n","jsonc",[15,285,286,291,296,301,306,311,316,321,326],{"__ignoreMap":97},[101,287,288],{"class":103,"line":104},[101,289,290],{},"{\n",[101,292,293],{"class":103,"line":122},[101,294,295],{},"  \"$schema\": \".\u002Fnode_modules\u002Fwrangler\u002Fconfig-schema.json\",\n",[101,297,298],{"class":103,"line":128},[101,299,300],{},"  \"name\": \"your-worker-name\",\n",[101,302,303],{"class":103,"line":141},[101,304,305],{},"  \"compatibility_date\": \"2026-11-16\",\n",[101,307,308],{"class":103,"line":147},[101,309,310],{},"  \"assets\": {\n",[101,312,313],{"class":103,"line":154},[101,314,315],{},"    \"directory\": \".output\u002Fpublic\",\n",[101,317,318],{"class":103,"line":177},[101,319,320],{},"    \"not_found_handling\": \"404-page\"\n",[101,322,323],{"class":103,"line":189},[101,324,325],{},"  }\n",[101,327,328],{"class":103,"line":195},[101,329,330],{},"}\n",[11,332,333,334,337,338,341],{},"If you start from a Pages project, the same file still says ",[15,335,336],{},"pages_build_output_dir",". Wrangler reads that field, treats the project as a Pages project, and never looks for an assets directory. ",[15,339,340],{},"wrangler deploy"," stops with:",[92,343,347],{"className":344,"code":345,"language":346,"meta":97,"style":97},"language-txt shiki shiki-themes github-dark","Missing entry-point to Worker script or to assets directory\n","txt",[15,348,349],{"__ignoreMap":97},[101,350,351],{"class":103,"line":104},[101,352,345],{},[11,354,355,356,359,360,363,364,366,367,370],{},"The message then offers ",[15,357,358],{},"main: \"src\u002Findex.ts\""," or ",[15,361,362],{},"assets.directory",". For a static site only the second applies. Deleting ",[15,365,336],{}," and adding ",[15,368,369],{},"assets"," is the whole fix.",[11,372,373,376,377,380,381,384],{},[15,374,375],{},"not_found_handling: \"404-page\""," makes Workers serve the nearest ",[15,378,379],{},"404.html"," with a 404 status when nothing matches. The alternative, ",[15,382,383],{},"\"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.",[57,386,388],{"id":387},"the-404-page-needs-its-own-prerender-flag","The 404 page needs its own prerender flag",[11,390,391,392,394,395,398,399,401],{},"Nuxt writes a ",[15,393,379],{}," either way. Without ",[15,396,397],{},"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 ",[15,400,201],{},".",[11,403,404,405,408,409,412,413,416],{},"The same build emits ",[15,406,407],{},"200.html",", Nuxt's SPA fallback. Nothing on this site uses it, but Cloudflare serves it at ",[15,410,411],{},"\u002F200"," with a 200 status, so it needs to stay out of the index. That is one block in ",[15,414,415],{},"_headers",":",[92,418,420],{"className":344,"code":419,"language":346,"meta":97,"style":97},"\u002F200\n  X-Robots-Tag: noindex\n",[15,421,422,427],{"__ignoreMap":97},[101,423,424],{"class":103,"line":104},[101,425,426],{},"\u002F200\n",[101,428,429],{"class":103,"line":122},[101,430,431],{},"  X-Robots-Tag: noindex\n",[57,433,435],{"id":434},"why-about-should-not-redirect-to-about","Why \u002Fabout should not redirect to \u002Fabout\u002F",[11,437,438,439,442,443,446,447,450,451,454,455,457,458,401],{},"Cloudflare serves HTML with ",[15,440,441],{},"html_handling: \"auto-trailing-slash\""," unless you change it. The rule is short. A file ",[15,444,445],{},"about.html"," is served at ",[15,448,449],{},"\u002Fabout",". A folder ",[15,452,453],{},"about\u002Findex.html"," makes ",[15,456,449],{}," answer 307 to ",[15,459,460],{},"\u002Fabout\u002F",[11,462,463,464,467,468,470,471,474,475,477,478,480,481,483],{},"Nuxt's ",[15,465,466],{},"autoSubfolderIndex"," defaults to ",[15,469,184],{},", 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. ",[15,472,473],{},"autoSubfolderIndex: false"," emits ",[15,476,445],{},", which makes ",[15,479,449],{}," a 200 with no redirect and leaves ",[15,482,460],{}," as the one that gets moved.",[11,485,486],{},"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.",[57,488,490],{"id":489},"redirects-and-headers-are-files-in-the-build-output","Redirects and headers are files in the build output",[11,492,493,494,497,498,500,501,504,505,508,509,511],{},"Cloudflare reads ",[15,495,496],{},"_redirects"," and ",[15,499,415],{}," from the assets directory and does not serve either file. Nuxt copies ",[15,502,503],{},"public\u002F"," into ",[15,506,507],{},".output\u002Fpublic",", so both live in ",[15,510,503],{}," and travel with the build.",[11,513,514,516],{},[15,515,496],{}," is one rule per line: source, destination, status.",[92,518,520],{"className":344,"code":519,"language":346,"meta":97,"style":97},"\u002Fabout-us              \u002Fabout    301\n\u002Fcase-studies          \u002Fwork     301\n\u002Fcontact-us            \u002Fcontact  301\n",[15,521,522,527,532],{"__ignoreMap":97},[101,523,524],{"class":103,"line":104},[101,525,526],{},"\u002Fabout-us              \u002Fabout    301\n",[101,528,529],{"class":103,"line":122},[101,530,531],{},"\u002Fcase-studies          \u002Fwork     301\n",[101,533,534],{"class":103,"line":128},[101,535,536],{},"\u002Fcontact-us            \u002Fcontact  301\n",[11,538,539,540,543,544,547],{},"The status is optional and defaults to ",[15,541,542],{},"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 ",[15,545,546],{},"301"," on every line. Rules apply from the top, so put a specific path above a wildcard.",[11,549,550,552],{},[15,551,415],{}," 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.",[57,554,556],{"id":555},"build-preview-then-check-the-status-codes","Build, preview, then check the status codes",[11,558,559,562,563,565,566,568],{},[15,560,561],{},"npm run build"," runs ",[15,564,65],{},", and the output lands in ",[15,567,507],{},". Most of it is what you would expect:",[92,570,572],{"className":344,"code":571,"language":346,"meta":97,"style":97},".output\u002Fpublic\n  about.html\n  blog.html\n  blog\u002F\n    deploying-static-nuxt-to-cloudflare-workers.html\n  404.html\n  200.html\n  _redirects\n  _headers\n  sitemap.xml\n  rss.xml\n",[15,573,574,579,584,589,594,599,604,609,614,619,624],{"__ignoreMap":97},[101,575,576],{"class":103,"line":104},[101,577,578],{},".output\u002Fpublic\n",[101,580,581],{"class":103,"line":122},[101,582,583],{},"  about.html\n",[101,585,586],{"class":103,"line":128},[101,587,588],{},"  blog.html\n",[101,590,591],{"class":103,"line":141},[101,592,593],{},"  blog\u002F\n",[101,595,596],{"class":103,"line":147},[101,597,598],{},"    deploying-static-nuxt-to-cloudflare-workers.html\n",[101,600,601],{"class":103,"line":154},[101,602,603],{},"  404.html\n",[101,605,606],{"class":103,"line":177},[101,607,608],{},"  200.html\n",[101,610,611],{"class":103,"line":189},[101,612,613],{},"  _redirects\n",[101,615,616],{"class":103,"line":195},[101,617,618],{},"  _headers\n",[101,620,621],{"class":103,"line":206},[101,622,623],{},"  sitemap.xml\n",[101,625,626],{"class":103,"line":212},[101,627,628],{},"  rss.xml\n",[11,630,631,634,635,638,639,642],{},[15,632,633],{},"npm run preview"," starts ",[15,636,637],{},"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 ",[15,640,641],{},"npx serve"," can still redirect in production.",[11,644,645],{},"Four requests cover most of the setup:",[92,647,651],{"className":648,"code":649,"language":650,"meta":97,"style":97},"language-sh shiki shiki-themes github-dark","curl -sI http:\u002F\u002Flocalhost:8788\u002Fabout | head -1         # 200\ncurl -sI http:\u002F\u002Flocalhost:8788\u002Fabout\u002F | head -1        # 307 to \u002Fabout\ncurl -sI http:\u002F\u002Flocalhost:8788\u002Fabout-us | head -1      # 301 to \u002Fabout\ncurl -sI http:\u002F\u002Flocalhost:8788\u002Fno-such-page | head -1  # 404\n","sh",[15,652,653,658,663,668],{"__ignoreMap":97},[101,654,655],{"class":103,"line":104},[101,656,657],{},"curl -sI http:\u002F\u002Flocalhost:8788\u002Fabout | head -1         # 200\n",[101,659,660],{"class":103,"line":122},[101,661,662],{},"curl -sI http:\u002F\u002Flocalhost:8788\u002Fabout\u002F | head -1        # 307 to \u002Fabout\n",[101,664,665],{"class":103,"line":128},[101,666,667],{},"curl -sI http:\u002F\u002Flocalhost:8788\u002Fabout-us | head -1      # 301 to \u002Fabout\n",[101,669,670],{"class":103,"line":141},[101,671,672],{},"curl -sI http:\u002F\u002Flocalhost:8788\u002Fno-such-page | head -1  # 404\n",[11,674,675,676,679],{},"Then ",[15,677,678],{},"curl -sI http:\u002F\u002Flocalhost:8788\u002F200 | grep -i x-robots-tag"," to confirm the SPA shell is noindexed.",[11,681,682],{},"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.",[57,684,686],{"id":685},"when-a-deploy-fails-check-these","When a deploy fails, check these",[688,689,690,707,715,730,748],"ul",{},[691,692,693,694,697,698,701,702,704,705,401],"li",{},"The deploy stops with ",[15,695,696],{},"Missing entry-point to Worker script or to assets directory",". ",[15,699,700],{},"wrangler.jsonc"," still has the Pages field ",[15,703,336],{},"; replace it with ",[15,706,362],{},[691,708,709,710,712,713,401],{},"The build or deploy asks for a D1 database or a ",[15,711,32],{}," binding. The build produced a server instead of a static folder; pin ",[15,714,89],{},[691,716,717,719,720,697,722,724,725,727,728,401],{},[15,718,449],{}," answers 307 to ",[15,721,460],{},[15,723,466],{}," is still ",[15,726,184],{},"; set it to ",[15,729,201],{},[691,731,732,733,736,737,740,741,744,745,401],{},"An unknown URL returns the home page with a 200. ",[15,734,735],{},"not_found_handling"," is ",[15,738,739],{},"single-page-application","; use ",[15,742,743],{},"404-page"," with ",[15,746,747],{},"prerenderErrorPages",[691,749,750,751,753,754,401],{},"An old URL redirects with a 302. There is no status code in ",[15,752,496],{},"; add ",[15,755,546],{},[11,757,758,759,761],{},"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 ",[15,760,637],{}," serves the built folder, so an edit you forgot to build is invisible; if a change doesn't appear, rebuild before debugging.",[11,763,764,765,769],{},"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 ",[35,766,768],{"href":767},"\u002Fblog\u002Fsoftware-development#release-ship-small-and-keep-a-way-back","software development","; the Cloudflare setup above is what makes them cheap.",[11,771,772,773,777],{},"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 ",[35,774,776],{"href":775},"\u002Fservices#devops","DevOps and deployment service"," covers.",[779,780,781],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .snl16, html code.shiki .snl16{--shiki-default:#F97583}html pre.shiki code .svObZ, html code.shiki .svObZ{--shiki-default:#B392F0}html pre.shiki code .s95oV, html code.shiki .s95oV{--shiki-default:#E1E4E8}html pre.shiki code .sU2Wk, html code.shiki .sU2Wk{--shiki-default:#9ECBFF}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html pre.shiki code .sDLfK, html code.shiki .sDLfK{--shiki-default:#79B8FF}",{"title":97,"searchDepth":122,"depth":122,"links":783},[784,785,786,787,788,789,790],{"id":59,"depth":122,"text":60},{"id":271,"depth":122,"text":272},{"id":387,"depth":122,"text":388},{"id":434,"depth":122,"text":435},{"id":489,"depth":122,"text":490},{"id":555,"depth":122,"text":556},{"id":685,"depth":122,"text":686},"2026-11-16","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.","md",{},"\u002Fblog\u002Fdeploying-static-nuxt-to-cloudflare-workers",{"title":5,"description":792},"blog\u002Fdeploying-static-nuxt-to-cloudflare-workers","Engineering",null,"9Ak43UCrY2Zyhwh4xBR6RE_xdPEZYH7u2CP-uQBMMFM",1794818605207]