Skip to content
Alchemy
GitHubXDiscordRSS

Astro

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

Init

Section titled “Init”

Start by creating a new Astro project with Alchemy:

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

Login

Section titled “Login”

Authenticate once with your Cloudflare account:

Terminal window
bun alchemy login

Deploy

Section titled “Deploy”

Run the deploy script generated by the template:

Terminal window
bun run deploy

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

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

Local Development

Section titled “Local Development”

Work locally using the dev script:

Terminal window
bun run dev

Destroy

Section titled “Destroy”

Clean up all Cloudflare resources created by this stack:

Terminal window
bun run destroy

What files are created

Section titled “What files are created”

.env

Section titled “.env”

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

ALCHEMY_PASSWORD=change-me

alchemy.run.ts

Section titled “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");


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


await app.finalize();

types/env.d.ts

Section titled “types/env.d.ts”
// Auto-generated Cloudflare binding types.
// @see https://alchemy.run/concepts/bindings/#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

Section titled “tsconfig.json”

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

{
  "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

Section titled “astro.config.mjs”

Use the alchemy() adapter to develop and deploy for Cloudflare Workers:

import alchemy from 'alchemy/cloudflare/astro';
import { defineConfig } from 'astro/config';


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

If you run astro dev without first running Alchemy, you will get an error from getPlatformProxyOptions(). This is because Alchemy needs to be run first to create the local environment. We recommend running alchemy dev, which runs astro dev automatically.