Cloud and deployment · Beginner · 12 min
How to Host a Static Site on Cloudflare Pages
By Padding · Updated 15 Nov 2026
Cloudflare Pages
You will publish a folder of static files to Cloudflare Pages from the command line with Wrangler, add a security header, deploy a preview and a production version, connect a domain, and delete the project when you are done.
On this page
Cloudflare Pages hosts static sites on Cloudflare's network. You hand it a folder of HTML, CSS, JavaScript and images, and it serves them from many locations over HTTPS. There is no server to patch and no certificate to renew, and the free plan is enough for a personal or small site.
One thing to know first. At the time of writing, Cloudflare's own Pages documentation says that new projects should start with Cloudflare Workers, which supports most Pages use cases and has a broader feature set. Pages is not deprecated by that page and keeps working, and it is a good fit for a plain static site that you deploy by upload or from Git. If you are choosing for a long-lived project, read Cloudflare's comparison first at developers.cloudflare.com/pages/. The steps below use Pages.
Step 1 · Make a site and install Wrangler
Create a project folder with a one-page site in a site folder:
mkdir my-static-site
cd my-static-site
mkdir site
cat > site/index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Hello from Cloudflare Pages</title>
</head>
<body>
<h1>Hello from Cloudflare Pages</h1>
</body>
</html>
HTMLInstall Wrangler in the project, so that its version is recorded in package.json and everyone who clones the project uses the same one:
npm init -y
npm install --save-dev wrangler
npx wrangler --versionThe last command prints Wrangler's version. Then sign in. This opens a browser window where you allow Wrangler to use your Cloudflare account:
npx wrangler loginIn a script or CI job, there is no browser. Create an API token in your Cloudflare profile with the permission to edit Cloudflare Pages, and set it as the environment variable CLOUDFLARE_API_TOKEN (and your account ID as CLOUDFLARE_ACCOUNT_ID) from your CI system's secret store. Never write the token into a file in the repository.
Step 2 · Create the project and deploy
Create a Pages project. The name becomes part of your address (<name>.pages.dev), and --production-branch is the branch name that Cloudflare treats as production:
npx wrangler pages project create my-static-site --production-branch=mainThen upload the folder. --branch=main marks this as a production deployment, because it matches the production branch. Without --branch, Wrangler uses your current Git branch if the folder is a Git repository:
npx wrangler pages deploy site --project-name=my-static-site --branch=mainThe upload takes a few seconds, and the command prints the address of the deployment. Wrangler reports a unique address for this deployment, and the project's main address, https://my-static-site.pages.dev. If the name was already taken, Cloudflare may add characters to your project's subdomain, so use the address that the command prints rather than the one you expected.
Check it worked
curl -s https://my-static-site.pages.dev/ | grep '<title>'The line <title>Hello from Cloudflare Pages</title> appears. The site is on HTTPS already, with a certificate Cloudflare manages.
Troubleshooting
You need to log inor an authentication error in CI: runnpx wrangler loginon your computer, or setCLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDin CI. A token needs the permission to edit Pages.- The site shows an old version after a deploy: your browser may be caching the page. Test with
curlas shown, or with a private window. - A 404 for your page: the deploy folder is wrong. The folder you pass to
wrangler pages deploymust containindex.htmldirectly, not in a subfolder. - The upload fails with a file-size or file-count error: Wrangler uploads up to 20,000 files, each up to 25 MiB. Zip files are not supported, so deploy the folder itself.
Step 3 · Add a header, and deploy a preview
Cloudflare Pages reads two optional text files from the root of the folder you deploy. _headers sets HTTP response headers, and _redirects sets redirects. Add a header file that asks browsers not to guess file types, and keeps your site out of frames on other sites (see /tutorials/add-security-headers-in-nginx for what these headers mean):
cat > site/_headers <<'HEADERS'
/*
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
HEADERSThe first line is the URL pattern, and the indented lines are headers. _headers applies only to static files that Pages serves, and not to responses from Pages Functions. A file can hold up to 100 rules.
Deploy this change to a preview first. A deployment to any branch other than the production branch is a preview, with its own address, and it does not change the production site:
npx wrangler pages deploy site --project-name=my-static-site --branch=previewOpen the preview address the command prints, and check the headers:
curl -sI https://preview.my-static-site.pages.dev/ | grep -i -E 'x-content-type|x-frame'The preview address uses the branch name as a subdomain, as shown in the command output. Use the address the command prints if yours differs. The branch address can take a few seconds to start answering after the deploy finishes, so if curl returns an error or an empty result, wait a moment and run it again. When you are satisfied, deploy to production:
npx wrangler pages deploy site --project-name=my-static-site --branch=mainEvery deployment is kept. In the dashboard, under the Workers and Pages section (the name may differ) and then your project, the Deployments list lets you view them and roll back to an earlier one.
Step 4 · Deploy from Git instead
Uploading from your computer is called Direct Upload. The other way is to connect a GitHub or GitLab repository in the dashboard: look for something like Create application, then Pages, then connect to Git. You give it a build command and the output folder, and every push builds and deploys, with preview addresses for other branches. Choose this if you want deploys to follow your Git history.
The two modes do not mix. Cloudflare's documentation says that a project created for Direct Upload cannot be switched to Git integration later, so decide before you create the project. If you pick Git, you can still start with the same site folder: set the output directory to site and leave the build command empty.
Step 5 · Add your own domain
Add the domain in the dashboard first: open your Pages project, then Custom domains, and choose to set up a domain. This order matters. Cloudflare's documentation warns that if you create the DNS record without adding the domain to the project first, the domain fails to resolve and visitors can see a 522 error.
- For a subdomain such as
www.example.com, the parent domain does not have to be on Cloudflare. At your DNS provider, create aCNAMErecord from the subdomain tomy-static-site.pages.dev. - For a bare domain such as
example.com, the domain must be a zone on Cloudflare, so you change its nameservers to Cloudflare's. Cloudflare then creates the record for you.
The record types are explained in /tutorials/dns-records-explained-a-cname-mx-txt. Changing nameservers moves all of the domain's DNS, including email records, to Cloudflare, so copy every existing record across before you switch.
Step 6 · Costs, limits and cleaning up
The free plan covers a small site, and it has limits: Cloudflare's Pages page mentions 500 deploys per month on the Free plan. Limits and prices change, so read developers.cloudflare.com/pages/platform/limits/ and your plan's page before depending on them. Paid features, such as Pages Functions beyond their free allowance, are billed through Workers.
To remove the project and every deployment, delete it. This is permanent, and the .pages.dev address stops working:
npx wrangler pages project delete my-static-siteWrangler asks you to confirm; --yes skips the question. Also delete any custom domain's DNS record at your provider, so that it does not point at a project that no longer exists, and delete the API token in your Cloudflare profile if you created one for this tutorial.
Next steps
- Understand the DNS records you add for a domain:
/tutorials/dns-records-explained-a-cname-mx-txt. - Learn what security headers do:
/tutorials/add-security-headers-in-nginx. - Serve your own site from your own server instead:
/tutorials/install-nginx-on-ubuntu-26-04. - Cloudflare's references: developers.cloudflare.com/pages/get-started/direct-upload/ and developers.cloudflare.com/workers/wrangler/commands/pages/.
Related tutorials
- DNS Records Explained: A, AAAA, CNAME, MX and TXT, with dig ExamplesYou will learn what the common DNS record types do and read each one with dig, using a small practice DNS server you start yourself.
- How to Add Security Headers to Your Site in NginxYou will add the HTTP security headers every site should send, keep them in one reusable file, avoid the add_header inheritance trap, and roll out Content-Security-Policy and HSTS in the safe order.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials