InfraWeb Platform

Sharp Edges

As a little follow-up/reality check to my previous post, I’d like to document my frustration with configuring and launching a new Astro site on Cloudflare, which feels ironic. The specific combo I’ve been wrestling with is pnpm v111 and Astro v7 on Cloudflare Workers.

Try this: in an empty directory, run pnpm init to get a basic package.json file, then follow the manual setup in the Astro docs: run pnpm add astro, add a page at src/pages/index.astro, and add dev/build/preview scripts as documented. Now you should be able to run pnpm run build and get some HTML in your /dist folder. Hooray! But now let’s put it on Cloudflare. If you want it connected to your source control, initialize git and push your folder to GitHub or GitLab.2 OK, almost there!

When you connect your new Workers project to your new repo, you’ll briefly feel a sense of hope. Did I really just deploy my new Astro site in three clicks? Ha, no. You’ll go through several failed builds before you get a success. In no particular order, here’s what it actually took:

  1. Set the PNPM_VERSION environment variable to 11, because out of the box right now the build system uses v10, and that won’t work
  2. Delete the packageManager field from the default package.json that pnpm init creates — it’s invalid and will fail the build
  3. Add wrangler as a dependency; without it in package.json, pnpm won’t build the project at all
  4. Run pnpm approve-builds so pnpm is allowed to run the install scripts for workerd and esbuild
  5. Maybe you do need a wrangler.jsonc after all? Or should you run astro add cloudflare?
  6. etc. etc. etc.

The actual steps needed to make the build work took some trial and error, which is frustrating because all indications are that it should be automatic. Make change, push to origin, check build logs for fail, repeat. I don’t envy the engineers tasked with making that work — there’s no doubt a huge backlog of bugs from esoteric combinations of things that don’t behave as they should.

That said, I don’t think it’s unreasonable to expect that in Q3 2026, pnpm, Astro, and Cloudflare should Just Work.

Footnotes

  1. According to State of JS 2025, pnpm was the most-used monorepo/package-manager tool among respondents to that question, and v11 was released in April. I’m just saying it’s not an obscure or bleeding edge tool. ↩

  2. Of course you’ll need a .gitignore file too so you don’t commit node_modules, the /.astro folder, or anything else accidentally, but maybe this is too obvious to mention… ↩