Skip to main content

​
Overview

Astro Portfolio v3 is configured to deploy seamlessly to Cloudflare Pages using the official @astrojs/cloudflare adapter. The project is set up for SSR (Server-Side Rendering) mode, enabling dynamic functionality while benefiting from Cloudflare’s global edge network.

​
Adapter Configuration

The project uses the Cloudflare adapter configured in astro.config.mjs:9-16: 
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
  site: 'https://lewiskori.com',
  // ... other configuration
});

​
Deployment Process

1

Connect Your Repository

  1. Log in to the Cloudflare Dashboard
  2. Navigate to Pages in the sidebar
  3. Click Create a project
  4. Select Connect to Git
  5. Authorize Cloudflare to access your GitHub repository
  6. Select the repository containing your Astro portfolio
2

Configure Build Settings

Set the following build configuration:
SettingValue
Production branchmain
Build commandpnpm build
Build output directorydist
Node version20 or higher
The project uses pnpm as the package manager. Cloudflare Pages will automatically detect this from the pnpm-lock.yaml file.
3

Set Environment Variables

Configure the required environment variables in the Cloudflare Pages dashboard:
  • BEEHIIV_PUBLICATION_ID - Your Beehiiv publication ID
  • BEEHIIV_API_KEY - Your Beehiiv API key (mark as secret)
  • GTM_ID - Your Google Tag Manager ID
See Environment Variables for detailed setup.
4

Deploy

Click Save and Deploy. Cloudflare Pages will:
  1. Clone your repository
  2. Install dependencies with pnpm install
  3. Run the build command
  4. Deploy the output to the edge network
Your site will be live at https://[project-name].pages.dev within minutes.

​
Wrangler Configuration

The project includes a wrangler.jsonc configuration file for advanced Cloudflare Workers settings: 
{
  "main": "dist/_worker.js/index.js",
  "name": "astro-portfolio-v3",
  "compatibility_date": "2026-01-26",
  "compatibility_flags": [
    "nodejs_compat",
    "global_fetch_strictly_public"
  ],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist"
  },
  "observability": {
    "enabled": true
  }
}
The nodejs_compat compatibility flag enables Node.js runtime APIs required by the Astro server components.

​
Automatic Deployments

Once connected, Cloudflare Pages automatically deploys your site:

​
Production Deployments

  • Trigger: Push to the main branch
  • URL: Your custom domain or [project-name].pages.dev
  • Process: Automatic build and deployment on every commit

​
Preview Deployments

  • Trigger: Pull requests to any branch
  • URL: Unique preview URL for each PR (e.g., [commit-hash].[project-name].pages.dev)
  • Features:
    • Test changes before merging
    • Share previews with stakeholders
    • Automatic updates on new commits
Preview deployments use the same build configuration and environment variables as production, ensuring consistency across environments.

​
Build Output

The Cloudflare adapter produces:
  • dist/_worker.js/index.js - The Cloudflare Workers runtime entry point
  • dist/ - Static assets and rendered pages
  • Server-side rendering capabilities for dynamic routes

​
Performance Features

Deploying to Cloudflare Pages provides:
  • Global CDN: Content served from 300+ data centers worldwide
  • Edge Computing: Server-side rendering at the edge for minimal latency
  • Automatic Caching: Static assets cached automatically
  • DDoS Protection: Built-in security and protection
  • Unlimited Bandwidth: No additional costs for traffic

​
Troubleshooting

If your build fails, check the following:
  • Ensure all environment variables are set correctly
  • Verify the Node.js version is 20 or higher
  • Check that pnpm-lock.yaml is committed to your repository
  • Review build logs in the Cloudflare Pages dashboard

​
Common Issues

Build command not found: Make sure pnpm is properly detected. Cloudflare Pages automatically detects package managers from lock files. Environment variables not working: Ensure variables are set in the Cloudflare Pages dashboard, not just in your local .env file. 404 errors on routes: Verify that output: 'server' is set in astro.config.mjs for SSR routes.

​
Next Steps

Environment Variables

Configure API keys and secrets

Custom Domain

Set up your custom domain

Build docs developers (and LLMs) love

Get started for freeTalk to us