Astro

This guide shows how to initialize and deploy an Astro server-side–rendered site to Cloudflare using Alchemy.

Init

Start by creating a new Astro project with Alchemy:

bun

bunx alchemy create my-astro-app --template=astro
cd my-astro-app

npm

npx alchemy create my-astro-app --template=astro
cd my-astro-app

pnpm

pnpm dlx alchemy create my-astro-app --template=astro
cd my-astro-app

yarn

yarn dlx alchemy create my-astro-app --template=astro
cd my-astro-app

Login

Authenticate once with your Cloudflare account:

bun

bun wrangler login

npm

npx wrangler login

pnpm

pnpm wrangler login

yarn

yarn wrangler login

Tip

Alchemy automatically re-uses your Wrangler OAuth tokens. See the Cloudflare guide for other options.

Deploy

Run the deploy script generated by the template:

bun

bun run deploy

npm

npm run deploy

pnpm

pnpm run deploy

yarn

yarn run deploy

You’ll get the live URL of your Astro site:

{
  url: "https://website.<your-account>.workers.dev",
}

Local Development

Work locally using the dev script:

bun

bun run dev

npm

npm run dev

pnpm

pnpm run dev

yarn

yarn run dev

Destroy

Clean up all Cloudflare resources created by this stack:

bun

bun run destroy

npm

npm run destroy

pnpm

pnpm run destroy

yarn

yarn run destroy

What files are created

.env

Alchemy requires a locally set password to encrypt Secrets that are stored in state. Be sure to change this.

Note

See the Secret documentation to learn more.

ALCHEMY_PASSWORD=change-me

alchemy.run.ts

/// <reference types="@types/node" />

import alchemy from "alchemy";
import { Astro } from "alchemy/cloudflare";

const app = await alchemy("my-astro-app");

export const worker = await Astro("website", {
  command: "bun run build",
});

console.log({
  url: worker.url,
});

await app.finalize();

types/env.d.ts

// Auto-generated Cloudflare binding types.
// @see https://alchemy.run/docs/concepts/bindings.html#type-safe-bindings

import type { worker } from "../alchemy.run.ts";

export type CloudflareEnv = typeof worker.Env;

declare global {
  type Env = CloudflareEnv;
}

declare module "cloudflare:workers" {
  namespace Cloudflare {
    export interface Env extends CloudflareEnv {}
  }
}

tsconfig.json

The CLI updated the tsconfig.json to include alchemy.run.ts and register @cloudflare/workers-types + types/env.d.ts globally

Tip

The alchemy.run.ts script will be run by node but still needs to infer the Binding types which depends on @cloudflare/workers-types:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*", "types/**/*.ts", "alchemy.run.ts"],
  "exclude": ["dist"],
  "compilerOptions": {
    "types": ["@cloudflare/workers-types", "./types/env.d.ts"]
  }
}

astro.config.mjs

Use the @astrojs/cloudflare plugin to build for Cloudflare Workers:

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

// https://astro.build/config
export default defineConfig({
  output: "server",
  adapter: cloudflare(),
});