Skip to content
Alchemy
GitHubXDiscordRSS

TanStack Start

This guide shows how to initialize and deploy a TanStack Start application to Cloudflare using Alchemy.

Init

Section titled “Init”

Start by creating a new TanStack Start project with Alchemy:

Terminal window
bunx alchemy create my-tanstack-app --template=tanstack-start
cd my-tanstack-app

Log in to Cloudflare

Section titled “Log in to Cloudflare”

Authenticate once with your Cloudflare account:

Terminal window
bun wrangler 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 TanStack Start application:

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 { TanStackStart } from "alchemy/cloudflare";


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


export const worker = await TanStackStart("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

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "types": ["@cloudflare/workers-types", "./types/env.d.ts"]
  },
  "include": ["types/**/*.ts", "alchemy.run.ts", "src/**/*.ts"]
}

vite.config.ts

Section titled “vite.config.ts”

Use the alchemyDevEnvironmentShim() plugin to configure TanStack Start for local development:

import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import alchemy from "alchemy/cloudflare/tanstack-start";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";


export default defineConfig({
  build: {
    target: "esnext",
    rollupOptions: {
      external: ["node:async_hooks", "cloudflare:workers"],
    },
  },
  plugins: [
    alchemy(),
    tsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tanstackStart({
      target: "cloudflare-module",
      customViteReactPlugin: true,
    }),
    viteReact(),
  ],
});