You merge a pull request on GitHub. A moment later, the website at your domain shows the change. There is no server to patch, no FTP client and no hosting bill at the end of the month.
That is the setup this guide builds, and you can host a website for free on Cloudflare this way. The catch is that most tutorials still show you the old way to do it. Cloudflare's own Pages documentation now says, right at the top: "Start new projects with Workers." So this guide uses Workers, the product Cloudflare recommends today, and it works for a plain static site with no server code at all.
This post covers four things:
- How to generate a professional website with AI: realistic product photos and a site with 3D tilt and depth effects, from two prompts you can copy (both are in the repository).
- The two small files that turn a folder of HTML into a Cloudflare project.
- How to connect GitHub to Cloudflare so every merge to
maingoes to production. - How to use the free
workers.devURL or add your own domain.
If you are new to web development, this is one of the best first setups you can pick. There is no server to configure or keep updated, nothing is compiled during the deploy (the one bundled file is built on your machine and committed, more on that in step 1), HTTPS comes for free, and a bad change is one rollback away. You also learn the workflow professional teams use (branch, pull request, merge, automatic deploy) from your first website, instead of unlearning FTP uploads later.
The demo site, Ember Lane Coffee, is a fictional brand. See it live first: ember-lane-coffee.diogosoares-dev.workers.dev, then come back for how it was built. The whole project is open source so you can copy it.
🧩 Free on GitHub: github.com/soaresdiogo/cloudflare-website-template: the code, the images, the scroll clip and both prompts in PROMPT.md.
What "free" actually means on Cloudflare
Before you move anything, know where the free tier ends. These are the numbers from Cloudflare's docs at the time of writing (November 2026):
| Item | Free plan |
|---|---|
| Requests to static files (HTML, CSS, JS, images) | Free and unlimited |
| Requests that run Worker code | 100,000 per day, reset at midnight UTC |
| Files per deployment | 20,000 (100,000 on the paid plan) |
| Size of one file | 25 MiB |
| HTTPS certificate | Included |
A <name>.<subdomain>.workers.dev URL |
Included |
| Automatic builds from GitHub (Workers Builds) | 3,000 build minutes per month, one build at a time, 20-minute timeout |
| Your own domain | You pay the registrar. Cloudflare Registrar sells at cost, with no markup |
The site in this guide has no Worker code. Every request is a request for a static file, so the 100,000-per-day limit doesn't apply to it. For a static website, the only money you may spend is the domain name.
That changes if you add server-side code later (a contact form handler, an API). Those requests count against the daily limit. For most small sites that is still a lot of room, but it is a limit, not a promise.
One cost that is not Cloudflare's: the AI agent you use to generate the site. Claude Code needs a paid Claude plan or API credits; Cursor and Codex have free tiers, but their limits are tight, so a full site may push you onto a paid plan. "Free" here means free hosting, not a free tool chain. You can skip the agent entirely and start from the template.
Pages or Workers?
If you search for this topic, most results show Cloudflare Pages. Pages still works and is still supported, but the Pages docs now say Workers "supports most Pages use cases and offers a broader feature set" and recommend it for new projects. Workers can serve a folder of static files on its own, which Cloudflare calls static assets.
| Pages | Workers with static assets | |
|---|---|---|
| Cloudflare's recommendation for new projects | No | Yes |
| Static files free and unlimited | Yes | Yes |
| Git integration with preview builds | Yes | Yes (Workers Builds) |
| Add server code later (APIs, cron jobs, queues) | Limited | Yes, same project |
| Custom domain with DNS hosted outside Cloudflare | Subdomains only (a CNAME at your DNS host); the apex domain needs Cloudflare DNS | No: the domain must use Cloudflare's nameservers |
The last row is the one real reason to still pick Pages: if your DNS must stay outside Cloudflare and a subdomain such as www.example.com is enough, Pages can attach to it with a CNAME; Workers can't. For everyone else, Workers is the better starting point, because the day you need a bit of server code you add it to the same project instead of migrating.
Step 0: What you need
- A GitHub account.
- A free Cloudflare account.
- Git installed.
- Node.js 22.12 or newer. The current Wrangler (Cloudflare's CLI) declares
node >= 22.12.0in its package. Check withnode -v. - An AI coding agent if you want to generate the site (Claude Code, Cursor, Codex or similar). You can also skip that step and start from the template.
No domain is needed. You get a free URL in step 5.
Step 1: Generate the site with AI, without the generic look
Ask a current AI agent to "build me a website for my coffee shop" and you no longer get an ugly page. You get a good-looking page for a business that doesn't exist: an invented name, an invented menu, invented prices and stock photos of someone else's café. It looks finished, and almost none of it is yours.
The fix is a brief, not a better model. And for a site that looks premium, you need two briefs: one for the images and one for the site. Code alone can't make a photo-realistic product; the realism comes from the pictures, and the code's job is to stage them well.
Three levels of AI-generated website
Before asking an agent for a "premium" site, decide which level you need. Each one adds visual impact and also weight, complexity and things that can break:
| Level | What it is | Techniques | Good for |
|---|---|---|---|
| 1. Static professional | Strong typography, art direction, good photos, clean layout | HTML, CSS, a little JavaScript | Most small businesses, portfolios, a first site |
| 2. Motion-driven | The page reacts to scroll and cursor, with real depth | CSS 3D transforms, layered parallax, scroll-triggered animation (GSAP or native APIs), scroll-scrubbed video, microinteractions | Product launches, brands that sell a feeling |
| 3. Immersive 3D | Real-time 3D objects in the page | WebGL with Three.js, 3D models (GLB), shaders | A product you can turn around, a portfolio piece |
All three host the same way on Cloudflare, for free, because they are all static files. The demo is level 2: photo-realistic images, a product that tilts in real 3D perspective, layers that move at different depths and a video that plays with the scroll. I also tried level 3, and the section at the end of this step explains why I took it out.
Realistic images without a photo shoot
You have two free or almost free options:
- Free stock photos from sites like Unsplash or Pexels, whose licenses allow commercial use without attribution (with limits, such as not reselling unaltered copies). They are real photos, but they can't show your product with your label.
- AI-generated images. You describe the product, the label and the light, and you get a mockup of your own brand. The demo uses this: I asked Codex, using the image generation included in my ChatGPT plan, for all seven images in one request.
Here is the image prompt, trimmed (the full one is in PROMPT.md):
Create photorealistic product images for a website. Keep one consistent art
direction across all images: premium studio product photography, soft diffused
key light from the upper left, gentle realistic contact shadows, warm neutral
colour grading, no text other than the label text specified, no other brands.
Brand: [Ember Lane] (fictional). Label: [a line-art flame inside a thin circle,
"EMBER LANE" in an elegant serif]. Palette: [espresso, ember, honey, cream].
1. bag-hero.png: [a matte espresso-brown stand-up coffee pouch with a folded top
and a tin-tie, slight three-quarter angle]. Transparent background.
2-4. [one bag per product, same design and angle, different colour and name].
5-6. [two piles of roasted beans, one from the left edge, one from the right].
7. [a landscape photo of the roastery]. No faces, no readable brand names.
Three details made the difference:
- One request for all images, with one light direction. Images generated separately come back with different light and colour, and the page looks like a collage.
- Transparent backgrounds for the bags and the beans, so they sit on the page's own background and can move independently.
-
WebP, resized for the page. The PNGs were about 1 to 3 MB each. After
cwebpat the size they are displayed, all seven images together are about 620 KB.
One rule of honesty: the demo's footer says the photos are AI-generated, because the brand is fictional. For a real business, photograph your real product and use AI for mockups and backgrounds, not for pictures customers will take as the thing they will receive.
The website prompt
A good website prompt answers the questions a designer would ask in the first meeting: who is it for, what should the visitor do, what are the real facts, what should it look like, and what are the technical rules. Here is the structure of the one I used, trimmed. Both prompts in full, the photo prompt and the website prompt, are in PROMPT.md on GitHub, next to everything else the demo uses (the code, the images and the video clip): copy them and replace the [brackets] with your business.
You are a senior creative developer and art director. Build a premium,
production-ready marketing website for the business below. It must not look
like a generic template.
## The business
- Name, what it does in one sentence, who it is for: [...]
- The one action a visitor should take: [start a coffee subscription]
- Real facts I want on the page (use only these, never invent numbers): [...]
## Assets
Use only the images in ./public/images. Don't draw replacements.
## Art direction
- A large centred serif headline, generous negative space, a restrained palette
defined once as CSS custom properties.
- [Fraunces] self-hosted for headings. No third-party font CDNs.
- Hero: headline and buttons centred, the bag centred below them, bean piles
bleeding off the left and right edges, one feature callout on each side.
## Depth and motion
- Bean piles and callouts move against the cursor, closer layers more, at most
36 px.
- The bag tilts in 3D toward the cursor (at most 10 degrees) and rises 90 px
while the hero scrolls away.
- GSAP with ScrollTrigger, bundled locally. Nothing loads if the visitor
prefers reduced motion; without JavaScript the page is complete.
## Technical rules
- Plain HTML, CSS and vanilla JavaScript. No framework, no build on deploy.
- No inline <script>, no inline event handlers, no style="" attributes,
so a strict Content-Security-Policy works.
## Before you finish
Run `npx wrangler dev`, open the page at 1440 px and 390 px wide, with and
without JavaScript, fix anything that breaks, and list what I must replace.
Five parts of it do most of the work:
- "Use only these facts, never invent numbers." Without it, the agent fills empty space with fake statistics. On a real business site, a made-up number is worse than no number.
- A described composition. "Premium" means nothing to a model. "Headline centred, product below, beans bleeding off the edges" is a layout it can build.
- Named effects with numbers. "Make it 3D and modern" gives a random result. The object, the motion and its limits (36 px, 10 degrees) give you the one you pictured.
- No inline scripts or styles. This sounds like a detail, but it is what allows the security headers in step 3 to block injected scripts without exceptions.
- The self-check at the end. An agent with browser access that opens its own page at two widths catches many layout bugs before you ever see them.
Generic prompt vs. a real brief
To be clear about the tools: I built the live Ember Lane demo with Claude Code, and the photos with Codex. For a fair test of the two prompts, both runs below used the same agent and model, Codex CLI 0.165.0 with gpt-6.1-sol, on 12 November 2026, each run in its own empty folder. The left run got only "Build me a website for my coffee shop." The right run got the website brief above, and its folder also held the seven product photos and the font files.
The one-line result surprised me: it is well designed. But the agent had to invent everything it wasn't given. It called the shop "Morrow Coffee", wrote a menu with prices, used two café photos that its README credits to Unsplash, and, to its credit, labelled all of it as sample content. There were no Cloudflare files and no security headers. It also published a private preview to its own ChatGPT hosting without being asked, which is worth knowing before you paste real business data into a one-line request.
The brief run used the real name, the real facts (Tuesday roasts, 12 kg batches, 48 hours of rest, the three prices), the product photos, the requested composition, wrangler.jsonc and the _headers file. It couldn't run the self-check at the end, because that Codex session had no browser, and it said so in its summary instead of claiming it had.
A one-line prompt gets you a nice website. The brief and your own assets get you your website. The design quality was never the hard part; the facts, the assets and the deployment rules are.
Depth and motion that don't slow the site down
Designers have names for these effects, and those names map to techniques an agent knows. Use them in the prompt:
| What you want | Words to put in the prompt | What it usually means in code |
|---|---|---|
| Depth from flat images | Layered depth, multi-layer parallax | Layers moving at different speeds |
| An object that turns | 3D perspective, hover tilt | CSS perspective with rotateX and rotateY
|
| Things that appear on scroll | Scroll-triggered reveals, staggered reveals | An animation that starts once when an element enters the screen (IntersectionObserver) |
| Motion tied to the scroll position | Scroll scrubbing, pinned sections | Scroll progress driving a value continuously, forwards and backwards (GSAP ScrollTrigger with scrub) |
| Video tied to the scroll | Scroll-scrubbed video | A pinned section where the scroll sets the video's currentTime
|
| Interaction | Cursor-driven interaction, magnetic buttons | Pointer position driving rotation or position |
| Objects with real 3D shape and light | Real-time WebGL scene, Three.js, physically based materials | A <canvas> rendered by Three.js, usually with a GLB model |
| Special materials | Glassmorphism, iridescent materials, fragment shaders |
backdrop-filter; Three.js materials; custom GLSL |
The demo picks four and describes them exactly:
- Layered depth. The bean piles and the feature callouts move against the cursor at different strengths, so the flat photos read as objects at different distances.
- The bag turns in 3D. It tilts toward the cursor in real perspective, and when you scroll, it rises and rotates slightly while the bean piles drift outward (scroll scrubbing with GSAP's ScrollTrigger).
-
Cards that tilt toward the pointer, at most 8 degrees, with a few lines of vanilla JavaScript and CSS
perspective(no GSAP). - A brewing clip the scroll plays. The "Brew it at home" section stays pinned while you scroll, and the scroll position moves a Chemex clip from the grounds falling, to the bloom, to the pour. Scroll back and the shot rewinds. Details below.
Motion is where a nice site becomes a slow or fragile one, so the prompt adds three rules:
-
Progressive enhancement. The page is complete without the motion layer. It loads with a dynamic
import()only if the visitor has not turned on "reduce motion" in their system settings, and with JavaScript off, everything is still there. -
Bundle the library locally. GSAP is installed with npm and bundled with esbuild into one file inside
public/, committed to the repository. No CDN means the security policy in step 3 stays at'self'. GSAP is free to use, under its own standard license rather than MIT. - A weight budget. The motion bundle is about 118 KB minified, 46 KB gzipped, and it only downloads for visitors who will see the motion.
The loader in main.js is small:
// Progressive enhancement: the page is complete without this module.
async function setUpMotion() {
if (prefersReducedMotion) return;
try {
const { startMotion } = await import("/js/motion.js");
startMotion();
} catch (error) {
console.warn("Motion layer unavailable, showing the static page.", error);
}
}
A video that follows the scroll
Some of the most striking "AI websites" you see on social media are not 3D at all. They are a pre-rendered video, and the scroll controls which frame you see. The demo does this in the "Brew it at home" section: three steps in plain HTML on the left, a Chemex clip on the right, and the section stays pinned for two and a half screen heights while the clip plays forwards or backwards with your scroll.
The core is a few lines of ScrollTrigger:
ScrollTrigger.create({
trigger: section,
start: "top top",
end: "+=250%",
pin: true,
scrub: true,
onUpdate: ({ progress }) => {
showStep(activeStepIndex(progress));
if (Number.isFinite(video.duration)) video.currentTime = progress * (video.duration - 0.05);
},
});
Four details make it work in practice:
-
Encode for seeking. A normal video stores a full frame only every few seconds, so jumping to a random time is slow and choppy. The demo's clip has a full frame every 6 frames (
ffmpeg ... -g 6 -bf 0), which keeps scrubbing smooth at 2.6 MB for 19 seconds of 540 × 960 video. -
Load it as a blob. Jumping around in a video needs the server to answer HTTP range requests, and the local
wrangler devserver didn't. The demo downloads the clip withfetch()and plays it from a blob URL, which works on any server. That is why the security policy hasmedia-src 'self' blob:. It also waits to download the clip until the visitor is close to the section. - Keep the words in HTML. The step titles and text are real headings and paragraphs, not part of the video, so search engines, screen readers and translation tools can read them.
- A still image for everyone else. Without JavaScript, or with reduced motion turned on, the section shows a still frame and all three steps, with no pinning.
The clip joins three shots from the same session, which is why the light and background match. For a real business, film your own product: a phone on a tripod and a plain background are enough for a shot like this. An AI video model can also generate one from your product photos, but that costs credits.
What I tried and removed: real-time 3D beans
The first version of the demo had a real WebGL scene: coffee beans modelled in code with Three.js, floating in front of the photos and turning with the cursor. Technically it worked. Visually, next to the AI-generated photos, the beans looked like chocolate. A shape made from a stretched sphere with a crease can't match a photo, and the mix broke the realism that the photos had built. It also cost another 136 KB gzipped.
So I took it out. Don't mix photo-realistic images with low-fidelity procedural 3D unless you can match their lighting, materials and detail. I couldn't, in a reasonable time, with a few lines of geometry. For a real level 3 site, render a real 3D model of the product (a GLB file made by a 3D artist or by an image-to-3D tool) with Three.js, and keep the same rules: load it only when WebGL works and motion is allowed, and keep the page complete without it.
A note for beginners on "no build": you will see npm run build:js in the repository. That command runs only on your machine, and only when you change src/motion.js; it writes public/js/motion.js, which you commit like any other file. Cloudflare never runs it. If you never touch the motion code, you never run it.
Plain HTML is a deliberate choice here, not a limitation. A one-page marketing site doesn't need React. Without a build step on deploy, the folder you commit is the folder Cloudflare serves, and there is nothing to break between the two. The motion bundle is the one exception, and you rebuild it on your machine (npm run build:js) only when you change it. If your site grows into many pages with shared layouts, a static site generator such as Astro also deploys to Workers as static files. Next.js runs on Workers too, through vinext or the OpenNext adapter, but then pages are rendered by Worker code, which counts against the free daily request limit (a static export with output: "export" does not).
Step 2: The two files that make it a Cloudflare project
These are the files that matter (the repository also has a README, PROMPT.md, a LICENSE, .gitignore, .node-version and the lockfile):
cloudflare-website-template/
public/
index.html
404.html
styles.css
main.js
js/motion.js
images/ (8 WebP images)
video/ (the Chemex clip)
fonts/ (Fraunces, self-hosted)
favicon.svg
robots.txt
_headers
src/motion.js
wrangler.jsonc
package.json
Everything inside public/ is the website. The two files at the root tell Cloudflare how to serve it. First, wrangler.jsonc:
{
"$schema": "./node_modules/wrangler/config-schema.json",
// The Worker name becomes the free URL: <name>.<your-subdomain>.workers.dev
"name": "ember-lane-coffee",
"compatibility_date": "2026-10-28",
// No "main" script: this Worker only serves the files in ./public
"assets": {
"directory": "./public",
"not_found_handling": "404-page"
},
// Pull request previews need this block; empty is enough for a static site
"previews": {}
}
Three things matter in it:
-
namebecomes part of your free URL, and it must match the Worker's name in the Cloudflare dashboard. If they differ, the build fails with an error saying exactly that. Use lowercase letters, numbers and dashes. -
There is no
mainfield. That field points to a Worker script; without it, Cloudflare only serves the files inassets.directory. This is what keeps every request free. -
not_found_handling: "404-page"serves your404.htmlwith a real 404 status for any URL that doesn't exist. Without it, a missing page returns a bare 404 with no page of yours. For a single-page app (React, Vue) you would use"single-page-application"instead, which returnsindex.htmlfor every unknown path.
A trap I hit while building the demo: I first set compatibility_date to a recent date, 2026-11-01, and the local server refused to start with This Worker requires compatibility date "2026-11-01", but the newest date supported by this server binary is "2026-10-30". The compatibility date tells Cloudflare which runtime behavior your project expects, and it can't be newer than what your Wrangler version knows. Set it to a date a little before the release date of the Wrangler version you install, and leave it alone afterwards.
The second file is package.json (the relevant part below), which pins the Wrangler version so your machine and Cloudflare's build use the same one:
{
"name": "cloudflare-website-template",
"private": true,
"scripts": {
"dev": "wrangler dev",
"deploy": "wrangler deploy",
"build:js": "esbuild src/motion.js --bundle --minify --format=esm --target=es2020 --legal-comments=eof --outfile=public/js/motion.js"
},
"engines": {
"node": ">=22.12.0"
},
"devDependencies": {
"@fontsource-variable/fraunces": "5.3.0",
"esbuild": "0.28.2",
"gsap": "3.15.0",
"wrangler": "4.155.0"
}
}
The exact versions (no ^) and the package-lock.json that npm install creates mean the build doesn't silently pick up a new release the day it comes out. esbuild and GSAP are only used on your machine to produce the motion bundle, and the font package is where the files in public/fonts were copied from; Cloudflare's build installs them but doesn't use them, and the deploy only uploads public/.
Step 3: Security headers with one text file
A static site has a small attack surface, but it still runs in your visitors' browsers. Workers static assets read a plain text file called _headers from the assets folder and add those headers to every response:
/*
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self' blob:; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()
X-Frame-Options: DENY
The /* line means "every path". The Content-Security-Policy only allows scripts, styles and images from your own domain, and frame-ancestors 'none' stops other sites from embedding yours in an iframe (clickjacking). This is why the prompt bans inline scripts and style="" attributes: with them, the policy would need 'unsafe-inline', which removes most of its protection against injected scripts.
Two notes. The _headers file itself is not served to visitors; requesting /_headers returns a 404. And if you later add Google Fonts, analytics or an embedded video, you must add their domains to the policy, or the browser will block them. The browser console tells you exactly which domain was blocked. Also, includeSubDomains forces HTTPS on every subdomain of your domain for a year; remove it if any subdomain still serves plain HTTP.
Step 4: Run it locally, then push it to GitHub
Install the dependencies and start the local server:
npm install
npm run dev
Wrangler serves the site at http://localhost:8787 using the same runtime Cloudflare runs in production, including the _headers rules and the 404 handling. You can check the headers from a second terminal:
curl -sI http://localhost:8787/ | grep -i content-security-policy
When the site looks right, create a repository on GitHub (an empty one, without a README) and push:
git init -b main
git add .
git commit -m "First version of the website"
git remote add origin https://github.com/<your-user>/<your-repo>.git
git push -u origin main
Check that node_modules/ and .wrangler/ are in .gitignore before the first commit. The template already has them.
Step 5: Connect GitHub to Cloudflare
This is the step that makes it automatic. Cloudflare's feature for it is called Workers Builds: it watches your repository and runs the deploy for you.
- In the Cloudflare dashboard, open Workers & Pages and select Create application.
- Select GitHub and authenticate if asked. GitHub asks you to install the Cloudflare Workers and Pages app.
- When GitHub asks which repositories the app can access, pick Only select repositories and choose this one. The app doesn't need to see the rest of your account.
- Back in Cloudflare, select the repository and review the settings:
-
Worker name: the same value as
nameinwrangler.jsonc. - Build command: leave it empty. There is nothing to build.
-
Deploy command: the default,
npx wrangler deploy. -
Root directory: leave it empty if
wrangler.jsoncis at the root of the repository.
-
Worker name: the same value as
- Select Save and Deploy.
The first build installs the dependencies, runs npx wrangler deploy, and publishes the site. When it finishes, the dashboard shows your free URL:
https://ember-lane-coffee.<your-subdomain>.workers.dev
The <your-subdomain> part is your account's workers.dev subdomain, chosen once per account. That URL is real, has HTTPS, and you can share it today.
Step 6: Every merge to main goes to production
From now on, the production branch is your repository's default branch, main. Cloudflare's docs describe it like this: a build on the production branch creates a new version and, with the deploy command, promotes it to the active deployment. In practice:
feature branch -> pull request -> review -> merge to main -> build -> live
The workflow I'd recommend, even if you work alone:
git switch -c update-prices
# edit public/index.html
git commit -am "Update subscription prices"
git push -u origin update-prices
Then open a pull request on GitHub, look at the change, and merge it. The merge is the deploy. You never run a deploy command by hand, and you never upload files from your laptop.
To be precise about what triggers it: Cloudflare deploys on any push to main, and a merge is just one kind of push. A git push straight to main goes live too. The pull request and the review are a practice, not something Cloudflare enforces. If you want GitHub to enforce it, add a branch protection rule on main that requires a pull request, and turn on Do not allow bypassing the above settings, because by default the rule doesn't apply to you as the admin. On a free GitHub account this works only for public repositories; private ones need GitHub Pro.
You can also get a preview of each branch before merging. A new Worker connected to GitHub builds non-production branches by default (the setting is under Settings > Build > Branch control), with npx wrangler preview, which gives each branch its own URL in the format <branch>-<worker-name>.<subdomain>.workers.dev. The build shows up as a check on the pull request, and the bot can also comment with the link: in my test it commented on the first pull request but not on the second, so look at the check.
One trap I hit: my first preview build failed with "Your Wrangler configuration is missing a previews block". Worker Previews need that block in wrangler.jsonc, and for a static site it can be empty: "previews": {}. The template already has it.
Two things to know about previews: their URLs are public by default (anyone with the link can open them, so don't put unreleased secrets there), and the free plan allows up to 100 previews per Worker.
If a deploy goes wrong, roll back. In the Worker's Deployments tab, open the menu next to an earlier version and select Rollback; it goes live immediately. Then fix it in a new commit, because the next merge to main deploys whatever is in the branch.
Step 7: Your own domain (or keep the free URL)
The workers.dev URL is enough for a portfolio, a test or a site you share by link. Cloudflare itself recommends a custom domain for production Workers, and for a business a domain is also what people remember.
A Worker can only use a domain that is an active zone on your Cloudflare account, which means Cloudflare must manage its DNS. There are two ways to get there.
Option A: buy the domain at Cloudflare. Domains bought through Cloudflare Registrar already use Cloudflare's DNS, so there is nothing to configure. You pay the registry and ICANN price, with no markup.
Option B: keep the domain where you bought it and move only the DNS. In the dashboard, go to Domains, choose Onboard a domain, enter it (example.com, without www) and pick the Free plan. Cloudflare scans your existing DNS records and shows two nameservers. Then, at your registrar:
- If DNSSEC is on, turn it off first. Changing nameservers with DNSSEC active can make the domain unreachable.
- Replace the current nameservers with the two from Cloudflare, copied exactly.
- Wait. Cloudflare's docs say it can take up to 24 hours; you get an e-mail when the domain is Active.
Review the scanned records before you switch, especially the e-mail ones (MX, TXT). If one is missing, your e-mail stops working after the change, and that problem has nothing to do with the website.
With the domain active, attach it to the Worker:
- Open the Worker, then Settings > Domains & Routes.
- Select Add, then Custom Domain.
- Type the domain (for example
example.com) and confirm.
Cloudflare creates the DNS record pointing to the Worker and issues the HTTPS certificate for you. Add www.example.com the same way if you want both to work, since a custom domain covers exactly one hostname. One more limit from the docs: you can't create a custom domain on a hostname that already has a CNAME record, so delete the old record that pointed to your previous host first.
The workers.dev URL keeps working after you add the domain. If you want only your domain to answer, turn off the workers.dev route in the same Domains & Routes screen.
When this setup is the wrong choice
| Situation | Better option |
|---|---|
| You can't move your domain's DNS to Cloudflare | Cloudflare Pages on a subdomain (it supports external DNS for subdomains, not for the apex), or another static host |
| The site needs a CMS that non-technical people edit | A hosted CMS, or a static site generator with a Git-based CMS on top |
| You need server-side code with heavy traffic | Still Workers, but plan for the paid plan once the code runs on most requests |
| You deploy from a pipeline you already have (tests, other steps) | Keep your CI and deploy with the official cloudflare/wrangler-action for GitHub Actions |
And one honest limit of "free": the free tier is a business decision by Cloudflare, not a law. It is generous for static files today, but if your business depends on the site, keep the code in Git (you already do) so moving to another host is a weekend, not a rewrite.
FAQ
Is it really free, or will I get a bill one day?
On the Workers Free plan, going over the limit doesn't produce a bill: if you add Worker code and pass 100,000 requests in a day, the extra requests fail (Error 1027) until midnight UTC. Static file requests are free and unlimited.
Will the motion work on every phone?
The layout, photos and content work everywhere. The cursor effects only run on devices with a mouse or trackpad, the scroll effects run on phones too, and visitors who turned on reduced motion get the static page.
Do I need to know how to code?
To edit text and colors, no: you change index.html and styles.css directly on GitHub and merge. To change the layout, the AI prompt does most of the work, but you should be able to read the result.
Can I use React, Vue or Astro instead of plain HTML?
Yes. Set the build command (for example npm run build) in the Cloudflare settings and point assets.directory to the output folder (./dist). For a single-page app, use "not_found_handling": "single-page-application".
What about a contact form?
A static site can't process a form by itself. You can link to e-mail (the template does), use a form service, or add a small Worker script later, which then counts toward the free request limit.
Takeaway
- Start new sites on Workers, not Pages, even as a beginner. Cloudflare's own Pages docs say so, there is no server to manage, and the same project can grow server code later.
- A static site on Workers costs nothing to serve. The 100,000-requests-per-day limit only applies to Worker code; your money goes only to the domain, if you want one.
-
Two files make the project:
wrangler.jsoncwithassets.directoryand nomain, and a pinned Wrangler inpackage.json. - Connect GitHub once, then the merge is the deploy. Previews per branch are optional and their URLs are public.
- A custom domain needs Cloudflare DNS. Buy it at Cloudflare or move the nameservers, and check your e-mail records before switching.
- Premium comes from the images, then the brief: generate consistent product photos first, then give the agent real facts, a described composition and two or three named effects with limits, and keep the page complete without them.
Everything the demo uses is on GitHub: the code, the images, the clip and both prompts in PROMPT.md. Fork the template, fill in the brackets, and you have your own version.
What did you host your first website on, and what made you leave it? I'm curious how many people are still paying for shared hosting for a static page.
I'm Diogo Soares, a Staff AI Engineer working on AI agents and legacy modernization. If this was useful, follow me here on DEV.to and on Instagram at @diogosoares.dev, where every article becomes a Reel of under a minute. This article also has a video walkthrough on my YouTube channel, Diogo Soares Dev, where you can watch every step on screen, so subscribe there for the next ones. Let's also connect on LinkedIn, or check out diogosoares.dev.








Top comments (2)
This is a fantastic write-up. The distinction between Cloudflare Pages and Workers is becoming such an important topic, and the table you provided makes it incredibly clear. The fact that Workers can handle static assets and scale to include server-side code later without migrating is a huge win for beginners. Definitely saving this guide!
I was very happy to read your comment. Thank you very much!