> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a SvelteKit app on floo

> Deploy a SvelteKit app with Postgres, sign-in, and a custom domain.

From a SvelteKit 3 project on GitHub to a live app at `https://<app>.getfloo.app`, with managed Postgres, signed-in users, and your own domain.

New to floo? Start with the [Quickstart](https://getfloo.com/docs/introduction.md).

## What your agent controls

floo builds the `Dockerfile` in your repository. Add one that specifies the runtime for your app:

* The base image and the exact Node version.
* System packages, such as `ffmpeg` or Chromium for headless browsing, each one `apt-get install` line.
* The build steps and the start command.
* More services from the same repository, such as a background worker or a [cron job](https://getfloo.com/docs/guides/cron-jobs.md).

Declare services, managed Postgres, sign-in, and domains in `floo.app.toml`. Store secrets outside git.

## 1. Add a Dockerfile

Build with [`@sveltejs/adapter-node`](https://svelte.dev/docs/kit/adapter-node), which outputs a standalone Node server:

```bash theme={null}
npm install -D @sveltejs/adapter-node
npm uninstall @sveltejs/adapter-auto
```

SvelteKit 3 takes its configuration in `vite.config.ts`, not `svelte.config.js`:

```ts vite.config.ts theme={null}
import adapter from "@sveltejs/adapter-node";
import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sveltekit({ adapter: adapter() })],
});
```

```dockerfile Dockerfile theme={null}
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
RUN npm prune --omit=dev

FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production \
    PROTOCOL_HEADER=x-forwarded-proto \
    HOST_HEADER=x-forwarded-host
COPY --from=build /app/package.json ./
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/build ./build
CMD ["node", "build"]
```

The adapter's server reads `PORT` and listens on `0.0.0.0` by default. `PROTOCOL_HEADER` and `HOST_HEADER` tell it the public URL from floo's edge, which form actions need to pass SvelteKit's cross-site request check. Add a `.dockerignore` listing `node_modules`, `build`, and `.svelte-kit`.

## 2. Initialize the floo config

Install the CLI and sign in: `curl -fsSL https://getfloo.com/install.sh | bash`, then `floo auth login`. An agent can run the same journey over the HTTP API instead, starting from [getfloo.com/agents.md](https://getfloo.com/agents.md).

```bash theme={null}
floo init my-sveltekit-app
```

For a single-service SvelteKit app:

```toml floo.app.toml theme={null}
[app]
name = "my-sveltekit-app"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
dev_command = "npm run dev -- --port 3000 --host 127.0.0.1"
```

After adding Postgres, set `migrate_command` under `[services.web]` to your migration tool, such as `"npx drizzle-kit migrate"`. Keep that tool in `dependencies`, not `devDependencies`, so `npm prune` leaves it in the image. It runs as a one-off job with the new image before traffic moves to it. A failed migration stops the deploy. Use [expand-then-contract migrations](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod) to keep the schema compatible with both old and new code.

## 3. Connect the repo and deploy

floo builds from your GitHub repository, not local files, so commit first. `floo deploy` pushes the commit and waits until the dev URL is live. The first time, it stops with one link if the floo GitHub App can't read the repository yet: a human opens it and installs the App on the account that owns the repository, then you run `floo deploy` again. See [Give floo access to your GitHub repository](https://getfloo.com/docs/introduction.md#2-give-floo-access-to-your-github-repository).

```bash theme={null}
git add . && git commit -m "feat: floo config + Dockerfile"
floo deploy --preflight
floo deploy
```

No GitHub repository? `floo deploy --hosted` has floo host the repository. See [Deploy without GitHub](https://getfloo.com/docs/deploy/without-github.md).

When it's done:

```bash theme={null}
floo apps show my-sveltekit-app
```

> [!TIP]
>
> **Your SvelteKit app is live** at `https://my-sveltekit-app.getfloo.app`.
>
> Every `git push origin main` ships to dev.

## 4. Add a Postgres database

```toml floo.app.toml theme={null}
[managed.default]
type = "postgres"
```

```bash theme={null}
npm install postgres
git add . && git commit -m "feat: add postgres"
floo deploy --preflight
floo deploy
```

Preflight warns `MANAGED_CREDS_TO_WEB` because the web service receives the database credentials. That is expected when the web service queries the database.

`DATABASE_URL` is injected at runtime. SvelteKit 3 exposes only the variables declared in `src/env.ts`, so declare it there. floo sets it when the server starts, not during `vite build`, so the schema allows it to be missing while building:

```ts src/env.ts theme={null}
import { building } from "$app/env";
import { defineEnvVars } from "@sveltejs/kit/env";

export const variables = defineEnvVars({
  DATABASE_URL: {
    schema: (value) => {
      if (value === undefined && !building) throw new Error("DATABASE_URL is not set");
      return value ?? "";
    },
  },
});
```

```ts src/lib/server/db.ts theme={null}
import postgres from "postgres";
import { DATABASE_URL } from "$app/env/private";

export const sql = postgres(DATABASE_URL);
```

```ts src/routes/+page.server.ts theme={null}
import { sql } from "#lib/server/db.js";

export async function load() {
  const [{ now }] = await sql`select now()`;
  return { dbTime: now.toISOString() };
}
```

`postgres` connects on the first query and reads the TLS settings in the URL. Dev and prod each get a separate Postgres database and credentials, with no shared state.

## 5. Add per-user auth

Set `access_mode = "accounts"` and floo handles sign-in:

```toml floo.app.toml theme={null}
[app]
name = "my-sveltekit-app"
access_mode = "accounts"
```

From the next deploy onward, floo's gateway:

* Redirects unauthenticated requests to a hosted login page.
* Validates the session cookie on every request.
* Injects identity headers into every request that reaches your SvelteKit server.

Read them once in a server hook, with no auth code, callback handlers, or session storage:

```ts src/hooks.server.ts theme={null}
import type { Handle } from "@sveltejs/kit/hooks";

export const handle: Handle = async ({ event, resolve }) => {
  const email = event.request.headers.get("x-floo-user-email");
  const id = event.request.headers.get("x-floo-user-id");
  event.locals.user = email && id
    ? { email, id, name: event.request.headers.get("x-floo-user-name") }
    : null;
  return resolve(event);
};
```

```ts src/app.d.ts theme={null}
declare global {
  namespace App {
    interface Locals {
      user: { email: string; id: string; name: string | null } | null;
    }
  }
}

export {};
```

Then use `locals.user` in any `load` function, form action, or `+server.ts` route:

```ts src/routes/dashboard/+page.server.ts theme={null}
import { error } from "@sveltejs/kit";

export function load({ locals }) {
  if (!locals.user) error(401, "Sign in required");
  return { user: locals.user };
}
```

Locally, run `floo dev --fixture-user` (see [section 7](#7-local-development-with-dev-credentials)) or send the headers yourself with `curl -H 'X-Floo-User-Email: you@example.com' ...`. Access modes and identity headers in full: [App sign-in](https://getfloo.com/docs/guides/app-auth.md).

## 6. Add a custom domain

Declare the domain in `floo.app.toml`:

```toml theme={null}
[domains."app.example.com"]
service = "web"
```

Commit and push, wait for that commit's dev deploy to go live, then release it
to prod and read the DNS records:

Replace `owner/repo` with your GitHub repository. For a floo-hosted project, see [Environments](https://getfloo.com/docs/guides/environments.md#the-flow).

```bash theme={null}
gh release create v1 --repo owner/repo
```

Wait for the prod deploy to finish, then read the DNS records:

```bash theme={null}
floo domains show app.example.com --app my-sveltekit-app
```

Publish the traffic and certificate CNAME records that `show` prints, then watch
activation:

```bash theme={null}
floo domains watch app.example.com --app my-sveltekit-app
```

With `HOST_HEADER` set, `event.url` carries the custom domain, so it needs no extra config. DNS setup and troubleshooting: [Custom domains](https://getfloo.com/docs/guides/custom-domains.md).

## 7. Local development with dev credentials

```bash theme={null}
floo dev --app my-sveltekit-app
```

Runs `dev_command` locally with `DATABASE_URL` and readable env vars from the app's dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Write-only secrets are withheld; supply separate local values when needed. Prod credentials never reach a local session.

The database exists after the first deploy that declares `[managed.default]`. Before that deploy, `floo dev` starts without `DATABASE_URL`.

To test signed-in flows, add `--fixture-user`:

```bash theme={null}
floo dev --app my-sveltekit-app --fixture-user you@example.com
```

`floo dev` then puts a proxy in front of each accounts-mode service that injects the same `X-Floo-User-*` headers floo's gateway adds in production. The output table shows the raw service URL and the auth-proxied URL; use the auth-proxied one for any path that reads identity headers.

## Common gotchas

* **`/healthz` is reserved.** floo's edge intercepts that exact path. Use `/health` or `/livez`.
* **`--host 127.0.0.1` in `dev_command`.** On macOS the dev server listens on `::1` by default, and the `floo dev --fixture-user` proxy reaches it at `127.0.0.1`. Without the flag, proxied requests fail with an empty reply.
* **An undeclared variable is undefined.** A variable floo injects reaches your code only if `src/env.ts` declares it. Without the declaration, `postgres` falls back to `PG*` defaults and fails with `connection is insecure`.
* **`static: true` for runtime values.** A static variable is inlined at build time, when `DATABASE_URL` and secrets are not set. Leave `static` off for anything floo injects.
* **`#lib`, not `$lib`.** SvelteKit 3 imports from `src/lib` through the `#lib` mapping in `package.json`, with the file extension: `#lib/server/db.js`.
* **Form actions return 403 "Cross-site POST form submissions are forbidden".** `PROTOCOL_HEADER` or `HOST_HEADER` is missing from the final stage, so the server thinks its origin is not the public URL.
* **Values for the browser.** Declare them with `public: true` in `src/env.ts` and import them from `$app/env/public`. Without `static: true`, they are read when the server starts, so floo needs no build arg for them.

## Next steps

> [card] [App sign-in](https://getfloo.com/docs/guides/app-auth.md)
>
> Identity headers, access policies, and access modes in detail.

> [card] [Environment variables](https://getfloo.com/docs/guides/environment-variables.md)
>
> Secrets, build-time variables, and per-service values.

> [card] [Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)
>
> Layer order for fast pushes and recommended multi-stage builds.

> [card] [Production environments](https://getfloo.com/docs/guides/environments.md)
>
> Dev vs prod, promotion, env overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.