Host a Static Web App on Cloudflare Pages: A 2026 Guide

Cloudflare Pages hosting lets frontend teams ship code that is fast, secure, and free of server administration. By using Cloudflare Pages , developers get a high-performance edge-native platform to deploy static web applications, single-page apps (SPAs), and server-side rendered (SSR) frameworks. By connecting directly to your Git repository, Cloudflare automates build pipelines, generates preview deployments, and hosts assets globally. This guide explains how to connect Git, configure build settings, set up custom domains, and configure redirects.

TL;DR

• Deploy edge-native frontend apps; Cloudflare Pages serves assets globally from Cloudflare’s network, ensuring sub-second load times.
• Automate Git integration; link your repository to trigger automatic builds and generate preview URLs for every commit.
• Configure framework build settings; set output directories and commands for React, Vue, Next.js, Hugo, or Astro.
• Apply redirect and header rules using plain text _redirects and _headers files in your public folder.
• Map custom domains with free, automatically renewed SSL certificates managed by Cloudflare.

What is Cloudflare Pages?

Cloudflare Pages is a serverless hosting platform for frontend developers, similar to Netlify or Vercel, built directly on Cloudflare’s global infrastructure.

Rather than hosting files on a single cloud server, Cloudflare Pages distributes your HTML, CSS, JavaScript, and images across edge locations worldwide. When a user requests your site, assets are served from the closest location, cutting network latency. For projects requiring server-side logic, Pages integrates with Cloudflare Workers to run backend functions. To compare Pages with other edge compute services, read our guide on Cloudflare Pages vs Workers .

Prerequisites

Before you begin, make sure you have the following in place:

• A Git repository on GitHub or GitLab containing your project (or the built files ready for a direct upload).
• A framework that outputs static assets — React (Vite), Vue, Astro, SvelteKit, Hugo, or plain HTML. Server-rendered frameworks work too, through Pages Functions.
• A working local build. Run your build command (for example npm run build) and confirm the output folder is generated without errors before you connect anything.
• A free Cloudflare account. No credit card is required for the free tier.
• Node.js installed locally (recommended) so you can reproduce builds and use the Wrangler command-line tool.

A quick sanity check saves hours of debugging later: if your site does not build cleanly on your own machine, it will not build on Cloudflare’s runners either. Resolve local errors first.

Step 1: Connecting Your Git Repository

To get started, log in to your Cloudflare Dashboard, navigate to Compute > Pages, and click Create a project.

Select Connect to Git to link your GitHub or GitLab account. Choose the repository containing your static web application. This integration is valuable because it establishes a continuous integration (CI) pipeline: every time you push code to your production branch, Cloudflare builds and deploys the updates automatically. For other commits, Cloudflare generates unique “preview URLs” so you can test changes before merging.

Step 2: Configuring Build Settings

Cloudflare Pages supports popular static site generators and frontend frameworks. During the setup wizard, configure the following settings based on your stack:

• Build command: The build script defined in your package.json (such as npm run build or hugo --minify).
• Build output directory: The folder containing the compiled static files (such as dist, build, or public).
• Environment variables: If your build script requires API keys or config variables, define them here.

Cloudflare auto-detects many frameworks, but confirming the preset avoids a failed first build. The common combinations are:

Pin your Node version. A frequent cause of “works locally, fails on Cloudflare” is a mismatch between the Node version the build runner defaults to and the one your project expects. Declare it explicitly, either as an environment variable in the dashboard:

1NODE_VERSION = 20

Or by committing a .node-version file to the repository root:

120

Step 3: Setting Up Redirects and Headers

For single-page apps (like React Router) or legacy URL migrations, you must configure routing and redirect rules. Pages handles this through simple text files placed in your output directory.

Redirects (_redirects)

Create a file named _redirects in your public folder. For a React SPA to handle client-side routing cleanly, add the fallback rule:

1/*  /index.html  200

This forces all requests to resolve to index.html, allowing the JavaScript router to manage the path.

Order matters. Cloudflare evaluates rules top to bottom and stops at the first match, so specific redirects must sit above the catch-all fallback:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

The :splat placeholder carries the matched portion of the path through to the destination. The free plan allows up to 2,000 static redirect rules per project; beyond that, move the logic into a Pages Function or Bulk Redirects.

Custom Headers (_headers)

Create a file named _headers to apply security rules, Referrer-Policies, or custom cache controls:

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

The same file is the right place to tune caching. Fingerprinted, immutable assets can be cached for a year, while HTML stays fresh so users always receive the newest build:

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

To see how these rules compare to traditional backend routing, read building a serverless API with Cloudflare Workers .

Step 4: Mapping Custom Domains

Once deployed, Cloudflare provides a default sub-domain (e.g. your-project.pages.dev).

To map your custom domain, navigate to the Custom Domains tab in your Pages project, and enter your domain (e.g. yourcompany.com). If your DNS is managed by Cloudflare, the platform configures the CNAME records and provisions a free, auto-renewing SSL certificate instantly. If you need help managing domain mapping, DNS, or server security, check the website security audit page.

Step 5: Deploying with the Wrangler CLI (Direct Upload)

Git integration suits most teams, but you can also deploy straight from your machine or an existing pipeline using Wrangler, Cloudflare’s command-line tool. This is useful when your build already runs in GitHub Actions or GitLab CI and you only want to upload the finished output.

Install Wrangler and authenticate:

1npm install -g wrangler
2wrangler login

Build locally, then push the output directory to a named project:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

The first run creates the project if it does not already exist. In CI, swap the interactive wrangler login for a scoped API token supplied through an environment variable, so no browser step is needed:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Direct upload skips Cloudflare’s own build step, which sidesteps build-environment issues and hands you full control of the toolchain.

Common Pitfalls and Troubleshooting

A handful of issues account for most first-time deployment failures:

• 404 errors when refreshing an SPA route. A client-side route such as /dashboard returns “Nothing is here yet” because no matching file exists on disk. The fix is the /* /index.html 200 fallback in _redirects, and confirming that file lands in the build output rather than your source folder.
• _redirects or _headers appear to be ignored. These files must live in the published output directory, not merely the repository. With Vite, Astro, or SvelteKit, place them in the public/ (or static/) folder so the build copies them across untouched.
• Build succeeds locally but fails on Cloudflare. This is nearly always a Node version mismatch or a missing build-time variable. Pin the Node version and re-declare any variables the build reads — they are separate from runtime bindings.
• “Too many files” or an oversized deployment. A single deployment is capped at 20,000 files, with a 25 MiB limit per file. Large media belongs in R2 or an image service, not the static bundle.
• Stale assets after a release. Hashed files such as app.4f2c.js can be cached aggressively, but index.html should not be. Keep HTML on a short cache and let fingerprinted assets stay immutable, as shown earlier.

Testing and Production Considerations

Cloudflare builds a preview deployment for every non-production branch and pull request, each on its own URL (for example abc123.my-web-app.pages.dev). Because previews run on the same edge network as your live site, they are a reliable place to review changes before merging.

For real releases, a few controls make the difference between a host and a dependable workflow:

• Rollbacks. Every deployment is retained, so a broken release can be reverted by promoting a previous build back to production from the dashboard in seconds, with no rebuild.
• Environment separation. Set different variables for production and preview so preview builds point at staging APIs rather than live data.
• Analytics and Core Web Vitals. Enable Cloudflare Web Analytics — privacy-first and cookie-free — to track real-user LCP, CLS, and traffic without loading a third-party script.
• Access control for previews. Preview URLs are public by default. If a branch exposes unreleased work, place it behind Cloudflare Access so only your team can open it.

Putting these in place early keeps your deployments predictable as the project grows and more people push to it.

Key Takeaways

• Cloudflare Pages hosts static web applications on Cloudflare’s global edge network, optimising load speeds.
• Automate deployments by linking GitHub or GitLab to compile code on every commit.
• Define build commands and output directories matching your framework (Astro, Next.js, Hugo, React).
• Configure redirects and security headers using simple _redirects and _headers text files in your output directory.
• Map custom domains with free, auto-renewing SSL certificates managed directly by Cloudflare.

Optimise Your Web Infrastructure

Deploying fast, secure frontends requires choosing the right hosting architecture and caching rules. Mecanik specialises in website development services and provides expert technical SEO audit services . We build custom React, Next.js, and Astro platforms optimised for Core Web Vitals and deployed on Cloudflare. Contact us today to discuss your next build.

Frequently Asked Questions (FAQ)

What is Cloudflare Pages hosting? It is a serverless frontend hosting platform that builds and serves static web applications, React SPAs, and static site generator outputs (like Astro or Hugo) globally on Cloudflare’s CDN.

Does Cloudflare Pages support server-side rendering (SSR)? Yes. Pages supports SSR frameworks (like Next.js, Astro, SvelteKit) by automatically converting server logic into serverless Cloudflare Workers during the build process.

How do I configure redirects on Cloudflare Pages? You create a plain text file named _redirects in the build output directory and write redirection rules, defining the source path, destination path, and HTTP status code.

Is Cloudflare Pages free? Yes. Cloudflare Pages offers a generous free tier that includes unlimited deployments, unlimited bandwidth, and custom domains, making it highly cost-effective for static hosting.

How do I set up a custom domain on Pages? Navigate to the Custom Domains tab in your Pages project dashboard, enter your domain name, and Cloudflare will configure the DNS records and issue a free SSL certificate.