logo hsb.horse
← Back to blog index

Blog

How to configure subdirectory routing with Cloudflare Workers

Configuration steps for deploying an Astro project under a subdirectory with Cloudflare Workers. Organized how to adjust wrangler.json and astro.config.

Published:
#cloudflare #astro #deployment

Translations

German French Japanese Korean Portuguese

As of 2025-11-28, this site is operating on two Astro projects.

  • hsbt.horse/*: Root
  • hsbt.horse/tools/*: Tools

There is no problem if you write the root wrangler.json simply as per the official document.

{
  "name": "root",
  "compatibility_date": "2025-11-19",
  "route": "hsbt.horse/*",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page"
  },
  "preview_urls": false
}

On the other hand, the tools did not work as expected unless some work was done.

Problem: Subdirectory routing results in 404

Write wrangler.json as follows.

{
  "name": "tool",
  "compatibility_date": "2025-11-19",
  "route": "hsbt.horse/tools/*",
  "assets": {
    "directory": "./dist/",
    "not_found_handling": "404-page"
  },
  "preview_urls": false
}

There is no problem with the way it is written, but if you deploy it as is, you will get a 404 error.

The reason is that the behavior of uploading files under dist/tools according to the hierarchical structure of /tools/* described in route seems to be the specification of wrangler.

Solution: Set base and outDir in astro.config.mjs

This method can be used when treating src/pages as tools/.

If you set base and outDir as below in astro.config.mjs, it will work as expected.

export default defineConfig({
  site: "https://hsbt.horse",
  base: "/tools/",
  outDir: "./dist/tools",
})

base adds a prefix to the links and asset paths generated by Astro.

outDir changes the build output destination to ./dist/tools to match the hierarchical structure expected by wrangler.

Unplanned: Implement various pages under src/pages/tools

Do not change the settings in astro.config.mjs. Base is not set and outDir is not changed from dist.

Instead, we will deal with this by establishing implementation rules for the file-based routing side under src/pages.

By implementing the necessary pages under src/pages/tools, you can output various pages to dist/tools without changing settings.

However, with this method, the _astro directory (various bundled JS, CSS, assets) will be created directly under dist, so the HTML under dist/tools will be deployed, but the assets will not be deployed.

summary

When deploying a project under a subdirectory with Cloudflare Workers, you need to adjust not only the route settings of wrangler but also base and outDir on the Astro side.

By aligning the hierarchy, wrangler will be able to upload files correctly.