TanStack Start

Deploy TanStack Start applications to Cloudflare Workers with Alchemy

Deploy TanStack Start applications to Cloudflare Workers with automatic configuration.

Installation

Install the required dependencies:

npm install alchemy @tanstack/react-start @tanstack/react-start-cloudflare

Configuration

Configuration Options

Properties

• bindings: Cloudflare bindings (KV, R2, D1, etc.)
• entrypoint: Worker entrypoint path
  • Default: dist/server/index.js
• assets: Static assets directory
  • Default: dist/client
• wrangler.main: Path to server entry point
  • Default: src/server.ts (if exists), otherwise uses @tanstack/react-start/server-entry
• compatibility: Node.js compatibility mode
  • Default: "node"
• noBundle: Skip bundling
  • Default: true

Accessing Bindings

Access Cloudflare bindings in your TanStack Start application:

Server Functions

import { createServerFn } from "@tanstack/react-start/server";
import { getWebRequest } from "vinxi/http";

export const getUsers = createServerFn("GET", async () => {
  const request = getWebRequest();
  const env = request.env as Env;
  const db = env.DB;
  
  const result = await db.prepare("SELECT * FROM users").all();
  return result.results;
});

API Routes

// src/routes/api.users.$id.ts
import { getWebRequest } from "vinxi/http";

export const GET = async ({ params }: { params: { id: string } }) => {
  const request = getWebRequest();
  const env = request.env as Env;
  const kv = env.KV;
  
  const user = await kv.get(`user:${params.id}`);
  return new Response(user, {
    headers: { "Content-Type": "application/json" },
  });
};

Loaders

import { createFileRoute } from "@tanstack/react-router";
import { getWebRequest } from "vinxi/http";

export const Route = createFileRoute("/users")({
  loader: async () => {
    const request = getWebRequest();
    const env = request.env as Env;
    const db = env.DB;
    
    const users = await db.prepare("SELECT * FROM users").all();
    return { users: users.results };
  },
});

TypeScript Configuration

Define types for your Cloudflare bindings:

// src/env.d.ts
import type { D1Database, KVNamespace } from "@cloudflare/workers-types";

declare global {
  interface Env {
    DB: D1Database;
    KV: KVNamespace;
    API_SECRET: string;
  }
}

export {};

Local Development

Start the TanStack Start dev server:

npm run dev

The Alchemy Vite plugin provides:

• Local emulation of Cloudflare bindings
• Hot module replacement
• Fast refresh

Custom Dev Configuration

const website = await TanStackStart("website", {
  dev: {
    command: "vite dev --port 3000",
    domain: "localhost:3000",
  },
});

Server Entry Point

The resource automatically detects your server entry point:

• If src/server.ts exists, it will be used
• Otherwise, falls back to @tanstack/react-start/server-entry

Custom Server Entry

Specify a custom server entry:

const website = await TanStackStart("website", {
  wrangler: {
    main: "src/custom-server.ts",
  },
});

Node.js Compatibility

TanStack Start automatically enables Node.js compatibility:

• Node.js built-in modules
• npm packages with Node.js dependencies
• Full TanStack Start feature set

Deployment Best Practices

• Keep dist/ directory in .gitignore
• Use environment variables for secrets via alchemy.secret.env.X
• Test locally with Vite dev server
• Configure proper TypeScript types for bindings
• Use server functions for data fetching

Related Resources

• Website - Base resource for web applications
• Worker - Cloudflare Workers deployment
• KV Namespace - Key-value storage
• D1 Database - SQL database