---
title: TanStack Start
description: How to integrate varlock with TanStack Start for secure, type-safe environment management
---
import { Steps } from "@astrojs/starlight/components";
import Badge from '@/components/Badge.astro';
import ExecCommandWidget from '@/components/ExecCommandWidget.astro';
import InstallJsDepsWidget from '@/components/InstallJsDepsWidget.astro';

[TanStack Start](https://tanstack.com/start) is a full-stack React framework built on [Vite](https://vite.dev), so there's no dedicated TanStack Start package. Which integration you use depends on where you deploy.

- **Node / Vercel / Netlify / self-hosted**: use the [**Vite integration**](/integrations/vite/). See [setup below](#setup).
- **Cloudflare Workers**: use the [**Cloudflare integration**](/integrations/cloudflare/). See [Cloudflare setup below](#deploying-to-cloudflare-workers).

Check out the [TanStack Start example project](https://github.com/dmno-dev/varlock-examples/tree/main/examples/tanstack-start) for a working reference.

---

## Setup (vite integration)

<div class="page-badges">
  <Badge npmPackage="@varlock/vite-integration" />
</div>

For any deployment target _other than_ Cloudflare Workers, use `varlockVitePlugin` from the [Vite integration](/integrations/vite/).

<Steps>

1. **Install packages**
    <InstallJsDepsWidget packages="@varlock/vite-integration varlock" />

1. **Run `varlock init` to set up your `.env.schema`**

    This will guide you through setting up your `.env.schema` file, based on your existing `.env` file(s). Make sure to review it carefully.

    <ExecCommandWidget command="varlock init" showBinary={false} />

1. **Add the plugin to your Vite config**

    ```diff lang="ts" title="app.config.ts"
    import { defineConfig } from '@tanstack/react-start/config';
    import { tanstackStart } from '@tanstack/react-start/plugin/vite'
    +import { varlockVitePlugin } from '@varlock/vite-integration';

    export default defineConfig({
      vite: {
        plugins: [
    +      varlockVitePlugin(),
          tanstackStart(),
          // ... other plugins
        ],
      },
    });
    ```

</Steps>

:::tip[Next steps]
See the [**Vite integration page**](/integrations/vite/) for configuration options, SSR injection modes, accessing env vars, managing environments, sensitive values, and more.
:::

---

## Setup for Cloudflare Workers

<div class="page-badges">
  <Badge npmPackage="@varlock/cloudflare-integration" />
</div>

If you're deploying your TanStack Start app to Cloudflare Workers, use `varlockCloudflareVitePlugin` from the [Cloudflare integration](/integrations/cloudflare/) instead.

<Steps>

1. **Install packages**

    You must also install `@cloudflare/vite-plugin` as a peer dependency.

    <InstallJsDepsWidget packages="@varlock/cloudflare-integration @cloudflare/vite-plugin varlock" />

1. **Run `varlock init` to set up your `.env.schema`**

    <ExecCommandWidget command="varlock init" showBinary={false} />

1. **Add the Cloudflare Vite plugin**

    ```diff lang="ts" title="app.config.ts"
    import { defineConfig } from '@tanstack/react-start/config';
    import { tanstackStart } from '@tanstack/react-start/plugin/vite'
    +import { varlockCloudflareVitePlugin } from '@varlock/cloudflare-integration';

    export default defineConfig({
      vite: {
        plugins: [
    +      varlockCloudflareVitePlugin(),
          tanstackStart(),
          // ...
        ],
      },
    });
    ```

1. **Deploy with `varlock-wrangler`**

    Use `varlock-wrangler deploy` instead of `wrangler deploy` in your deploy script:

    ```diff lang="json" title="package.json" add="varlock-"
    {
      "scripts": {
        "deploy": "varlock-wrangler deploy"
      }
    }
    ```

    If you deploy via [Cloudflare Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) instead of a local/CI script, override the deploy command in your Cloudflare dashboard under **Settings → Build → Deploy command**. See [Workers Builds](#deploying-via-cloudflare-workers-builds) below.

</Steps>

:::tip[Next steps]
See the [**Cloudflare integration page**](/integrations/cloudflare/) for more on `varlock-wrangler`, multi-environment setup, and deploying secrets.
:::

### Deploying via Cloudflare Workers Builds

If you deploy through [Cloudflare Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/), two pieces of configuration must be set in the dashboard, and neither can be committed to the repo:

- **Override the Deploy command.** Under **Settings → Build → Deploy command**, replace the default `npx wrangler deploy` with `npx varlock-wrangler deploy`. Without this, Cloudflare runs stock `wrangler deploy`, which skips varlock resolution and leaves your worker without its resolved vars/secrets.
- **Set any _secret-zero_ vars under Build variables.** Any env vars varlock itself needs _during load_ (e.g. a 1Password service account token, a GCP key) must be set under **Settings → Build → Variables and Secrets** so they're available at build time. `varlock-wrangler deploy` then resolves your full env graph and uploads the result to the worker runtime as regular vars/secrets.

See the [Cloudflare integration page](/integrations/cloudflare/) for more detail on `varlock-wrangler` and [Workers Builds configuration](/integrations/cloudflare/#cloudflare-workers-builds-cicd).

---

## Compared to TanStack Start's built-in env var handling

TanStack Start inherits [Vite's env var approach](https://tanstack.com/start/v0/docs/framework/react/guide/environment-variables): `process.env` on the server and `import.meta.env` on the client, with only `VITE_`-prefixed vars exposed client-side. Their docs recommend maintaining a manual `src/env.d.ts` for TypeScript support and separate Zod schemas for runtime validation.

With varlock, your `.env.schema` is the single source of truth. It handles validation, type coercion, TypeScript generation, sensitivity controls, and more, replacing the need for separate type declarations, Zod schemas, and the `VITE_` prefix convention. You also get leak detection (sensitive values are automatically scrubbed from outgoing HTTP responses) and clear error messages when env vars are missing or invalid, so no more silent `undefined` values at runtime. See the [Vite integration page](/integrations/vite/) for the full details.

:::note[Encrypting the env blob]
When deploying SSR TanStack Start apps to serverless platforms, varlock injects the resolved env into your server-side build output as plaintext JSON. This is generally safe since it only appears in server code, but you can encrypt it for extra protection (e.g., against sourcemap leaks). See the [encrypted deployments guide](/guides/encrypted-deployments/) for setup instructions.
:::
