sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ neon/ frontend/ tanstack-start.mdx

Neon.Website.TanStackStart builds the application's client and server output, then wraps the server Fetch handler for Node 24 on Neon Functions. It packages a Function ZIP, not a listening Bun server, container, or S3 hosting stack.

Prepare the app

Use an existing TanStack Start app or the runnable TanStack Start example. Configure deployment credentials, then install in the app directory:

Install Alchemy and its matching Effect dependencies first; use Node 24 for this build toolchain.

pnpm add -D @alchemy.run/frontend-frameworks @vercel/nft

Keep the tanstackStart() and React plugins in vite.config.*; no deployment preset is needed. Keep Vite's default dist output directory for this integration. Application routes and the router remain normal TanStack Start code.

Define the stack

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Neon from "@alchemy.run/neon";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "NeonTanStackStart",
  { providers: Neon.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {
    const site = yield* Neon.Website.TanStackStart("Web", {
      rootDir: ".",
    });
    return { url: site.url };
  }),
);

Client files are served from the artifact; unmatched requests reach the framework handler for SSR and server routes. Private server-side env values are process environment. VITE_* values are compiled into client code; keep privileged tokens out of them and out of server-function responses.

Develop and deploy

pnpm exec alchemy dev
pnpm exec alchemy deploy
pnpm exec alchemy destroy

Run separately, destroying when finished. Dev uses the native Vite server and HMR, returns a local URL, and creates no implicit Project or Function. Append .pipe(Alchemy.remote()) to the Website Effect to opt into live deployment during dev.

Omitting scope creates an Ohio Project on deploy. Supply either project or branch for an existing backend, and use Ohio when adding storage. Read scope and credentials before sharing backend credentials with application code.

:::caution[Deployment limits] Complete live framework acceptance remains unverified. Neon probes have served old code/env despite new active deployment IDs. This integration provisions no CDN or durable server cache, and registering a domain does not validate TLS. See the shared deployment limits. :::

Reference