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

# Bijection Svelte

> Reactive Svelte 5 client library for Bijection, with real-time subscriptions, mutations, actions, pagination, auth, and SvelteKit SSR.

[Bijection Svelte](https://www.npmjs.com/package/bijection-svelte) is the client
library enabling your Svelte application to interact with your Bijection backend.
It enhances the [`BijectionClient`](/api/classes/browser.BijectionClient) with
declarative subscriptions for [Svelte 5](https://svelte.dev/), so your frontend
code can:

1. Receive live updates to your [queries](/functions/query-functions) with
   automatic reactivity
2. Call your [mutations](/functions/mutation-functions) and
   [actions](/functions/actions)
3. [Paginate](/database/pagination) through large datasets
4. [Authenticate users](/auth/overview)
5. [Server-side render](/client/svelte/sveltekit-server-rendering) data in
   SvelteKit

<Info>
  **Source & issues**

  Source: bijectionhq/bijection-svelte.

  <br /> Found a bug or have a feature request? Open an issue in its issue
  tracker.
</Info>

Follow the [Svelte Quickstart](/quickstart/svelte) to get started, or read
on for the full setup.

## Installation

[Install the Bijection CLI](/get-started/install), then add a Bijection
backend to your SvelteKit app from its root directory:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection init
```

Svelte doesn't like referencing code outside of `src/`, so move the Bijection
functions directory there and point `bijection.json` at it:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mv bijection src/bijection
```

```json bijection.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "$schema": "./node_modules/bijection/schemas/bijection.schema.json",
  "functions": "src/bijection/"
}
```

The Bijection SDK (`bijection/react`, `bijection/browser`, …) is not published
to the npm registry. Your app declares it as a tarball from bijection.com, for
the version of your CLI (`bijection --version` prints it). Add this line to the
`dependencies` in your app's `package.json`:

```json package.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
"bijection": "https://bijection.com/sdk/bijection-0.1.1.tgz"
```

Then install your app's dependencies with its package manager as usual (for
example `npm install`). The `react-vite` and `nextjs` templates of
`bijection init` write this line and run the install for you.

Also add `bijection-svelte` to your app with your package manager.

Log in once per machine and set up a Bijection dev deployment:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection login
bijection dev
```

The first run of `bijection dev` creates your dev deployment and saves its URL
in `.env.local` as `PUBLIC_BIJECTION_URL`.

## Setup

Call `setupBijection()` once in a root layout component (e.g. `+layout.svelte`).
This initializes a [`BijectionClient`](/api/classes/browser.BijectionClient) and
stores it in Svelte context so child components can access it. The client is
app-scoped: it stays open for the lifetime of the app (remounts and HMR reuse
the same connection) and supports a single deployment URL. For explicit teardown
— e.g. in tests — call `closeBijection()`.

```svelte src/routes/+layout.svelte theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
<script lang="ts">
  import { setupBijection } from "bijection-svelte";
  import { PUBLIC_BIJECTION_URL } from "$env/static/public";

  const client = setupBijection(PUBLIC_BIJECTION_URL);
</script>
```

`setupBijection()` returns the `BijectionClient` instance, which you can use directly
in the layout for mutations or actions (e.g. an auth nav bar). In child
components and `.ts` files, use `getBijectionClient()` to retrieve it — see
[Client access](/client/svelte/reactivity#client-access).

You can pass `BijectionClientOptions` as the second argument to configure the
[`BijectionClient`](/api/classes/browser.BijectionClient).

<Info>
  **Non-SvelteKit usage**

  If you're using plain Vite + Svelte (no SvelteKit), replace `$env/static/public`
  with `import.meta.env.VITE_BIJECTION_URL` and set `VITE_BIJECTION_URL` in your `.env`
  file.
</Info>

## Fetching data

Use `useQuery()` to subscribe to a Bijection query with automatic real-time
updates. When the data changes on the server, your component re-renders
automatically.

```svelte src/routes/+page.svelte theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
<script lang="ts">
  import { useQuery } from "bijection-svelte";
  import { api } from "../bijection/_generated/api.js";

  const messages = useQuery(api.messages.list, () => ({ searchWords: [] }));
</script>

{#if messages.isLoading}
  Loading...
{:else if messages.error != null}
  failed to load: {messages.error.toString()}
{:else}
  <ul>
    {#each messages.data as message}
      <li>
        <span>{message.author}</span>
        <span>{message.body}</span>
      </li>
    {/each}
  </ul>
{/if}
```

See [Queries, Mutations & Actions](/client/svelte/reactivity) for the full
reactive API — query options, skipping, mutations, actions, optimistic updates,
pagination, and accessing the client outside of components.

## Next steps

* [Queries, Mutations & Actions](/client/svelte/reactivity) — the core
  reactive API
* [Authentication](/client/svelte/authentication) — wire up auth providers
* [SvelteKit Server Rendering](/client/svelte/sveltekit-server-rendering) —
  SSR with `bijectionLoad`
* [Why server-side rendering with Bijection?](/client/svelte/why-server-rendering)
  — performance deep dive
* [Troubleshooting](/client/svelte/troubleshooting) — common errors and
  fixes