How to Deploy React + Vite on Cloudflare Pages

Prepare your Vite project

Start with a React + Vite application that installs and builds successfully on a clean machine. Commit the lockfile so Cloudflare installs the same dependency versions used during local development, and pin important runtime versions when the project depends on a specific Node.js release. A reproducible build removes a large category of deployment-only failures.

Confirm that package.json contains a production build command, normally vite build or a TypeScript check followed by vite build. Vite writes the deployable application to dist by default. Avoid absolute filesystem references, development-only API addresses, and asset paths that only work from the local server.

Before connecting the repository, delete or ignore any old build output and run npm ci followed by npm run build. Then inspect dist locally. This catches TypeScript errors, case-sensitive filename mistakes, missing public assets, and accidental dependencies on the development server.

Configure Cloudflare Pages

Create a Pages project in the Cloudflare dashboard and connect the Git provider that contains the application. Select the production branch deliberately rather than assuming the repository default is correct. The Vite framework preset normally supplies npm run build as the build command and dist as the output directory, but verify both fields before the first deployment.

Cloudflare creates an isolated preview URL for non-production branches and pull requests. Use those previews as release candidates: test the compiled application there before merging to the production branch. Preview deployments are also useful for checking redirects, response headers, social previews, and environment-specific integrations without exposing unfinished work on the primary domain.

Keep deployment behavior in the repository wherever possible. Files such as robots.txt, a custom 404.html, redirects, headers, and generated sitemap output can travel through review and remain consistent across environments. Dashboard-only rules are harder to discover when another engineer needs to reproduce the project.

Manage environment variables safely

Add public build-time configuration in the Pages project settings and define separate values for preview and production environments when necessary. Vite only exposes variables prefixed with VITE_ to browser code. That prefix is a visibility boundary, not a security feature: every exposed value becomes readable in the generated JavaScript bundle.

Never place private API keys, database credentials, signing secrets, or unrestricted service tokens in a VITE_ variable. Sensitive work belongs behind an authenticated server endpoint, a Cloudflare Function, or another trusted backend. If a browser must call a third-party service directly, use a deliberately public key with domain restrictions and minimal permissions.

Document required variable names in an example environment file without committing real values. Fail the build with a clear message when essential configuration is missing, rather than allowing a deployment that only reveals the problem when a visitor opens the affected feature.

Handle React Router routes

Client-side navigation can hide a routing problem during development. Clicking a React Router link works because the application is already loaded, while refreshing that same nested URL asks Cloudflare for a matching asset. Test both behaviors. Every public route should either match generated HTML or be covered by an intentional application fallback.

For marketing and editorial pages, generating an HTML file for every important route is safer than relying entirely on a generic SPA response. Route-specific output lets crawlers, social networks, and users without completed JavaScript receive the correct title, canonical URL, description, headings, and article content immediately.

Add a top-level 404.html when unknown URLs must return an actual 404 response. Cloudflare Pages otherwise treats a project without that file as a single-page application and can serve the root document for unmatched paths. A real 404 prevents nonexistent article URLs from becoming indexable soft-404 pages.

Make important pages crawlable

A React application can update document metadata after navigation, but production SEO should not depend on that update for the first request. Inspect View Source—not only the browser Elements panel—and confirm that the original response already contains the page title, meta description, canonical link, robots directive, primary H1, and meaningful body copy.

Article pages should also provide Open Graph and Twitter metadata for reliable sharing, plus Article and BreadcrumbList structured data when those schemas accurately describe the page. Keep the canonical URL, internal links, breadcrumb items, and sitemap location in the same trailing-slash convention so crawlers do not waste time resolving avoidable redirects.

Generate sitemap entries from the same local content source used to render routes. This avoids publishing an article without adding it to discovery files, preserves reliable last-modified dates, and prevents stale URLs from remaining in the sitemap after content is removed.

Connect the production domain

After the preview is stable, add the production domain from the Pages project. Cloudflare will guide the required DNS configuration and certificate activation. Choose one canonical hostname—such as the apex domain—and redirect alternate hostnames consistently instead of allowing both versions to serve identical content.

Update application metadata, sitemap locations, robots.txt, API allowlists, analytics settings, and any OAuth callback URLs to use the final HTTPS origin. Search engines should never discover preview deployment domains as canonical alternatives to the production site.

Verify the production deployment

Open the deployed origin in a private browser session, then visit and refresh several nested routes directly. Confirm that the network response is successful, assets load from HTTPS URLs, and an unknown route returns the custom 404 rather than the homepage. Test both trailing-slash variants to ensure Cloudflare redirects to a single canonical form.

Inspect the HTML source for metadata and structured data, validate sitemap.xml as XML, and verify that robots.txt allows the intended sections and names the production sitemap. Check that every sitemap URL returns successfully and that no preview, laboratory, or nonexistent route is accidentally indexable.

Finally, test mobile navigation, keyboard focus, image dimensions, and the production Core Web Vitals. Measure the deployed build rather than the Vite development server because minification, caching, fonts, third-party scripts, and CDN behavior all affect the experience visitors actually receive.

Troubleshoot common deployment failures

If the build fails, compare the Cloudflare build log with a clean local npm ci and npm run build. Check the selected root directory, Node version, filename capitalization, missing environment variables, and whether required generated files are excluded from the repository or build command.

If the homepage works but nested routes fail, inspect the files produced inside dist and decide whether each route should have static HTML or use a deliberate fallback. If a deployment succeeds but shows old content, confirm that the production branch actually contains the change before investigating cache behavior.

Treat deployment as part of the application architecture rather than the last command in a project. A small, explicit build pipeline makes React + Vite on Cloudflare Pages fast to release, straightforward to audit, and much easier to recover when something changes.