Prerequisites

Everything you need before starting a Cloudflare Pages project — whether migrating from WordPress or building fresh. This page walks you through accounts, tools, and environment setup so you can hit the ground running.

---

Accounts

Cloudflare Account

RequiredFree

URL: dash.cloudflare.com

Your hub for hosting, CDN, DNS, Functions, and deployment.

After setup you get access to:

• Pages (hosting)
• Workers / Functions (serverless)
• DNS management
• SSL certificates
• Analytics
• Security features

GitHub Account

RecommendedFree

URL: github.com

Version control, auto-deploy integration, and browser-based editing.

Why GitHub?

• Cloudflare Pages auto-deploys from GitHub on every push
• GitHub web editor enables browser-based content editing (no local tools)
• Full version history and rollback capability
• Collaboration features (PRs, reviews)

SendGrid Account

If Forms NeededFree Tier

URL: app.sendgrid.com

Email delivery for form submissions. Free tier includes 100 emails/day.

Domain Registrar Access

For Custom Domains

Access to your domain registrar to point nameservers to Cloudflare or add CNAME records for subdomains.

Common registrars: GoDaddy, Namecheap, Google Domains (Squarespace), Hover, Cloudflare Registrar.

---

Setting Up Your Cloudflare Account

1. Go to dash.cloudflare.com/sign-up
2. Create account with email + password
3. Verify your email address
4. Add your domain (or do this later)
5. Note your Account ID (visible in dashboard URL or Overview page)

Setting Up SendGrid (If Forms Needed)

1. Go to signup.sendgrid.com
2. Create your account
3. Complete Single Sender Verification:
   • Navigate to Settings > Sender Authentication
   • Verify a “from” email address (e.g., noreply@yourdomain.com)
4. Create an API Key:
   • Settings > API Keys > Create API Key
   • Permission: “Mail Send” (minimum)
   • Copy the key immediately (you will not see it again)
   • Format: SG.xxxxxxxxxxxxxxxxxxxxxxxx

SendGrid Alternatives

Service	Free Tier	Notes
SendGrid	100 emails/day	Recommended, reliable
Resend	3,000 emails/month	Developer-friendly API
Mailgun	1,000 emails/month (trial)	Good deliverability
Postmark	100 emails/month	Excellent for transactional

---

Tools

Node.js Required

Version: 18+ recommended (LTS) Purpose: Runs Wrangler CLI, build scripts, and Astro

macOS (Homebrew)

brew install node

macOS / Linux (nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Tip

nvm is the recommended approach — it lets you switch between Node.js versions easily.

Windows

Download the installer from nodejs.org.

Verify your installation:

node --version   # Should show v18.x.x or higher
npm --version    # Should show 9.x.x or higher

---

Wrangler CLI Required

Purpose: Cloudflare’s command-line tool for Pages deployment and local development.

1. Install globally:

   npm install -g wrangler

2. Authenticate with Cloudflare:

   npx wrangler login
   # Opens browser to authenticate with Cloudflare

3. Verify:

   npx wrangler whoami
   # Should show your Cloudflare account name and ID

---

Git Required

Purpose: Version control, deployment, collaboration

macOS

xcode-select --install
# Or via Homebrew:
brew install git

Windows

Download from git-scm.com.

Linux

sudo apt install git

Verify:

git --version   # Should show git version 2.x.x

Configure your identity:

git config --global user.email "your@email.com"
git config --global user.name "Your Name"

---

Code Editor Required

Recommended: Visual Studio Code (free)

Key extensions to install:

• Astro — for Astro projects
• HTML CSS Support — for HTML editing
• Prettier — code formatting
• Live Server — local preview

Alternatives: Sublime Text, WebStorm, Cursor, Zed

---

Playwright WordPress Migration Only

Purpose: Headless browser for capturing WordPress pages with full fidelity.

npm install playwright
npx playwright install chromium

Note

Only needed for WordPress migrations that use the browser-capture approach (Unbounce-style migrations, complex Divi sites).

---

Lighthouse CLI Optional

Purpose: Run performance audits from the command line.

npm install -g lighthouse

Or use per-project without a global install:

npx lighthouse https://your-site.com/ --output=json --chrome-flags="--headless"

---

WordPress Migration: Additional Requirements

Caution

This section only applies if you are migrating an existing WordPress site. Skip ahead to Fresh Builds if you are starting from scratch.

Local WordPress Environment Required

You need a locally running copy of the WordPress site to crawl.

Tool	Platform	Free	Notes
Local by Flywheel	Mac, Windows, Linux	Yes	Recommended — easiest
DevKinsta	Mac, Windows	Yes	Good if hosting on Kinsta
MAMP	Mac, Windows	Yes (limited)	Classic approach
Docker + WordPress	Any	Yes	For advanced users
wp-env	Any (Node.js)	Yes	Official WordPress tool

Setup with Local by Flywheel

1. Download from localwp.com
2. Create new site or import existing
3. Pull database and files from production
4. Site will be available at https://sitename.local

WordPress File Access Required

You need direct file system access to the WordPress installation:

wp-content/
  themes/          # Active theme files
  plugins/         # Active plugin files
  uploads/         # Media library
  cache/           # Cache files (if using caching plugin)

Where to find this:

• Local by Flywheel: ~/Local Sites/<site>/app/public/
• MAMP: /Applications/MAMP/htdocs/
• Server: /var/www/html/ or similar
• Hosting panel: File Manager > public_html/

WordPress Security Plugin Considerations

Danger

Security plugins like CleanTalk, Wordfence, and iThemes Security may block the crawler. You will need to temporarily disable them during the crawl.

# Rename plugin folder to disable
mv wp-content/plugins/cleantalk-spam-protect wp-content/plugins/cleantalk-spam-protect.disabled

# After crawl, restore
mv wp-content/plugins/cleantalk-spam-protect.disabled wp-content/plugins/cleantalk-spam-protect

---

Fresh Builds: Additional Requirements

Astro Recommended

Purpose: Cloudflare’s first-party web framework, perfect for new sites.

1. Create a new project:

   npm create astro@latest my-site
   cd my-site
   npm install

2. Choose a template during setup:

   • Minimal — Empty project
   • Blog — Blog with content collections
   • Starlight — Documentation site
   • Portfolio — Portfolio/showcase

3. Add the Cloudflare adapter:

   npx astro add cloudflare

4. Verify everything works:

   npm run dev    # Local dev server
   npm run build  # Build for production

Astro CMS Integrations Optional

For non-technical content editing, you can add a CMS:

CMS	Type	Free Tier	Best For
Decap CMS	Git-based	Free (open source)	Simple sites, blog posts
Tina CMS	Git-based	Free (3 users)	Visual editing experience
Contentful	API-based	Free (5 users)	Larger teams, structured content
Sanity	API-based	Free (3 users)	Flexible content modeling
Storyblok	API-based	Free (1 user)	Visual editor, component-based

Tip

For medical practice sites, Decap CMS is the recommended choice — it is free, simple, and Git-based with no external dependencies.

---

Environment Variables

Local Development (.env file)

Create a .env file in the project root (and add it to .gitignore):

# SendGrid API Key (for form email delivery)
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxx

# Cloudflare API Token (for configuration scripts)
CLOUDFLARE_API_TOKEN=xxxxxxxxxxxxxxxxxxxx

# Zone ID (for Cloudflare API operations)
CLOUDFLARE_ZONE_ID=xxxxxxxxxxxxxxxxxxxx

Danger

Never commit your .env file to version control. Make sure .gitignore includes .env before your first commit.

Production (Cloudflare Dashboard)

Location: Dashboard > Pages > [Project] > Settings > Environment Variables

1. Go to Settings > Environment Variables
2. Click “Add variable”
3. Enter name and value
4. Select environment (Production / Preview / Both)
5. Save
6. Redeploy for changes to take effect

Required for forms:

• SENDGRID_API_KEY — Your SendGrid API key

---

Project Initialization

Choose the approach that matches your project type:

WordPress Migration

# Create project directory
mkdir cloudflare-builder-<sitename>
cd cloudflare-builder-<sitename>

# Initialize npm
npm init -y

# Install dependencies
npm install playwright wrangler --save-dev

# Install Playwright browsers
npx playwright install chromium

# Create project structure
mkdir -p public scripts tests docs

# Create .gitignore
cat > .gitignore << 'EOF'
node_modules/
.env
.wrangler/
*.DS_Store
test-results/
lighthouse-*.json
EOF

# Initialize git
git init
git add .
git commit -m "Initial project setup"

Fresh Build (Astro)

# Create Astro project
npm create astro@latest cloudflare-<sitename>
cd cloudflare-<sitename>

# Add Cloudflare adapter
npx astro add cloudflare

# Create .env
touch .env

# Verify
npm run dev

Fresh Build (Plain HTML)

# Create project directory
mkdir cloudflare-<sitename>
cd cloudflare-<sitename>

# Initialize npm (for Wrangler)
npm init -y
npm install wrangler --save-dev

# Create project structure
mkdir -p public functions/api

# Create basic index.html
cat > public/index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Site Name</title>
</head>
<body>
  <h1>Hello World</h1>
</body>
</html>
EOF

# Create wrangler.toml
cat > wrangler.toml << 'EOF'
name = "cloudflare-sitename"
compatibility_date = "2024-01-01"
pages_build_output_dir = "public"
EOF

# Create .gitignore
cat > .gitignore << 'EOF'
node_modules/
.env
.wrangler/
*.DS_Store
EOF

# Initialize git
git init
git add .
git commit -m "Initial project setup"

# Test locally
npx wrangler pages dev public

---

Cloudflare API Token Setup

Note

Only needed if you plan to use API-based Cloudflare configuration (Auto Minify, Brotli, etc.).

1. Go to dash.cloudflare.com/profile/api-tokens

2. Click Create Token

3. Use the Custom token template

4. Set permissions:

   Section	Permission	Access
   Zone	Zone Settings	Edit
   Zone	Firewall Services	Edit
   Zone	Analytics	Read
   Account	Account Analytics	Read

5. Zone Resources > Include > Specific zone > your domain

6. Create the token

7. Copy immediately (shown only once)

8. Add to your .env file: CLOUDFLARE_API_TOKEN=your_token_here

---

Verification Checklist

Before starting any migration or build, confirm everything is in place.

Accounts

• Cloudflare account created and verified
• SendGrid account created (if forms needed)
• GitHub account created (recommended)
• Domain registrar access confirmed

Tools

• Node.js 18+ installed: node --version
• npm installed: npm --version
• Git installed: git --version
• Wrangler installed: npx wrangler --version
• Wrangler authenticated: npx wrangler whoami
• Code editor installed

WordPress Migration (if applicable)

• Local WordPress environment running
• WordPress site accessible at local URL
• File system access to wp-content
• Security plugins identified (may need temporary disable)
• Playwright installed: npx playwright --version

Fresh Build (if applicable)

• Astro installed (if using): npx astro --version
• Chose project template
• Local dev server runs: npm run dev

Environment

• .env file created with API keys
• .gitignore includes .env and node_modules
• Git repository initialized

---

Troubleshooting Common Issues

”wrangler: command not found"

npm install -g wrangler
# Or use npx:
npx wrangler login

"Error: EACCES permission denied"

# Fix npm global permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

"Playwright browsers not installed"

npx playwright install chromium

"SSL certificate error on local WordPress”

Trust local certificates (Local by Flywheel generates self-signed certs), or use the --ignore-certificate-errors flag in Playwright.

”Port already in use”

# Find process on port
lsof -i :8788

# Kill it
kill -9 <PID>

Tip

If you run into an issue not listed here, check the Cloudflare Pages documentation or open an issue on your project repository.