Skip to content

TanStack Start

Archil.Website.TanStackStart deploys a TanStack Start app to an Archil sandbox, (React or Solid), built through your own vite build. The site is the program of its own sandbox, on port 3000, at a public https://3000-…archil.app URL. A stopped sandbox starts again on the next request.

Install

Section titled “Install”

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads its /tanstack-start and /tanstack-start/node exports from your project at deploy time. It is only used at build time, so a dev dependency is enough:

Terminal window
pnpm add -D https://pkg.alchemy.run/@alchemy.run/frontend-frameworks/pr:2930:0cabab6

Configure Vite

Section titled “Configure Vite”

Your vite.config.ts stays what TanStack Start’s scaffold gives you — no adapter, no deployment preset. Vite plugins like Tailwind go in plugins as usual:

vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";


export default defineConfig({
  plugins: [tailwindcss(), tanstackStart(), viteReact()],
});

Alchemy drives that config’s builder.buildApp() and forces the SSR bundle to be self-contained, then wraps its fetch handler as a Node HTTP server on port 3000.

Declare the Website

Section titled “Declare the Website”

Declare the site as a module-level const:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";


export const Website = Archil.Website.TanStackStart("Website");

sandbox sizes the site’s sandbox and sets its image, timeouts, disks and network policy:

alchemy.run.ts
export const Website = Archil.Website.TanStackStart("Website", {
  sandbox: { vcpuCount: 2, memSizeMiB: 4096, idleTtlSeconds: 600 },
});

Add it to the Stack

Section titled “Add it to the Stack”

Yield the site from your Stack and return its URL:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";


export const Website = Archil.Website.TanStackStart("Website");


export default Alchemy.Stack(
  "MyTanStackStartSite",
  {
    providers: Archil.providers(),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

Run alchemy deploy. url is the site’s https://3000-…archil.app URL. site.sandbox is the sandbox behind it, and undefined under alchemy dev.

See examples/archil-website-tanstack-start for the checked-in example.

Add environment variables

Section titled “Add environment variables”

Process environment is a top-level env map — plain strings, or Redacted values:

alchemy.run.ts
export const Website = Archil.Website.TanStackStart("Website", {
  env: {
    API_BASE: "https://api.example.com",
  },
});

The values are copied onto process.env before the build and the dev server, and onto the program at deploy time, so server code reads the same keys in both modes. Client inlining is whatever Vite does (VITE_ prefixes).

An output from another resource only exists once that resource is yielded, so declare the site inside the Stack generator instead:

alchemy.run.ts
Effect.gen(function* () {
  const api = yield* Api;


  const site = yield* Archil.Website.TanStackStart("Website", {
    env: { API_BASE: api.url },
  });


  return { url: site.url };
});

Read the environment in a server function

Section titled “Read the environment in a server function”

The TanStack Start server is a plain Node process, so server functions read the environment from process.env:

src/routes/index.tsx
import { createServerFn } from "@tanstack/react-start";


const getApiBase = createServerFn({ method: "GET" }).handler(() => ({
  apiBase: process.env.API_BASE ?? "unset",
}));

Values prefixed VITE_ are inlined into the client bundle at build time instead, as import.meta.env.VITE_* — set those in the shell that runs alchemy deploy, not in env.

Read the environment in a server route

Section titled “Read the environment in a server route”

Server routes run on the same Node process and read process.env the same way:

src/routes/api.hello.ts
import { createFileRoute } from "@tanstack/react-router";


export const Route = createFileRoute("/api/hello")({
  server: {
    handlers: {
      GET: () => new Response(process.env.API_BASE ?? "unset"),
    },
  },
});

Build configuration

Section titled “Build configuration”

The build runs through your project’s own vite.config.ts — the tanstackStart() plugin and everything else in it apply as-is. Keep vite’s default build.outDir (dist); the integration reads the server and client output from dist/server and dist/client.

Local dev

Section titled “Local dev”
Terminal window
bun alchemy dev

alchemy dev runs TanStack Start’s own Vite dev server (native HMR) instead of deploying; site.url is the local address and no Archil resources are created. Wrap the site in Alchemy.remote() to deploy the live sandbox even during dev:

export const Website = Archil.Website.TanStackStart("Website").pipe(
  Alchemy.remote(),
);

Solid variant

Section titled “Solid variant”

TanStack Start’s Solid flavor works the same way — swap the plugins in vite.config.ts and keep the identical alchemy.run.ts:

vite.config.ts
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
import { defineConfig } from "vite";
import viteSolid from "vite-plugin-solid";


export default defineConfig({
  plugins: [tanstackStart(), viteSolid({ ssr: true })],
});

@tanstack/solid-start exposes the same tanstackStart() plugin entry point and the same client/ssr build environments, so the deploy is identical.

Where next

Section titled “Where next”