Convex is the typesafe backend-as-a-service with realtime updates, server functions, crons and scheduled jobs, file storage, vector search, and more.

Quickstart

convex-svelte

Receive live updates to Convex query subscriptions and call mutations and actions from Svelte with convex-svelte.

To install:

``
npm install convex convex-svelte
`

Run npx convex init to get started with Convex.

See the example app live.

convex-svelte provides a setupConvex() function which takes a Convex deployment URL,
a useConvexClient() which returns a ConvexClient
used to set authentication credentials and run Convex mutations and actions,
and a useQuery() function for subscribing to Convex queries.

$3

Call setupConvex() in a component above the components that need to Convex queries
and use useQuery() components where you need to listen to the query.

See +layout.svelte for setupConvex()

`svelte

`

and Chat.svelte for how to use useQuery()

`svelte


...
{#if query.isLoading}
Loading...
{:else if query.error != null}
failed to load: {query.error.toString()}
{:else}


{#each query.data as message}

• 
  {message.author}
  {message.body}
  

{/each}


{/if}
`

Running a mutation looks like

`svelte





Send



`

$3

You can conditionally skip a query by returning the string 'skip' from the arguments function.
This is useful when a query depends on some condition, like authentication state or user input.

`svelte


{#if activeUserResponse.isLoading}
Loading user...
{:else if activeUserResponse.error}
Error: {activeUserResponse.error}
{:else if activeUserResponse.data}
Welcome, {activeUserResponse.data.name}!
{/if}
`

When a query is skipped, isLoading will be false, error will be null, and data will be undefined.

$3

useQuery() accepts an initialData option in its third argument.
By defining a load() function in a +page.server.ts file
that uses the ConvexHttpClient to request the same query to get initial data
and passing that through to the initialData option of a useQuery call you can avoid an initial loading state.

`ts
// +page.server.ts
import { ConvexHttpClient } from 'convex/browser';
import type { PageServerLoad } from './$types.js';
import { PUBLIC_CONVEX_URL } from '$env/static/public';
import { api } from '../convex/_generated/api.js';

export const load = (async () => {
const client = new ConvexHttpClient(PUBLIC_CONVEX_URL!);
return {
messages: await client.query(api.messages.list, { muteWords: [] })
};
}) satisfies PageServerLoad;
`

`svelte

`

Combining specifying initialData and either setting the keepPreviousData option to true or never modifying the arguments passed to a query should be enough to avoid ever seeing a loading state for a useQuery().

$3

#### effect_in_teardown Error

If you encounter effect_in_teardown errors when using useQuery in components that can be conditionally rendered (like dialogs, modals, or popups), this is caused by wrapping useQuery in a $derived block that depends on reactive state.

When useQuery is wrapped in $derived, state changes during component cleanup can trigger re-evaluation of the $derived, which attempts to create a new useQuery instance. Since useQuery internally creates a $effect, and effects cannot be created during cleanup, this throws an error.

Use Conditionally skipping queries instead. By calling useQuery unconditionally at the top level and passing a function that returns 'skip', the function is evaluated inside useQuery's own effect tracking, preventing query recreation during cleanup.

$3

In production build pipelines use the build command

`bash
npx convex deploy --cmd-url-env-var-name PUBLIC_CONVEX_URL --cmd 'npm run build'
`

to build your Svelte app and deploy Convex functions.

Trying out this library

Clone this repo and install dependencies with npm install then start a development server:

`bash
npm run dev
`

This will run you through creating a Convex account and a deployment.

Everything inside src/lib is part of the library, everything inside src/routes is an example app.

Developing this library

To build the library:

`bash
npm run package
`

To create a production version of the showcase app:

`bash
npm run build
`

You can preview the production build with npm run preview.

> To deploy your app, you may need to install an adapter for your target environment.

Publishing

Go into the package.json and give your package the desired name through the "name" option. Also consider adding a "license" field and point it to a LICENSE file which you can create from a template (one popular option is the MIT license).

To publish your library to npm:

`bash
npm publish
``