From Static to Dynamic on Cloudflare Pages

This one is for developers. It assumes you have already put a static site on Cloudflare Pages and now need it to do something — take a form submission, remember it, and live on your own domain. Every number here comes from Cloudflare's own documentation, checked in September 2026.

The wrong turn I took first

I want to start with the mistake, because it is the one thing a tutorial will not tell you and it wasted the most time.

Cloudflare’s dashboard has a big blue Create application button. In 2026 that button walks you into Workers Builds — connect your GitHub repo, set a build command, done. It looks like the obvious front door. I clicked it, connected my repository, and got this:

Three things are wrong in that little box, and they are worth naming one by one.

wrangler deploy is the Workers command, not the Pages command. They are different products with different deploy verbs. A Pages project is deployed with wrangler pages deploy <directory>. Running the Workers verb against a Pages configuration gets you an error that reads like a bug in your code.

The build command was empty. The log went straight from npm clean-install to the deploy step, so there was no built output to deploy at all. It was shipping nothing, loudly.

It was not even the right project. Cloudflare created a new application from my repository name. My real site lived in a Pages project called something else entirely, with the database and the secrets attached to it. Even a green build would have deployed a stranger.

A successful deploy to the wrong project is worse than a failed one.

I deleted the whole thing and went back to deploying from my laptop. Which, it turns out, is the better answer anyway — for a reason that has nothing to do with Workers versus Pages.

Here is what a correctly configured project looks like afterwards. Note the line under the name:

“No Git connection” is not a warning. On a direct-upload project it is the design.

The shape of a dynamic Pages site

Before the how, the what. A Pages site with a backend has exactly two kinds of request, and Cloudflare decides between them by looking at the path.

The mental shift that took me longest: the function does not stay running between requests. There is no process holding a variable. I originally kept a rate-limit counter in a JavaScript Map, which worked perfectly on my laptop and did nothing at all in production, because every request got a fresh, empty Map. Anything that must be remembered between two requests has to go into the database. That is not a limitation to work around; it is the entire model.

Adding a database with D1

D1 is Cloudflare’s SQLite database. It is real SQL — tables, indexes, JOIN, transactions — and on the free plan it costs nothing.

npx wrangler d1 create my-leads

name = "my-site"
pages_build_output_dir = "dist"
[[d1_databases]]
binding = "DB"
database_name = "my-leads"
database_id = "the-uuid-from-step-1"

npx wrangler d1 execute my-leads --local  --file=./schema.sql
npx wrangler d1 execute my-leads --remote --file=./schema.sql

const result = await env.DB
  .prepare('INSERT INTO leads (name, email, message) VALUES (?, ?, ?)')
  .bind(lead.name, lead.email, lead.message)
  .run();
const id = result.meta.last_row_id;

npx wrangler d1 execute my-leads --remote \
  --command "SELECT * FROM leads ORDER BY id DESC LIMIT 20"

What the dashboard tells you

The D1 overview page is one of the more useful screens Cloudflare has, because it answers “am I anywhere near the limits” at a glance. Mine, after a day of real traffic:

Now hold those against the free plan, which as of September 2026 allows 5 million rows read per day and 100,000 rows written per day.

The point of showing my own unimpressive numbers is calibration. A portfolio contact form, a small dashboard, a side project with a few hundred daily visitors — these do not approach a free D1 allowance. The free tier is not a teaser that runs out the moment anyone visits. What does burn rows is a query pattern that reads a whole table on every page load; the fix there is an index, not a bigger plan.

Variables and secrets

This is where I nearly shipped something embarrassing, so it gets a section of its own.

There are two kinds of configuration on Pages and they behave nothing alike. Getting them the wrong way round is either a broken site or a leaked credential.

Set a secret once, from the terminal:

npx wrangler pages secret put TELEGRAM_BOT_TOKEN --project-name my-site
npx wrangler pages secret put TURNSTILE_SECRET_KEY --project-name my-site

It prompts, you paste, it is encrypted and stored. You cannot read it back afterwards — not through the CLI, not in the dashboard. That is the feature. Lose it and you rotate it; there is no recovery, and there does not need to be.

Public build-time values go in a .env file instead, and by convention are prefixed so nobody is confused about what they are:

PUBLIC_TURNSTILE_SITE_KEY=0x4AAAAAAA...

Updating the site

Once the wiring is done, this is the whole workflow — and it is worth designing it to be one command, because a deploy you have to think about is a deploy you will do badly at 1am.

./run deploy

Behind that, in order:

Updating the database is a separate motion, and deliberately so. Schema changes ship as SQL files applied with wrangler d1 execute --remote. Keeping them out of the deploy path is a feature: you almost never want “push the site” and “alter a live table” to be the same button.

Pointing your own domain at it

Every project gets a free <name>.pages.dev address and a working certificate immediately. Attaching your own domain takes about a minute.

In the dashboard: Workers & Pages → your project → Custom domains → Set up a domain.

What happens next depends on where your DNS lives.

Two things worth knowing afterwards. The pages.dev address keeps working — it is not replaced, and it stays useful as a way to check a deployment without touching the real domain. And the certificate covers your domain automatically, with renewal handled for you; there is no expiry date to diary.

Four traps that cost me time

What it actually costs

Every figure below is from Cloudflare’s own documentation, as of September 2026. The terms do move, so check them rather than trusting a blog post — including this one.

One line worth adding, because it surprised me: Cloudflare’s free plan includes 500 builds per month — but that quota is for builds Cloudflare runs. Build on your own machine and upload the result and you never touch it. Direct upload is not only the safer path for a private repository; it is the one with no build budget at all.

Where to read more

One last thing

The thing I did not expect was how much of this was deciding, not building. The code for a contact form is an afternoon. Choosing direct upload over a Git connection, deciding that the database write comes before the notification, making the deploy script refuse to ship a test key — those took longer and mattered more.

Every one of them came from the same question: when this breaks, how will I find out? A Git build that deploys the wrong project, a preview URL that looks like production, a bot filter that passes everything, a notification that silently stops — all four failed quietly. None of them threw an error. That is what made them expensive.

So the practical advice, more than any command in this post: after you wire something up, break it on purpose and check that you notice. If nothing tells you, add the thing that will.