Skip to main content

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:

Bash
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>
HTML

Install Wrangler in the project, so that its version is recorded in package.json and everyone who clones the project uses the same one:

Bash
npm init -y
npm install --save-dev wrangler
npx wrangler --version

The last command prints Wrangler's version. Then sign in. This opens a browser window where you allow Wrangler to use your Cloudflare account:

Bash
npx wrangler login

In 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:

Bash
npx wrangler pages project create my-static-site --production-branch=main

Then 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:

Bash
npx wrangler pages deploy site --project-name=my-static-site --branch=main

The 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

Bash
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 in or an authentication error in CI: run npx wrangler login on your computer, or set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID in 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 curl as shown, or with a private window.
  • A 404 for your page: the deploy folder is wrong. The folder you pass to wrangler pages deploy must contain index.html directly, 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):

Bash
cat > site/_headers <<'HEADERS'
/*
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY
  Referrer-Policy: strict-origin-when-cross-origin
HEADERS

The 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:

Bash
npx wrangler pages deploy site --project-name=my-static-site --branch=preview

Open the preview address the command prints, and check the headers:

Bash
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:

Bash
npx wrangler pages deploy site --project-name=my-static-site --branch=main

Every 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 a CNAME record from the subdomain to my-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:

Bash
npx wrangler pages project delete my-static-site

Wrangler 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/.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.