Using Wrangler to develop Cloudflare Pages locally

Testing Cloudflare Pages Static Sites Locally

The Problem

When developing static sites or applications destined for deployment on Cloudflare Pages, it's crucial to have a local testing environment that accurately reflects the production setup. While development tools like Vite.js or VSCode's Live Server are excellent for the initial build process, they don't replicate the Cloudflare Pages runtime environment. This discrepancy can lead to the common "it works on my machine" issue, where bugs or unexpected behavior only appear after deployment. The challenge is to create a local testing environment that is as close as possible to the Cloudflare Pages production environment to catch these issues early.

How to Solve the Problem (Step-by-Step)

Solving this problem is straightforward using Cloudflare's official command-line tool, wrangler. Even if you haven't used Cloudflare tools before or have an existing static site project, you can integrate wrangler to preview your built site locally.

Here are the steps:

1. Install the wrangler CLI:
   The first step is to add wrangler to your project's development dependencies. wrangler is Cloudflare's CLI tool used for interacting with Cloudflare Workers and Pages, including running a local development server that simulates the Cloudflare Pages environment.
   Open your terminal in your project's root directory and run one of the following commands:

   pnpm add \-D wrangler  
   \# or  
   npm i \-D wrangler
   

2. Configure a Script in package.json:
   Next, you need to add a script to your project's package.json file to easily run the local preview command using your package manager.
   Open your package.json and add the following line within the "scripts" section:

   "scripts": {  
     "preview": "wrangler pages dev .dist"  
   }
   

   Important: Replace .dist with the actual path to the directory where your project's static assets are built and stored. This is the folder that wrangler will serve locally.

3. Run the Local Preview:
   Now you can start the local Cloudflare Pages server using the script you added.
   In your terminal, run:

   pnpm preview  
   \# or  
   npm run preview
   

   You should see output similar to this:

   \[wrangler:inf\] Ready on <http://127.0.0.1:8788>  
   Attempting to login via OAuth...  
   Opening a link in your default browser: <https://dash.cloudflare.com/oauth2/auth?response\_type=code\&client\_id=>...
   

   wrangler will start serving your built static site. While it might attempt to open a browser for Cloudflare authentication, this isn't necessary for serving a static site locally, so you can safely ignore or close that browser tab. Your static site will be accessible locally at http://127.0.0.1:8788.

Alternative Usage: Running with HTTPS

In some cases, you might need to test your site using HTTPS locally to ensure everything works correctly before deployment, especially if your site relies on features that require a secure context. wrangler makes this easy and can even generate a self-signed certificate for you.

To run your local preview server with HTTPS, modify the preview script in your package.json to include the --local-protocol=https flag:

"scripts": {  
  "preview": "wrangler pages dev \--local-protocol=https .dist"  
}

Now, when you run pnpm preview or npm run preview, your site will be served over HTTPS. You might encounter a browser warning about the self-signed certificate, which is expected and can be safely bypassed for local testing.

By incorporating wrangler pages dev into your local development workflow, you gain a testing environment that closely mirrors Cloudflare Pages, helping you build and deploy with greater confidence.