Building a Low-Friction Platform from Scratch with Astro + Cloudflare Workers

So you want to build a technical blog, or maybe a little demo platform — but you don't want to wrestle with some complicated backend setup every single time you deploy. That's exactly the problem I set out to solve, and the answer I landed on was Astro plus Cloudflare Workers. Let me walk you through how I made the whole thing lightweight, including the traps I fell into and the details that actually matter.

First, why this particular stack? There are plenty of static-site hosts out there — Vercel, Netlify, Railway, they've all got their strengths. But if your wish list reads something like "a light frontend, a sprinkle of dynamic API, global edge deployment, and almost zero operations cost," then Cloudflare wins on one thing above all: integration.

Here's the comparison in plain terms. For edge execution, Cloudflare runs your code on Workers using V8 isolates, while Vercel uses Node-based edge functions and Netlify uses Deno-based ones. The big difference shows up with data. Cloudflare gives you a database built in — that's D1, which is SQLite — plus a key-value store, and even a vector database called Vectorize, right there on the platform. With Vercel or Netlify, you're reaching for an external service for all of those. On the free tier, Cloudflare hands you a hundred thousand Worker requests a day. And cold starts? Because isolates spin up almost instantly, cold start is virtually a non-issue, whereas the others do make you wait.

Now, there's a price for all this. The Cloudflare runtime is Workers — V8 isolates — not a full Node.js environment. So a handful of npm packages just won't work, and the Node built-ins like file system, path, and child process simply don't exist. That's worth confirming before you commit your whole project to it.

Let me paint the architecture. Picture the browser making two kinds of requests. Static assets — your JavaScript, CSS, images — get served straight from the Pages CDN, cached and distributed globally. But anything dynamic, an API call or a server-rendered page, goes to Workers instead. And it's the Worker that talks to everything else: the D1 database, the key-value store, R2 object storage, and Workers AI. Once Astro is wired up with the Cloudflare adapter, your server-rendered pages and your API routes all run on Workers, while the static stuff lives on the CDN. Clean division of labor, and the two never step on each other's toes.

Okay, let's build it from scratch.

Step one, spin up the Astro project and add the Cloudflare adapter. In your Astro config, you set output to "server" and plug in the Cloudflare adapter. Two settings really matter here. You set mode to "directory," which makes the output match the folder structure Cloudflare Pages Functions expects. And then — this is the one people forget — you enable platformProxy. That flag is what emulates the Cloudflare environment when you're developing locally. Skip it, and your runtime object comes back undefined on your own machine, which turns debugging into absolute misery. If you want multilingual routing, say Traditional Chinese as the default with English living under a slash-en path, Astro's i18n config handles that too — you just declare your locales and tell it not to prefix the default language.

Step two, configure wrangler.jsonc. This is the single place where you manage every Cloudflare service binding. A binding has two parts: a name you reference in code — like env.DB or env.AI — and the actual resource it points to. So in that file you'd declare your D1 database with the binding "DB," your KV namespace as "CACHE," your R2 bucket as "STORAGE," and Workers AI simply as "AI." If you need a few Node built-ins like crypto, buffer, or stream, you add the nodejs_compat compatibility flag. But heads up — that flag does not bring back file system, path, or child process. Those are gone for good.

Step three, actually use those bindings in an API route. My strong recommendation: declare an Env interface in your env.d.ts file first, listing each binding and its type — the database, the KV store, R2, the AI binding, your admin token, and so on. Do that, and your editor's autocomplete starts correctly suggesting D1's methods. Then an API route is genuinely simple. You pull the database binding off of locals.runtime.env, run a prepared statement — say, counting the rows in your posts table — and return it as JSON. Workers AI works the exact same way: grab the AI binding, call run with a model name like bge-m3, hand it your text, and you get an embedding back. Same pattern every time.

Step four, create the D1 database. D1 is Cloudflare's SQLite-compatible edge database, and because it lives right next to your Worker, calling it feels local — there's basically no connection latency. You create it with one wrangler command, then run your migrations, and here's the key distinction: there's a local flag and a remote flag. Local applies the migration to your dev copy, remote applies it to the real thing. Keep your migration files in a migrations folder and prefix them with version numbers — zero-zero-zero-one, zero-zero-zero-two, and so on — because that numeric prefix is what guarantees they run in the right order.

Step five, deploy through GitHub Actions. The workflow is short: check out the code, set up pnpm, install, build, and then hand off to Cloudflare's wrangler action to deploy your dist folder to Pages. It authenticates with two secrets — your Cloudflare API token and your account ID — which you store in the GitHub repo under Settings, Secrets and variables, Actions. To create that token, you go into the Cloudflare dashboard, into API Tokens, pick "Custom token," and give it at minimum Cloudflare Pages Edit permission. If your workflow also runs migrations, it needs D1 Edit too. And here's a nice bonus: Pages spins up a separate preview URL for every branch, so you can eyeball your changes before merging to main, no manual steps required.

Now, the pitfalls — and these are the ones that cost me real time.

Pitfall number one: environment variables and bindings are two completely separate systems. The symptom is maddening. Locally, your dev server reads a secret just fine, but after you deploy, that same secret comes back undefined. Here's what's going on: the bindings in wrangler.jsonc — your database, KV, R2 — and the environment variables in the Cloudflare dashboard are two independent worlds. Locally, you fake environment variables using a dotfile called .dev.vars, but they're accessed through a different mechanism than bindings. So the rule is: put your real secrets — API tokens, passwords — in the dashboard's environment variables. Put your database, KV, and R2 in wrangler.jsonc as bindings. And for local development secrets, use that .dev.vars file — and absolutely add it to your gitignore.

Pitfall number two: the Node.js APIs that aren't there. You import some npm package, deploy, and the build screams that it can't find module "fs." Right — because the runtime is V8 isolates, not Node, so file system, path, and child process don't exist. Your move is to check whether the package has a Workers-compatible build, or enable the nodejs_compat flag for things like crypto and buffer. Just remember it still won't give you file system access.

Pitfall number three, and this one's a little scary: data contamination in your D1 preview environment. The symptom — you run some tests in a pull request's preview environment, and somehow your production data gets modified. Here's the trap. By default, every branch's preview environment points at the same database ID in wrangler.jsonc, which is your production database. So any write you do in preview is hitting production directly. The fix is to go into your Cloudflare Pages project settings, find the environment variables, and override the database ID specifically for the preview environment so it points at a dedicated staging database. Do that before you ever run a test against preview.

Pitfall number four: isolates are stateless. You set some module-level variable on the first request, and on the second request it's back to its starting value. That's because in Workers, each request is its own isolated execution environment — global variables just don't persist between requests, which is a real departure from a traditional Node server that stays running. So anything you need to share across requests — sessions, caches — goes into KV or D1. Never lean on a module-level variable to hold state.

So let me leave you with the three things that really matter here.

First, integration is the whole point of Cloudflare. D1, KV, R2, Vectorize, and Workers AI all live on one platform, which means you're not juggling credentials and access policies across a half-dozen separate services. That's the friction you're buying your way out of.

Second, don't forget to enable platformProxy. I know I've said it twice now, but it's the single easiest thing to miss and it'll have you staring at an undefined runtime wondering what broke.

And third, be disciplined about secrets. Keep your sensitive keys in the Cloudflare dashboard and in GitHub Secrets. In wrangler.jsonc, you only ever put binding names and resource IDs — never an actual secret. Get those three right, and you've got a platform that's genuinely low-friction, the way it was supposed to be.