Deploy Your First Cloudflare Page with Wrangler CLI

After signing up for a Cloudflare account, the next exciting milestone is launching your first website onto Cloudflare’s global edge network. Cloudflare Pages is a JAMstack and fullstack serverless platform that delivers your site directly from 300+ data centers across the globe with virtually zero latency.

While you can upload static assets manually using the Cloudflare Dashboard, using the official Wrangler CLI provides a fast, repeatable developer workflow that is ready for continuous integration and automation.

This guide walks you step-by-step through setting up Wrangler, authenticating, and deploying your very first Cloudflare Page.

1. Mental Model (ELI5): The Cargo Jet and Global Post Offices#

Think of your website as a physical comic book:

• Traditional Single Server: You only have 1 original printed copy sitting in a single office in New York. If a reader in Tokyo or London wants to read it, their request must travel across the ocean to New York and back -> Slow load times and high server congestion.
• Cloudflare Pages: The Wrangler CLI acts like a high-speed supersonic cargo plane. When you run wrangler pages deploy, it takes your files, instantly replicates them, and deposits copies into 300+ local edge hubs around the world.
• Visitor Experience: A visitor in London fetches the site from the London data center; a visitor in Tokyo fetches it from Tokyo. The page opens within milliseconds at zero infrastructure management overhead.

flowchart TD
    A["💻 Local Computer<br/>(Your Project)"] -->|1. npx wrangler pages deploy| B["⚡ Cloudflare Global Network"]
    B --> C["🌏 Edge Node Tokyo"]
    B --> D["🌏 Edge Node Frankfurt"]
    B --> E["🌏 Edge Node Singapore"]
    B --> F["🌏 Edge Node San Jose"]
    
    User1["👤 Visitor in Japan"] -->|Ultra-fast load| C
    User2["👤 Visitor in Germany"] -->|Ultra-fast load| D
    User3["👤 Visitor in US"] -->|Ultra-fast load| F

2. Problem & Solution#

Common Pitfalls#

1. Outdated Global Packages: Installing the deprecated global package @cloudflare/wrangler (Wrangler v1) leads to command signature errors.
2. Global Dependency Conflicts: Global installs (npm install -g) frequently trigger permission issues or version mismatches across different projects.
3. Manual Deploy Fatigue: Drag-and-drop web UI uploads are cumbersome and prone to human error.

The Solution#

• Install Wrangler locally as a development dependency or execute it on-the-fly with npx.
• Use the modern create-cloudflare (C3) CLI wizard for automatic scaffolding, or attach Wrangler to an existing HTML directory.
• Authenticate seamlessly using single sign-on browser authorization via npx wrangler login.

3. System Requirements#

Before you begin, verify that your environment satisfies these prerequisites:

• Node.js: Version 16.17.0 or higher. Using a version manager like nvm, volta, fnm, or bun is highly recommended to avoid root permission issues.
• Operating System: macOS 13.5+, Windows 11, or Linux (with glibc 2.35+ support).
• Web Browser: An active session on the Cloudflare Dashboard ↗.

[!TIP] If you previously installed the legacy version of Wrangler globally, remove it first:

npm uninstall -g @cloudflare/wrangler

bash

4. Step-by-Step Implementation#

Option 1: Create a New Project with C3 (Recommended)#

The fastest and most robust way to spin up a new Cloudflare application is via the Create Cloudflare CLI (C3) tool. It creates the project folder, configures dependencies, and sets up the modern Wrangler CLI automatically.

Run one of the following commands in your terminal:

# Using npm
npm create cloudflare@latest -- my-pages-app

# Or using pnpm
pnpm create cloudflare@latest my-pages-app

# Or using Bun
bun create cloudflare@latest my-pages-app

The interactive wizard will guide you through:

1. Category: Choose a Framework (Astro, Next.js, Nuxt, SvelteKit, React/Vite, etc.) or a simple Static HTML page.
2. Language: TypeScript or JavaScript.
3. Deployment: Select whether to deploy to Cloudflare immediately.

Option 2: Add Wrangler to an Existing Project & Deploy Static Files#

If you already have existing website code or want to deploy a clean static HTML file from scratch:

Step 1: Create the Project Directory#

Set up your workspace and create an index.html file inside a public directory:

mkdir my-first-page
cd my-first-page

Create public/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Cloudflare Page</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #f38020, #faad3f);
      color: #fff;
    }
    .card {
      background: rgba(255, 255, 255, 0.15);
      backdrop-filter: blur(10px);
      padding: 2.5rem;
      border-radius: 16px;
      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
      text-align: center;
      max-width: 500px;
    }
    h1 { margin-top: 0; }
  </style>
</head>
<body>
  <div class="card">
    <h1>🚀 Hello from Cloudflare Pages!</h1>
    <p>Deployed globally in seconds using the modern Wrangler CLI.</p>
  </div>
</body>
</html>

Step 2: Install Wrangler Locally#

Initialize your package.json (if not present) and install Wrangler as a dev dependency:

npm init -y
npm install --save-dev wrangler

Step 3: Authenticate Wrangler#

Connect your local CLI to your Cloudflare account:

npx wrangler login

This will automatically open your default browser to the Cloudflare authorization page. Click Allow to authorize Wrangler. Once completed, your terminal will confirm:

Successfully logged in.

Verify your active account at any time:

npx wrangler whoami

5. Deploying to Cloudflare Pages#

Deploy your static folder directly to production using the pages deploy subcommand:

npx wrangler pages deploy public --project-name my-first-page

What happens under the hood:

1. Wrangler creates a new Pages project named my-first-page if it does not already exist.
2. It uploads all assets inside public/ directly to Cloudflare’s Edge network.
3. You receive an instant live preview URL (e.g., https://my-first-page.pages.dev).

[!NOTE] To preview your static site locally with full Cloudflare Pages simulation before deploying, run:

npx wrangler pages dev public --port 8788

bash

6. Common Wrangler Commands Quick Reference#

7. References#

• Cloudflare Pages - Get Started Guide ↗
• Wrangler CLI Installation & Configuration ↗
• Wrangler Commands Reference ↗
• Create Cloudflare (C3) Tool ↗
• Migrating from Wrangler v1 to modern Wrangler ↗