Astro

import { PagesBuildPreset, Render, PackageManagers, YouTube, } from "~/components";

Astro is an all-in-one web framework for building fast, content-focused websites. By default, Astro builds websites that have zero JavaScript runtime code.

Refer to the Astro Docs to learn more about Astro or for assistance with an Astro project.

In this guide, you will create a new Astro application and deploy it using Cloudflare Pages.

Video Tutorial

Set up a new project

To use create-cloudflare to create a new Astro project, run the following command:

Astro will ask:

1. Which project type you would like to set up. Your answers will not affect the rest of this tutorial. Select an answer ideal for your project.

2. If you want to initialize a Git repository. We recommend you to select No and follow this guide's Git instructions below. If you select Yes, do not follow the below Git instructions precisely but adjust them to your needs.

create-cloudflare will then install dependencies, including the Wrangler CLI and the @astrojs/cloudflare adapter, and ask you setup questions.

Astro configuration

You can deploy an Astro Server-side Rendered (SSR) site to Cloudflare Pages using the @astrojs/cloudflare adapter. SSR sites render on Pages Functions and allow for dynamic functionality and customizations.

Add the @astrojs/cloudflare adapter to your project's package.json by running:

npm run astro add cloudflare

Deploy with Cloudflare Pages

<Render file="deploy-via-c3" product="pages" params={{ name: "Astro" }} />

Deploy via the Cloudflare dashboard

Optionally, you can customize the Project name field. It defaults to the GitHub repository's name, but it does not need to match. The Project name value is assigned as your *.pages.dev subdomain.

After completing configuration, select Save and Deploy.

You will see your first deployment in progress. Pages installs all dependencies and builds the project as specified.

Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to preview deployments, which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the Get started guide.

:::

Local runtime

Local runtime support is configured via the platformProxy option:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
	adapter: cloudflare({
		platformProxy: {
			enabled: true,
		},
	}),
});

Use bindings in your Astro application

A binding allows your application to interact with Cloudflare developer products, such as KV, Durable Object, R2, and D1.

Use bindings in Astro components and API routes by using context.locals from Astro Middleware to access the Cloudflare runtime which amongst other fields contains the Cloudflare's environment and consecutively any bindings set for your application.

Refer to the following example of how to access a KV namespace with TypeScript.

First, you need to define Cloudflare runtime and KV type by updating the env.d.ts. Make sure you have generated Cloudflare runtime types by running wrangler types.

/// <reference types="astro/client" />

type ENV = {
	// replace `MY_KV` with your KV namespace
	MY_KV: KVNamespace;
};

// use a default runtime configuration (advanced mode).
type Runtime = import("@astrojs/cloudflare").Runtime<ENV>;
declare namespace App {
	interface Locals extends Runtime {}
}

You can then access your KV from an API endpoint in the following way:

import type { APIContext } from "astro";

export async function get({ locals }: APIContext) {
	const { MY_KV } = locals.runtime.env;

	return {
		// ...
	};
}

Besides endpoints, you can also use bindings directly from your Astro components:

---
const myKV = Astro.locals.runtime.env.MY_KV;
const value = await myKV.get("key");
---
<div>{value}</div>

To learn more about the Astro Cloudflare runtime, refer to the Access to the Cloudflare runtime in the Astro documentation.

<Render file="framework-guides/learn-more" product="pages" params={{ one: "Astro" }} />