Build a Full-Stack Application using Astro on Cloudflare Workers and Cloudflare Pages

Overview

This comprehensive tutorial demonstrates how to build and deploy a full-stack Astro application using Cloudflare Workers and Cloudflare Pages. Astro is a JavaScript framework perfect for building full-stack applications, and its Cloudflare integration allows you to choose between static deployments, hybrid deployments, or full server-rendered applications.

What You’ll Learn

1. Project Setup and Initialization

• Create a new Astro project with Cloudflare integration
• Explore the project structure and run locally
• Add the Cloudflare adapter for deployment optimization

2. Cloudflare Integration Configuration

• Configure Astro for Cloudflare in astro.config.js
• Understand deployment modes: static vs. server-rendered vs. hybrid
• Use Wrangler platform proxy for local development with Cloudflare services

3. Building Serverless API Endpoints

• Create API routes using Astro’s endpoints feature
• Set up HTTP methods (GET, POST, etc.) for your endpoints
• Deploy and test your serverless functions

4. Cloudflare Services Integration

• Add Cloudflare KV namespace for key-value storage
• Configure Wrangler.toml with service bindings
• Access KV from endpoints through locals.runtime.env
• Perform CRUD operations with KV storage

5. Advanced Features and Possibilities

• Explore other Cloudflare services: D1 databases, Workers AI
• Understand the transformation from Astro endpoints to Workers functions
• Scale your application with edge computing capabilities

Step-by-Step Tutorial

Setting Up Your Astro + Cloudflare Project

# Create a new Astro project with Cloudflare
npm create cloudflare my-astro-app --framework=astro

# Navigate to your project
cd my-astro-app

# Start development server
npm run dev

Adding Cloudflare Integration

# Add the Cloudflare adapter
npm run astro add cloudflare

This command will:

• Install the @astrojs/cloudflare package
• Configure your astro.config.js for Cloudflare deployment
• Enable server-side rendering capabilities

Creating API Endpoints

Create serverless API routes in src/pages/api/:

// src/pages/api/test.ts
export async function GET() {
  return new Response(JSON.stringify({
    name: "Astro",
    url: "astro.build"
  }), {
    headers: {
      "content-type": "application/json"
    }
  });
}

Integrating Cloudflare KV

1. Create a KV namespace:

npx wrangler kv:namespace create "my-test-kv"

2. Configure in wrangler.toml:

[[kv_namespaces]]
binding = "MY_TEST_KV"
id = "your-namespace-id"

3. Use in your endpoint:

export async function GET({ locals }) {
  const value = await locals.runtime.env.MY_TEST_KV.get("test");
  return new Response(JSON.stringify({ value }));
}

Deployment

# Deploy to Cloudflare Pages
npm run deploy

Key Benefits

• 🚀 Edge Performance: Your application runs globally on Cloudflare’s edge network
• 💾 Integrated Storage: Direct access to KV, D1, and other Cloudflare services
• 🔧 Flexible Architecture: Mix static and dynamic content as needed
• ⚡ Fast Development: Local development with Wrangler platform proxy
• 🌍 Global Scale: Automatic scaling and distribution worldwide

Next Steps

This tutorial provides the foundation for building powerful full-stack applications. You can extend your application by:

• Adding a D1 SQL database for complex data operations
• Integrating Workers AI for intelligent features
• Implementing authentication and user management
• Building real-time features with Durable Objects

Additional Resources

• Astro Documentation
• Cloudflare Pages Documentation
• Workers KV Documentation
• Astro Cloudflare Integration Guide

This tutorial showcases the seamless integration between Astro and Cloudflare’s developer platform, enabling you to build modern, performant web applications with minimal configuration.