# How to publish an Astro site on Cloudflare (2026 guide)

> Publish an Astro site on Cloudflare Workers for free: GitHub setup, custom domain, common errors, and what Claude and ChatGPT can and can't do.

- Author: [Vas](https://shipthemes.com/authors/vas)
- Published: Oct 26, 2026
- URL: https://shipthemes.com/blog/publish-astro-site-on-cloudflare

Your site is ready. You built it with AI or started from a template, and it looks great on your computer. What's left is the last step, which somehow turns out to be the most annoying one: showing the site to people. For that you need hosting (a computer where the site lives), an address, a secure connection and a way to update the site without pain.

In this guide, we'll walk through publishing an Astro site on Cloudflare. For most small sites it's free and needs no server of your own. We'll cover the whole path, from a folder of files to a working address on your own domain. Then we'll look at what Claude and ChatGPT/Codex can do for you and what you'll still have to click yourself.

> **Last verified: October 23, 2026.** Cloudflare changes its documentation and button names often. This guide was checked against the official Cloudflare and Astro documentation on that date. Every important claim carries a source number, and the full list of sources is at the end of the page.

## What you'll learn

1. What you need to get a site onto the internet.
2. What Cloudflare is good at, where it falls behind its competitors, and what it really costs.
3. Which sites Cloudflare suits and which are better off elsewhere.
4. How to publish a site manually through GitHub, from an empty account to your own domain.
5. What Claude and ChatGPT/Codex can and can't do when publishing, and how to avoid giving them too much access.
6. The three traps people hit most often, and how to get around them.
7. Answers to common questions.

## Short version: what to do

- For a new Astro site, choose Cloudflare **Workers** ("static assets" mode) rather than the older Pages. Cloudflare itself recommends starting new projects on Workers.[1]
- A site from a template is almost always static, and a static site doesn't need Astro's special "adapter": a small config file is enough.[2, 3]
- Put the project on GitHub and connect the repository to Cloudflare. After that, every update on GitHub rebuilds and publishes the site automatically.
- Buy your domain in Cloudflare or move its DNS there: Workers only works with domains whose nameservers are managed by Cloudflare.[4]
- AI will speed up setup but won't replace you: it can't create your account or pay for your domain. And give it only minimal access to your Cloudflare account.

## What you need to get a site onto the internet

AI builds an Astro project in a few minutes. But what you get is a folder of files on your own computer. To turn it into a website, you need a chain of steps, and each step has its own name:

- **Git and GitHub:** a version store for the project, where the host picks up your files;
- **build:** turning source files into finished pages;
- **hosting:** the computers that show your pages to visitors;
- **domain and DNS:** the site's address and the "phone book" that connects the address to the host;
- **SSL/HTTPS:** that little padlock in the address bar;
- **Node.js version:** the program that builds the site.

Each term is simple on its own. What feels hard is something else: error messages are cryptic and come with no explanation. So below you'll find a step-by-step guide with hints, and at the end, the three typical traps worth knowing about in advance.

First, let's see what makes Cloudflare a good fit for a site like this.

## Why Cloudflare works well for an Astro site

Cloudflare isn't the only way to put a site on the internet. But for a static Astro site it offers a set of advantages that are hard to find in one place.

### 1. Free, with no traffic limit on static files

Requests for static files (pages, images, styles) on Cloudflare Workers are free and unlimited.[5] Money and limits only enter the picture for server code: on the free plan it gets 100,000 requests per day.[6] A static site isn't affected, because your pages don't count as server code.

Free-plan limits worth knowing up front:[6, 7]

- up to 20,000 files per version of the site;
- up to 25 MiB per file;
- 3,000 minutes of automatic builds per month, one build at a time, each no longer than 20 minutes.

For a landing page, a blog or a company site, this is usually more than enough. You'll only pay for the domain.

### 2. The site updates itself after every save to GitHub

You connect a GitHub repository to Cloudflare once. After that, Cloudflare builds and publishes the site by itself whenever a new change arrives in the repository.[8] Developers call such a change a push. This is handy when AI edits your site: the edits go through GitHub and reach the live site on their own.

### 3. Previews and rollback

- **Previews.** Changes on a separate branch get their own link, so you can check edits before they reach the main site. Keep in mind that by default anyone who has a preview link can open it. You can restrict access with Cloudflare Access.[9]
- **Rollback.** If something breaks after publishing, you can restore any of the last 100 versions of the site.[10]

### 4. HTTPS and protection out of the box

The free Cloudflare plan includes DNS, DDoS protection with no cap on volume, a CDN and a free SSL certificate.[11] A CDN is a network of servers around the world that serves your site from the one closest to the visitor. The certificate for your domain is issued automatically, so there's nothing to configure.

On speed. Cloudflare itself says that 95% of internet users are within 50 milliseconds of its servers in 348 cities.[12] That's the company's own claim, not an independent measurement. We deliberately don't compare speed with other hosts: we couldn't find honest benchmarks with an open methodology.

### 5. A domain at cost

Cloudflare Registrar sells domains at cost: the company charges only what the registry (the operator of the domain zone) and ICANN charge, with no markup.[13] DNSSEC (extra protection for your address) is free too.[13] Hiding your personal details in the public WHOIS database is also free, if the zone allows it.[14] Check the exact price for your zone in the Cloudflare dashboard before you buy: it depends on the zone and can change.

### Comparison with alternatives

|  | Cloudflare (Workers, free plan) | Vercel (Hobby) | Netlify (Free) | GitHub Pages |
| --- | --- | --- | --- | --- |
| Price | $0, domain extra | $0 | $0 | $0 |
| Traffic for static files | Unlimited [5] | 100 GB per month [15] | Credit model: 300 credits per month, 20 credits per GB of traffic [16] | Soft limit of 100 GB per month [17] |
| Commercial sites | No explicit ban, but the plan is pitched at personal and hobby projects, and you can't collect card details on the site [11, 55] | Non-commercial, personal use only [15] | Not stated on the pricing page | Not intended for or allowed as free hosting for an online business, a store or another site mainly aimed at commercial transactions [17] |
| Branch previews | Yes [9] | Yes [58] | Yes [16] | No built-in option |

Two notes on the table. First, on Netlify's free plan, projects are paused when credits run out and stay paused until the next billing period.[16] Second, ordinary paid hosting will work too. But it gives you PHP, databases and other features a static site doesn't need, and you'd pay for it every month.

Prices change, so check the numbers against the linked sources before you launch a business.

## Who Cloudflare fits and who it doesn't

### It fits

- **Static sites:** landing pages, blogs, business-card sites, portfolios, documentation. Most sites built from Astro templates work this way: pages are built in advance and served as ready-made files.
- **Sites with a small server-side part.** Astro can create pages "on request". On Cloudflare this takes a special adapter and extra setup.[2] The free plan limits server code to 100,000 requests per day.[6]
- **Projects where the site is edited often.** Branch previews and version rollback (covered above) make experiments safer.

### Not a fit, or use caution

| Situation | What to know |
| --- | --- |
| The domain's DNS must stay with another provider, and you don't want to change its nameservers | Workers doesn't work with such domains, while the older Pages does. For Workers, you'll have to move the domain's DNS to Cloudflare. The domain itself can stay with its registrar [4] |
| The site has a lot of video or very heavy files | Under Cloudflare's CDN terms, video and other large files must be served through the company's paid services (for example, the Developer Platform, Images and Stream). If images, audio and large files make up a disproportionate share of a site, Cloudflare may limit access. The terms don't say how this applies to free Workers, so it's better to host video on a specialized service [18] |
| You need a contact form | A static page can't send an email on its own: you need a server-side handler. Cloudflare's email sending is in beta. Sending to your own verified addresses is free on every plan, while sending to arbitrary recipients requires a paid Workers plan.[19] The alternative is a third-party form service |
| A high-traffic site with server-side logic | The free plan limits server code: 100,000 requests per day and 10 ms of CPU time per request [6] |
| Files over 25 MiB, or more than 20,000 files in one version of the site | 25 MiB per file is the limit on every plan. 20,000 files per version is the free-plan limit; the paid plan allows 100,000 [6] |
| WordPress, PHP, ready-made CMSs | That's a different technology. It needs ordinary hosting |
| A commercial site, and you want legal clarity | We found no direct ban on commercial use of the free plan. But Cloudflare describes it as being for personal or hobby projects that aren't business-critical, and its terms forbid collecting credit card details on a site that uses free services [11, 55]. Read the terms before you launch a business |

### A simple rule for choosing

- A static Astro site, and the domain can move to Cloudflare: **Workers**. That's the path this guide covers.
- The domain's nameservers must stay with another provider: then choose either the older Pages (the platform is supported but develops more slowly) or another host. Whether that trade-off suits you is your call.
- You need a form: connect a third-party form service or add a server-side part. A static site won't send emails on its own.

## How to publish a site manually through GitHub: step by step

This method doesn't depend on AI and always works. You set it up once, and after that the site updates itself.

**What you'll need:**

- a free Cloudflare account;
- a free GitHub account;
- an Astro project on your computer (from a template or made by AI);
- Node.js and Git installed.

The commands below are typed into a terminal, a window for text commands (on macOS it's the Terminal app, on Windows it's PowerShell). Open it in your project folder. If the terminal scares you, you can hand the commands to an AI assistant; the next section covers that.

### Step 1. Check that the site builds on your computer

```bash
node -v
npm install
npm run build
```

The first command shows your Node.js version: you need 22.23.4 or newer, and 24 is better.[20] After the build, a `dist` folder appears in the project. That folder is the finished site. If the build fails, don't go any further: Cloudflare will repeat the same steps and fail on the same error.

To make the cloud build use the same Node.js version, create a `.nvmrc` file in the project root with a single line: `24`. Cloudflare reads this file during the build.[21]

### Step 2. Add the Cloudflare config file

Install Wrangler, Cloudflare's official tool for publishing sites:

```bash
npm install --save-dev wrangler@latest
```

Then create a `wrangler.jsonc` file in the project root with this content:

```jsonc
{
  "name": "my-astro-site",
  "compatibility_date": "2026-10-23",
  "previews": {},
  "assets": { "directory": "./dist" }
}
```

What each line means:

- `name` is the project name in Cloudflare: Latin letters, digits and hyphens. It becomes part of the site's temporary address, which looks like `name.your-subdomain.workers.dev`.[53] The name in the file must match the project name in the Cloudflare dashboard, or the build will fail with an error.[22]
- `compatibility_date` is the settings date in YYYY-MM-DD format. Use today's date.
- `previews` turns on preview links for branches (step 5). It's required for them and can stay empty.[51]
- `assets.directory` is the folder with the finished site. For Astro it's `dist`.[3, 23]

A static site doesn't need the Astro adapter for Cloudflare: Wrangler is the only extra package.[2] You can check the configuration without publishing it using this command:

```bash
npm run build && npx wrangler deploy --dry-run
```

If you want to show your own "404" page for addresses that don't exist, create a `src/pages/404.astro` file in the project and add the line `"not_found_handling": "404-page"` to the `assets` block.[24]

### Step 3. Put the project on GitHub

1. On github.com, create an **empty** repository: no README, no `.gitignore`, no license. It can be private.
2. In the terminal, in the project folder, run these commands one by one. GitHub shows the repository address on the new repository's page.[25]

```bash
git init -b main
git add .
git commit -m "First commit"
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
git push -u origin main
```

3. Check your `.gitignore` file: it should include `node_modules`, `dist`, `.wrangler` and `.dev.vars*`. Astro projects usually have it already. Never add passwords or access keys to the repository.

### Step 4. Connect the repository in Cloudflare

Interface labels in Cloudflare change from time to time, and even the documentation names them differently. For example, Astro's guide calls the section **Compute → Workers & Pages**, while Cloudflare's help calls it just **Workers & Pages**.[3, 8] If you can't find a button, look for the one with the same meaning.

1. Log in to the Cloudflare dashboard (dash.cloudflare.com). Open **Workers & Pages** and click **Create application**.[8]
2. Choose **GitHub** (or **GitLab**) and, if asked, sign in to that service. Astro's guide calls this step **Import a repository**.[3, 8]
3. Allow the **Cloudflare Workers & Pages** GitHub app to access your account. The docs also spell it "Workers and Pages": it's the same app, shared by Workers and Pages. We recommend choosing **Only select repositories** and ticking just the repository you need, so the app can't see your other projects.[26]
4. Select the repository and check the build settings:
   - **Project name** is the same as `name` in `wrangler.jsonc`;
   - **Build command** is `npm run build`. Astro's guide says `npx astro build`, but in a standard Astro project they do the same thing;[3]
   - **Deploy command** is `npx wrangler deploy`;
   - **Root directory**: leave it as the project root.
5. Click **Save and Deploy**. In a few minutes the site will be available at a temporary `workers.dev` address.[8]

If the repository has no `wrangler.jsonc` file, Cloudflare turns on auto-configuration and proposes changes in a separate pull request in your repository.[27] A static site doesn't need that. Add the file from step 2 beforehand. If the request has already arrived, look carefully at what it changes, and don't accept the installation of a server adapter.[2, 27]

### Step 5. Updates, previews and rollback

- **Updates.** Every change you push to the main branch triggers a new build and publish. By default, the main branch is the repository's default branch; you can change it in **Settings → Build → Branch control**.[8, 28]
- **Previews.** In the same place, turn on **Enable Preview Builds**.[28] Changes on any other branch get their own link; if the branch has a pull request, the link also appears in a comment on it.[26] For this, `package.json` must list Wrangler 4.135.0 or newer, and `wrangler.jsonc` needs the `previews` block.[9, 51] Step 2 takes care of both.
- **Rollback.** In the dashboard, open your project → **Deployments**, open the three-dot menu next to the version you want and choose **Rollback**. The last 100 versions are available.[10]

### Step 6. Connect your own domain

The temporary `workers.dev` address is fine for testing, but a real site needs its own domain.

**Option A. You don't have a domain yet.** Buy one right in Cloudflare: in the dashboard, open **Register domains**, find an available name and pay. Auto-renewal is on by default, and you need a verified email to buy.[29] Such a domain already uses Cloudflare's DNS servers, so there's nothing to move.

**Option B. The domain was bought from another registrar.** For Workers, you need to hand its DNS over to Cloudflare.[4] Here's how:

1. In the dashboard, open **Domains → Onboard a domain**, enter the domain and choose the free **Free** plan.
2. Check the imported DNS records. If email works on the domain, make sure the mail records (MX) are in place, or messages will stop arriving.
3. At your registrar, replace the nameservers (DNS servers) with the two addresses Cloudflare shows you.
4. Wait for the **Active** status. It can take up to 24 hours. If DNSSEC is on for the domain, turn it off before changing the DNS servers and turn it back on afterwards.[30]

**Connecting the domain to the site.** Open your project → **Settings → Domains & Routes → Add → Custom Domain**, enter the domain (`example.com`) or a subdomain (`www.example.com`) and click **Add Custom Domain**. Cloudflare creates the DNS record and the SSL certificate by itself. If a CNAME record already exists at that address, delete it first: it prevents the domain from being added.[31] To make both `example.com` and `www.example.com` work, connect one of them as the Custom Domain and send the other to it with a redirect rule; the address you redirect from needs a proxied DNS record.[31]

### Step 7. Keys and passwords (if your template needs them)

A typical static site needs no environment variables. If your template does require a key (for example, for an analytics service), add it under **Settings → Build → Build Variables and Secrets**.[21] These variables are available only during the build, not while the site is running.[32] If a key is needed by code that runs on Cloudflare's side, set it somewhere else: **Settings → Variables & Secrets**.[32] Don't paste keys into project files and don't push them to GitHub.

### Common errors and what to do about them

| What you see | Cause | What to do |
| --- | --- | --- |
| The build fails, and Astro says the Node.js version isn't supported | The Node.js version is too old | Use Node.js 24 and an `.nvmrc` file [20, 21] |
| "The name in your Wrangler configuration file (…) must match the name of your Worker" | The name in `wrangler.jsonc` doesn't match the project name in the dashboard | Make the names identical [22] |
| Publishing succeeded, but the site is empty or shows a 404 | The wrong folder in `assets.directory`, or the build isn't running | Check the build command and the `dist` folder [22] |
| "Missing entry-point" | Cloudflare can't find `wrangler.jsonc`: the file is missing, or the Root directory points somewhere else | Set the Root directory in **Settings → Build → Build Configuration**, or add the config file from step 2 [22] |
| "a namespace with this account ID and title already exists" (code 10014) | Most likely, auto-configuration added the adapter with a KV store, and a store with that title already exists in the account | Delete or rename the same-named store in the dashboard, or remove the adapter, add your own minimal `wrangler.jsonc` and update Wrangler [33, 56, 57] |
| "Build was timed out" | The build takes longer than 20 minutes | Simplify the build [22] |
| The domain shows "Pending Nameserver Update" | The nameservers haven't updated yet (up to 24 hours), or DNSSEC is in the way | Wait; check DNSSEC [30] |
| Errors connecting to GitHub or GitLab with no clear message (the "Git integration issues" section in Cloudflare's help) | Something is wrong with the Git connection | Remove Cloudflare's access to GitHub or GitLab, then connect it again [22] |

### Other ways to publish a site

- **From the terminal, without GitHub.** The command `npx wrangler login` opens a browser to sign in,[54] and `npx wrangler deploy` after `npm run build` publishes the site.[3] This is handy for a one-off publish, but you won't get automatic updates.
- **A temporary site without an account.** The command `npx wrangler deploy --temporary` (it needs Wrangler 4.102.0 or newer) publishes a site for 60 minutes with no sign-up. To keep it, you must confirm ownership through a special link within that hour. If you're already logged in to Cloudflare in this terminal, the command refuses to run. It's good for a demo, but not for a real site.[34]
- **The "Deploy to Cloudflare" button.** It works only with public repositories.[35] If your template is paid and sits in a private repository, this method won't work.
- **Dragging a folder into the browser.** Cloudflare Drop takes a folder, a `.zip` or a single `.html` file and publishes it to a `workers.dev` address with no account. The site stays live for an hour unless you claim it.[52] Like the temporary deploy, it's good for a demo. In the dashboard, Workers still offers no upload button. Pages has its own upload (Direct Upload), but after it you can't switch to a Git connection.[36]

## How to publish a site with Claude and ChatGPT

The phrase "let AI publish my site" can mean two different methods, and they have different capabilities.

1. **An AI agent works in your project folder** (Claude Code, Codex). It sees your files and runs the build and publish commands itself. This is how a site really gets onto the internet.
2. **AI is connected to your Cloudflare account through a connector.** It can look at and configure the account: projects, DNS records, storage. But judging by the server's description, the connector works through the Cloudflare API, not through your computer. So it can't see your project files and can't run a build.[37]

The main takeaway: a connector doesn't replace `git push` and the build. It helps with setup and diagnostics, while the site is published either by an AI agent in your folder or by the automatic build from GitHub (the steps above).

### What a connector is, in plain words

A connector is a "power outlet" that an AI assistant plugs into to reach an outside service. Technically, such outlets follow a standard called MCP (Model Context Protocol). Cloudflare has an official server at `https://mcp.cloudflare.com/mcp`: through it, AI can read Cloudflare's documentation and call almost any function of its API.[37] Cloudflare has marked its older separate servers (including Workers Builds and Workers Bindings) as deprecated and suggests moving to the main one.[38] Judging by their tool lists, they could look at builds and work with storage, but none of their tools uploaded site files.[38]

Claude's connector directory has a verified entry from Cloudflare called "Cloudflare Developer Platform".[39] It connects to `bindings.mcp.cloudflare.com`, the Workers Bindings server that Cloudflare has marked as deprecated.[38] Its description mentions deploying code, but its tools only list and read Workers and work with storage such as KV, D1 and R2: none of them publishes a site. So it's safer to add your own connector at the address above.

### What AI can and can't do

| Task | Cloudflare connector (Claude, ChatGPT, Codex) | AI agent in your folder (Claude Code, Codex) |
| --- | --- | --- |
| Create a Cloudflare account | No | No. But you can publish a temporary site with no account for 60 minutes [34] |
| Read project files and run `npm run build` | No: judging by the server's description, it works through the Cloudflare API and can't see your files [37] | Yes |
| Publish the built site | In practice, no | Yes, with `npx wrangler deploy` [3] |
| View projects, DNS records and account settings | Yes | Partly, through Wrangler |
| Confirm the GitHub app, pay for a domain | No, that's up to you | No, that's up to you |

### Method 1. An AI agent in the project folder (the most practical)

Claude Code and Codex are AI assistants for working with code: they run in your folder and execute commands on your instructions. The order is:

1. Sign in to Cloudflare yourself, once: run `npx wrangler login`, a browser opens, and you confirm the sign-in.[54] The AI doesn't need your password.
2. Start the assistant in the project folder and give it a task, for example:

```text
This is a static Astro site. Work step by step and stop after each step so I can confirm:
1) Read package.json and astro.config.mjs. Do NOT add the @astrojs/cloudflare adapter: the site is fully static.
2) Create a minimal wrangler.jsonc: name = "project-name", compatibility_date = today's date, assets.directory = "./dist".
3) Check the Node version (node -v: 22.23.4 or newer is required, 24 preferred), run npm ci, npm run build, then npx wrangler deploy --dry-run. Show me the output.
4) Only after I say "publish", run npx wrangler deploy and tell me the workers.dev address.
Never print or store my tokens. If a command fails, show me the error and suggest a fix, without changing dependencies unless I agree.
```

This is a starting point, not a guarantee: AI may act differently, so confirm every step and read what exactly it's about to run. For everyday updates you don't need to ask the AI to publish the site separately: let it make the edits and push to GitHub, and the automatic build will publish the site.

### Method 2. Connect the Cloudflare connector

Connecting is worth it if you want AI to help with account setup: check DNS records, find why a build failed, explain settings.

**Claude (website, desktop app).** On the Pro and Max plans, open Customize → Connectors, click + Add and choose Add custom connector. On Team and Enterprise, an organization owner adds a custom connector first (Organization settings → Connectors → Add → Custom → Web), and everyone else then connects it under Customize → Connectors.[40] Enter a name and the address `https://mcp.cloudflare.com/mcp`, then sign in through Cloudflare. A screen opens where you choose which permissions to grant.[37] After connecting, open Customize → Connectors, select the connector and set a mode in the Tool permissions block: Always allow, Needs approval or Blocked.[41] For tools that change something, we recommend Needs approval. Anthropic warns that custom connectors lead to services it hasn't verified, so connect only Cloudflare's official address. Also, Research mode can call tools without asking, so it's best to disable write tools there.[40]

**Claude Code.** To connect just the server itself, use Claude Code's standard command for remote MCP servers.[42] We picked the name `cloudflare-api` ourselves; any name works:

```bash
claude mcp add --transport http cloudflare-api https://mcp.cloudflare.com/mcp
```

Then, inside a session, open the server list with the `/mcp` command and sign in in your browser.[42] Cloudflare offers another path for Claude Code: a ready-made plugin that installs its skills for AI and registers its MCP servers, including the main one. It takes two commands: `/plugin marketplace add cloudflare/skills`, then `/plugin install cloudflare@cloudflare`.[43]

**Codex (OpenAI's AI assistant for development).** Cloudflare's main path is a plugin: run `/plugins` in Codex, find Cloudflare and install it (in the desktop app, open Plugins → Cloudflare).[44] To connect just the server, there's a command:

```bash
codex mcp add cloudflare --url https://mcp.cloudflare.com/mcp
```

After connecting, it helps to start with read-only requests:

```text
Using the Cloudflare connector, in read-only mode: find the project "project-name", show the last three builds and their status. If the latest one failed, read the log and explain the cause in plain words. Don't change anything.
```

### What about ChatGPT?

In ChatGPT, custom MCP connectors are added in developer mode, and only in the web version. According to OpenAI's help, actions that change something are currently available only on the Business, Enterprise and Edu plans. On the Pro plan you can connect MCP servers with read and fetch permissions. The help page says nothing about Plus or the free plan.[45] So for publishing, it's easier to use Codex as described above and keep ChatGPT as an assistant that explains steps and errors.

### How not to give AI too much access

Access to your account is access to your site and your domain. A few rules:

1. **Prefer signing in through the browser (OAuth) over pasting a token.** Start with read-only permissions. If a request needs more, the server asks you to sign in again and grant the extra permission.[37]
2. **If you do need a token** (for example, for automation), create it for one task only. Choose the minimum permissions and resources you need (for example, a single zone) and, if possible, an expiry time (the TTL field). The token's secret is shown only once.[46]
3. **Don't paste a token into a chat with AI and don't push it to GitHub.** Keep it in environment variables or a password manager.
4. **Any changes only after confirmation.** The Needs approval mode in Claude[41] is your safeguard against surprise actions.
5. **Connect only the official address,** `mcp.cloudflare.com`. Malicious MCP servers can contain hidden instructions for AI.[40]
6. **Limit Cloudflare's GitHub app to the repositories it needs.** You can revoke access in your GitHub settings (Settings → Applications). After the app is removed, new builds stop running, while the already published site keeps working.[26]
7. **The link for claiming a temporary site is a transfer of ownership.** Treat it like a password.[34]

### What stays with you

The shortest realistic path looks like this. AI prepares the config file and checks the build in your folder. You (or the AI, on your command) push the changes to GitHub. After that, Cloudflare's automatic build publishes the site. Your first sign-in to the account, confirming the GitHub app and paying for the domain stay with you. Cloudflare's documentation and the set of connectors change quickly, so check the commands against the pages in the list of sources before you start.

## Three traps worth knowing in advance

If publishing doesn't work, the cause is most often one of three things.

**1. Cloudflare has two products, and instructions online contradict each other.** Sites used to be hosted on Cloudflare Pages. Now Cloudflare calls Workers its main platform and advises starting new projects there.[1] The company's blog says Pages will continue to be supported, but all further investment and feature work goes to Workers.[47] Pages keeps working, and we found no official shutdown date. Still, the announcement confused even experienced developers, to the point that the tech lead for Workers had to say publicly that Cloudflare isn't sunsetting Pages.[48] Since version 13, the official Astro adapter for Cloudflare also works only with Workers.[49] And search results are full of Pages-era guides in which button names and steps no longer match reality.

**2. The Node.js version.** Node.js is the program Astro needs in order to build your site. The current Astro 7.4.2 requires Node.js 22.23.4 or newer, and odd-numbered versions such as 23 aren't supported.[20, 50] Many older guides name lower versions, and on an "almost right" version the build simply won't start. The simplest fix: use Node.js 24 and pin the version in the project. Step 1 above shows how. Cloudflare's cloud build already uses Node.js 24 by default.[21]

**3. Auto-configuration adds extras.** If you connect a repository with no config file to Cloudflare, Cloudflare detects the framework and proposes changes to your project in a separate pull request.[27] For Astro, that can mean installing a server adapter, even though your static site doesn't need one. The adapter adds a KV store for sessions, and Wrangler creates it automatically on publish, naming it after your Worker.[2, 56] That can cause conflicts: if the account already has a KV store with that title, publishing fails with the error "a namespace with this account ID and title already exists" (code 10014), as happened in one third-party project.[33] Older versions of Wrangler could also create such a store for a purely static site by mistake; Cloudflare fixed that in version 4.101.0.[57] Whether this applies to your site depends on what exactly auto-configuration adds. It's better to put your own minimal config file in the project beforehand (it's described in step 2 above).

## Summary

The main points of this guide:

1. For a new Astro site, use Cloudflare Workers with automatic builds from GitHub: Cloudflare itself recommends starting new projects on Workers.[1]
2. A static site doesn't need an adapter: a `wrangler.jsonc` file pointing to the `dist` folder is enough.[2, 23]
3. It's best to keep your domain in Cloudflare: Workers doesn't work with domains on other providers' DNS servers.[4]
4. AI agents speed up setup, but signing in to the account, paying for the domain and access rights stay under your control.
5. Give AI minimal permissions and confirm every action that changes something.

Before you point the domain at the site, check the sitemap, redirects and favicon: [“Sitemap, redirects and favicon in Astro: the pre-launch checklist”](https://shipthemes.com/blog/astro-sitemap-redirects-favicon).

### Want to skip the setup?

Most of the difficulties in this guide come not from your site but from the "plumbing" around it: the Node.js version, the config file, an unneeded adapter, the domain. ShipThemes templates are standard, static-first Astro projects, so they follow the path above as they are: add the `wrangler.jsonc` from step 2, and no adapter is needed. Each one comes with the full Astro source and every page from the live preview, and it's easy to edit with AI without ending up with the typical "AI look" (more in our article [How to avoid AI slop on a website built with AI](https://shipthemes.com/blog/avoid-ai-slop-on-ai-built-websites)). [Pick a template](https://shipthemes.com/templates), put it on GitHub and connect it to Cloudflare following the guide above.

An honest caveat: a template saves setup time but doesn't replace accounts and permissions. You still sign in to Cloudflare and GitHub, confirm the GitHub app and pay for the domain yourself.

## Frequently asked questions

### Is Cloudflare hosting really free for a website?

For a static site, yes: requests for static files are free and unlimited.[5] Free-plan limits: up to 20,000 files per site version, up to 25 MiB per file and 3,000 minutes of automatic builds per month.[6, 7] You'll pay for the domain and, if the site has server code, for requests above 100,000 per day. If your site is commercial, read Cloudflare's terms: we found no direct ban, but the Free plan is pitched at personal and hobby projects, and you can't collect card details on a site that uses it.[11, 55]

### What should I choose in 2026: Pages or Workers? Is Pages being shut down?

For a new project, Cloudflare recommends Workers.[1] Pages isn't shut down: Cloudflare says it will continue to be supported, but development and new features are going to Workers.[47] One reason to pick Pages is a domain that has to stay on another provider's DNS servers.[4]

### Do I need the @astrojs/cloudflare adapter for a static site?

No. For a static site, a `wrangler.jsonc` file is enough.[2, 23] The adapter is for creating pages on request; a fully static site doesn't need it. Make sure Cloudflare's auto-configuration doesn't add it unnecessarily.[27]

### Which build and publish commands should I use for Astro?

Build: `npm run build` (Astro's guide says `npx astro build`; in a standard project they're the same). Publish: `npx wrangler deploy`. The folder with the finished site: `dist`.[3]

### Which Node.js version should I choose?

Node.js 24. Astro 7.4.2 requires 22.23.4 or newer.[20, 50] Pin the version with an `.nvmrc` file.[21]

### Can I use a domain bought from another registrar?

Yes, but for Workers you need to move its DNS servers to Cloudflare.[4] The older Pages can also work with external DNS.[4] Changing DNS servers takes up to 24 hours.[30]

### How long do DNS and the SSL certificate take?

Activating a domain in Cloudflare takes up to 24 hours.[30] The SSL certificate for a Custom Domain is issued automatically,[31] but the documentation doesn't give an exact time.

### How can I check changes before publishing and roll back a mistake?

Turn on Preview Builds: changes on a separate branch get their own link for checking.[9, 26] If a mistake does reach the site, open Deployments and choose Rollback in the three-dot menu of the version you want: the last 100 are available.[10]

### Can I just drag the site folder into the browser?

For a quick demo, yes: Cloudflare Drop publishes a folder or a `.zip` to a `workers.dev` address with no account, and the site stays live for an hour unless you claim it.[52] For a real site, use Git or Wrangler. Pages has its own Direct Upload, but after it you can't switch to Git.[36]

### Can Claude or ChatGPT publish the site for me?

Partly. Claude Code and Codex can run the publish commands in your folder.[3] The Cloudflare connector manages the account but, judging by the server's description, can't see your files or run a build.[37] In ChatGPT, actions that change something are currently available only on the Business, Enterprise and Edu plans.[45]

### Is it safe to give AI a Cloudflare token?

Don't paste a token into a chat. It's better to sign in through the browser (OAuth) and start with read-only permissions. If you need a token, create it for one task: with minimal permissions, only for the resources you need and with a limited lifetime (TTL).[46] In Claude, set write tools to Needs approval.[41]

### How do I add a contact form to a static site?

A static page needs a server-side handler or a third-party form service. Cloudflare's email sending is in beta: sending to your own verified addresses is free on every plan, while sending to arbitrary recipients requires a paid Workers plan.[19]

## Sources

Pages checked on October 23, 2026.

1. Cloudflare Docs, [Pages](https://developers.cloudflare.com/pages/)
2. Astro Docs, [Cloudflare adapter](https://docs.astro.build/en/guides/integrations-guide/cloudflare/)
3. Astro Docs, [Deploy your Astro site to Cloudflare](https://docs.astro.build/en/guides/deploy/cloudflare/)
4. Cloudflare Docs, [Pages and Workers compatibility matrix](https://developers.cloudflare.com/workers/static-assets/compatibility-matrix/)
5. Cloudflare Docs, [Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/)
6. Cloudflare Docs, [Workers limits](https://developers.cloudflare.com/workers/platform/limits/)
7. Cloudflare Docs, [Workers Builds: limits and pricing](https://developers.cloudflare.com/workers/ci-cd/builds/limits-and-pricing/)
8. Cloudflare Docs, [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/)
9. Cloudflare Docs, [Workers Previews](https://developers.cloudflare.com/workers/previews/)
10. Cloudflare Docs, [Rollbacks](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/rollbacks/)
11. Cloudflare, [Plans](https://www.cloudflare.com/plans/)
12. Cloudflare, [Global network](https://www.cloudflare.com/network/) (the company's own statement about its network coverage)
13. Cloudflare Docs, [Registrar](https://developers.cloudflare.com/registrar/)
14. Cloudflare Docs, [Registrar: WHOIS redaction](https://developers.cloudflare.com/registrar/account-options/whois-redaction/)
15. Vercel Docs, [Hobby plan](https://vercel.com/docs/plans/hobby)
16. Netlify, [Pricing](https://www.netlify.com/pricing/)
17. GitHub Docs, [GitHub Pages limits](https://docs.github.com/en/pages/getting-started-with-github-pages/github-pages-limits)
18. Cloudflare, [Service-Specific Terms](https://www.cloudflare.com/service-specific-terms-application-services/)
19. Cloudflare Docs, [Email Service](https://developers.cloudflare.com/email-service/) (beta)
20. npm, [astro 7.4.2 package](https://registry.npmjs.org/astro/7.4.2)
21. Cloudflare Docs, [Workers Builds: build image](https://developers.cloudflare.com/workers/ci-cd/builds/build-image/)
22. Cloudflare Docs, [Workers Builds: troubleshooting](https://developers.cloudflare.com/workers/ci-cd/builds/troubleshoot/)
23. Cloudflare Docs, [Workers static assets: binding](https://developers.cloudflare.com/workers/static-assets/binding/)
24. Cloudflare Docs, [Static Site Generation (SSG) and custom 404 pages](https://developers.cloudflare.com/workers/static-assets/routing/static-site-generation/)
25. GitHub Docs, [Adding locally hosted code to GitHub](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github)
26. Cloudflare Docs, [Workers Builds: GitHub integration](https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/github-integration/)
27. Cloudflare Docs, [Workers Builds: automatic pull requests](https://developers.cloudflare.com/workers/ci-cd/builds/automatic-prs/)
28. Cloudflare Docs, [Workers Builds: build branches](https://developers.cloudflare.com/workers/ci-cd/builds/build-branches/)
29. Cloudflare Docs, [Registrar: register a domain](https://developers.cloudflare.com/registrar/get-started/register-domain/)
30. Cloudflare Docs, [DNS: full setup](https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/)
31. Cloudflare Docs, [Workers: custom domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/)
32. Cloudflare Docs, [Workers Builds: configuration](https://developers.cloudflare.com/workers/ci-cd/builds/configuration/)
33. GitHub, [issue emdash-cms/emdash #437](https://github.com/emdash-cms/emdash/issues/437) (an example of error 10014 in a third-party project)
34. Cloudflare Docs, [Temporary accounts (claim deployments)](https://developers.cloudflare.com/workers/platform/claim-deployments/)
35. Cloudflare Docs, [Deploy to Cloudflare buttons](https://developers.cloudflare.com/workers/platform/deploy-buttons/)
36. Cloudflare Docs, [Pages: Direct Upload](https://developers.cloudflare.com/pages/get-started/direct-upload/)
37. GitHub, [cloudflare/mcp](https://github.com/cloudflare/mcp) (the official Cloudflare API MCP server)
38. GitHub, [cloudflare/mcp-server-cloudflare](https://github.com/cloudflare/mcp-server-cloudflare) (see the "Deprecated servers" section)
39. Claude, [Cloudflare Developer Platform connector](https://claude.com/connectors/cloudflare)
40. Claude Help Center, [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
41. Claude Help Center, [Use connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities)
42. Claude Code Docs, [MCP](https://code.claude.com/docs/en/mcp)
43. Cloudflare Docs, [Agent setup: Claude Code](https://developers.cloudflare.com/agent-setup/claude-code/)
44. Cloudflare Docs, [Agent setup: Codex](https://developers.cloudflare.com/agent-setup/codex/)
45. OpenAI Help Center, [Developer mode and MCP in ChatGPT](https://help.openai.com/en/articles/12584461)
46. Cloudflare Docs, [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
47. Cloudflare Blog, [Your frontend, backend, and database now in one Cloudflare Worker](https://blog.cloudflare.com/full-stack-development-on-cloudflare-workers/) (April 8, 2025)
48. Kenton Varda, tech lead for Cloudflare Workers, [comment on Hacker News](https://news.ycombinator.com/item?id=46037452) (November 2025)
49. Astro, [changelog of the @astrojs/cloudflare adapter](https://github.com/withastro/astro/blob/main/packages/integrations/cloudflare/CHANGELOG.md)
50. Astro Docs, [Install and setup](https://docs.astro.build/en/install-and-setup/)
51. Cloudflare Docs, [Workers Previews: configuration](https://developers.cloudflare.com/workers/previews/configuration/)
52. Cloudflare Changelog, [Cloudflare Drop](https://developers.cloudflare.com/changelog/post/2026-07-08-cloudflare-drag-and-drop/) (July 8, 2026)
53. Cloudflare Docs, [workers.dev](https://developers.cloudflare.com/workers/configuration/routing/workers-dev/)
54. Cloudflare Docs, [Wrangler commands: general](https://developers.cloudflare.com/workers/wrangler/commands/general/)
55. Cloudflare, [Self-Serve Subscription Agreement](https://www.cloudflare.com/terms/)
56. Cloudflare Docs, [Wrangler configuration: automatic provisioning](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning)
57. GitHub, [issue cloudflare/workers-sdk #14262](https://github.com/cloudflare/workers-sdk/issues/14262) (fixed in Wrangler 4.101.0)
58. Vercel Docs, [Environments](https://vercel.com/docs/deployments/environments)
