### Start Svelte Development Server

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Run this command after cloning the repository and installing dependencies to start a local development server for trying out the library.

```bash
npm run dev
```

--------------------------------

### Setup Convex Client in Svelte Layout

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Initialize the Convex client in the root layout component. Ensure the PUBLIC_CONVEX_URL environment variable is set.

```svelte
<!-- +layout.svelte -->
<script lang="ts">
  import { PUBLIC_CONVEX_URL } from '$env/static/public';
  import { setupConvex } from 'convex-svelte';

  const { children } = $props();
  setupConvex(PUBLIC_CONVEX_URL);
</script>

{@render children()}
```

--------------------------------

### Install convex-svelte

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Install the necessary Convex packages for your Svelte project.

```bash
npm install convex convex-svelte
```

--------------------------------

### Setup Convex in Svelte Layout

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Call `setupConvex()` in a parent component to initialize the Convex client with your deployment URL. This should be done above components that require Convex functionality.

```svelte
<script>
	import { PUBLIC_CONVEX_URL } from '$env/static/public';

	setupConvex(PUBLIC_CONVEX_URL);
</script>
```

--------------------------------

### Execute Convex Mutations with useConvexClient

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Use `useConvexClient()` to get a client instance for executing mutations. The `client.mutation()` function sends data to your Convex backend. Ensure correct API paths and data structures are used.

```svelte
<script lang="ts">
	import { api } from '../../convex/_generated/api.js'; // depending on file location
	import { useConvexClient } from 'convex-svelte';
	const client = useConvexClient();

	let toSend = $state('');
	let author = $state('me');

	function handleSubmit(event: SubmitEvent) {
		event.preventDefault();

		const data = Object.fromEntries(new FormData(event.target as HTMLFormElement).entries());
		client.mutation(api.messages.send, {
			author: data.author as string,
			body: data.body as string
		});
	}
</script>

<form onsubmit={handleSubmit}>
	<input type="text" name="author" bind:value={author} />
	<input type="text" name="body" bind:value={toSend} />
	<button type="submit" disabled={!toSend}>Send</button>
</form>
```

--------------------------------

### Build Production Showcase App

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

This command creates a production-ready build of the showcase application.

```bash
npm run build
```

--------------------------------

### Initialize Convex Client with setupConvex

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Call setupConvex in a parent component to initialize the Convex client. It makes the client available to child components via Svelte's context API and handles cleanup.

```svelte
<script lang="ts">
  import { PUBLIC_CONVEX_URL } from '$env/static/public';
  import { setupConvex } from 'convex-svelte';

  const { children } = $props();

  // Initialize Convex client with your deployment URL
  setupConvex(PUBLIC_CONVEX_URL);

  // With optional ConvexClientOptions for custom configuration
  setupConvex(PUBLIC_CONVEX_URL, {
    unsavedChangesWarning: false,
    verbose: true
  });
</script>

<div class="app">
  <main>
    {@render children()}
  </main>
</div>
```

--------------------------------

### Build Convex Svelte Library

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Execute this command to build the Convex Svelte library during development.

```bash
npm run package
```

--------------------------------

### Use ConvexClient with useConvexClient

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Use useConvexClient to access the ConvexClient instance for running mutations, actions, and managing authentication. Ensure setupConvex has been called in a parent component.

```svelte
<script lang="ts">
  import { useConvexClient } from 'convex-svelte';
  import { api } from '../convex/_generated/api.js';

  const client = useConvexClient();

  let toSend = $state('');
  let author = $state('me');

  async function sendMessage(event: SubmitEvent) {
    event.preventDefault();
    const formData = new FormData(event.target as HTMLFormElement);

    // Run a mutation using the client
    await client.mutation(api.messages.send, {
      author: formData.get('author') as string,
      body: formData.get('body') as string
    });

    toSend = '';
  }

  // Run an action
  async function processData() {
    const result = await client.action(api.processing.analyze, {
      input: 'some data'
    });
    console.log('Action result:', result);
  }

  // Set authentication token
  function setAuth(token: string) {
    client.setAuth(token);
  }
</script>

<form onsubmit={sendMessage}>
  <input type="text" name="author" bind:value={author} />
  <input type="text" name="body" bind:value={toSend} />
  <button type="submit" disabled={!toSend}>Send</button>
</form>
```

--------------------------------

### Subscribe to Convex Queries with useQuery

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Use the `useQuery()` hook to subscribe to data from Convex. It handles loading states, errors, and displays data, rendering updates automatically. The `useResultFromPreviousArguments` option can be useful for optimizing updates.

```svelte
<script>
	const query = useQuery(api.messages.list, () => ({ muteWords }), {
		useResultFromPreviousArguments: true
	});
</script>

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

--------------------------------

### useQuery with Initial Data and Keep Previous Data Options

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Use `initialData` for SSR hydration and `keepPreviousData` to show stale results during new data loading. This prevents a loading state on argument changes.

```svelte
<script lang="ts">
  import { useQuery } from 'convex-svelte';
  import { api } from '../convex/_generated/api.js';
  import type { PageData } from './$types.js';

  // Receive SSR data from +page.server.ts
  let { data }: { data: PageData } = $props();

  let useStale = $state(true);
  let searchTerm = $state('');

  // Query with initialData and keepPreviousData options
  const messages = useQuery(
    api.messages.list,
    () => ({ muteWords: searchTerm ? [searchTerm] : [] }),
    () => ({
      initialData: data.messages,
      keepPreviousData: useStale
    })
  );
</script>

<label>
  <input type="checkbox" bind:checked={useStale} />
  Show stale data while loading
</label>

<input type="text" bind:value={searchTerm} placeholder="Filter messages..." />

<ul class:stale={messages.isStale}>
  {#if messages.data}
    {#each messages.data as message}
      <li>{message.author}: {message.body}</li>
    {/each}
  {/if}
</ul>

<style>
  .stale {
    opacity: 0.6;
  }
</style>
```

--------------------------------

### Publish Library to npm

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

After updating the package name and license in `package.json`, use this command to publish your library to the npm registry.

```bash
npm publish
```

--------------------------------

### Subscribe to Convex Queries with useQuery

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Use useQuery to subscribe to Convex queries, receiving reactive data, loading, error, and stale states. Supports reactive arguments via closures for dynamic subscriptions.

```svelte
<script lang="ts">
  import { useQuery } from 'convex-svelte';
  import { api } from '../convex/_generated/api.js';

  // Basic query subscription
  const messages = useQuery(api.messages.list, { muteWords: [] });

  // Query with reactive arguments using a closure
  let filterWords = $state('');
  let muteWords = $derived(
    filterWords.split(',').map(w => w.trim()).filter(Boolean)
  );

  const filteredMessages = useQuery(
    api.messages.list,
    () => ({ muteWords: muteWords })
  );
</script>

{#if messages.isLoading}
  <p>Loading messages...</p>
{:else if messages.error}
  <p>Error: {messages.error.message}</p>
{:else}
  <ul>
    {#each messages.data as message}
      <li>
        <strong>{message.author}</strong>: {message.body}
      </li>
    {/each}
  </ul>
{/if}
```

--------------------------------

### Deploy Svelte App with Convex Functions

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Use this command in production build pipelines to build your Svelte app and deploy Convex functions. It specifies environment variables for the Convex URL and the build command.

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

--------------------------------

### Server-Side Rendering with initialData

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Avoid initial loading states by providing `initialData` to `useQuery()`. Fetch data in a `+page.server.ts` file using `ConvexHttpClient` and pass it to the `initialData` option in the Svelte component.

```typescript
// +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
<script lang="ts">
	// +page.svelte
	import type { PageData } from './$types.js';
	let { data }: { data: PageData } = $props();

	import { useQuery, useConvexClient } from '$lib/client.svelte.js';
	import { api } from '../convex/_generated/api.js';

	const messages = useQuery(
		api.messages.list,
		() => args,
		() => ({ initialData: data.messages })
	);
</script>
```

--------------------------------

### Manually Set Convex Client Context

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Manually set a `ConvexClient` instance in Svelte context for custom configuration or sharing an existing client. Includes custom authentication and cleanup on unmount.

```svelte
<script lang="ts">
  import { ConvexClient } from 'convex/browser';
  import { setConvexClientContext } from 'convex-svelte';
  import { PUBLIC_CONVEX_URL } from '$env/static/public';

  const { children } = $props();

  // Create client with custom configuration
  const client = new ConvexClient(PUBLIC_CONVEX_URL, {
    unsavedChangesWarning: false
  });

  // Set custom authentication
  client.setAuth(async () => {
    const token = await getAuthToken();
    return token;
  });

  // Manually set the client in context
  setConvexClientContext(client);

  // Cleanup on unmount
  $effect(() => () => client.close());
</script>

{@render children()}
```

--------------------------------

### Conditionally Skip useQuery

Source: https://context7.com/get-convex/convex-svelte/llms.txt

Skip query execution by returning 'skip' from the arguments function. `isLoading` will be false, `error` null, and `data` undefined when skipped. Useful for auth-dependent queries.

```svelte
<script lang="ts">
  import { useQuery } from 'convex-svelte';
  import { api } from '../convex/_generated/api.js';

  let isAuthenticated = $state(false);
  let userId = $state<string | null>(null);

  // Skip query when not authenticated
  const userProfile = useQuery(
    api.users.getProfile,
    () => (isAuthenticated && userId ? { userId } : 'skip')
  );

  // Toggle authentication for demo
  function toggleAuth() {
    isAuthenticated = !isAuthenticated;
    userId = isAuthenticated ? 'user_123' : null;
  }
</script>

<button onclick={toggleAuth}>
  {isAuthenticated ? 'Logout' : 'Login'}
</button>

{#if userProfile.isLoading}
  <p>Loading profile...</p>
{:else if userProfile.error}
  <p>Error loading profile</p>
{:else if userProfile.data}
  <p>Welcome, {userProfile.data.name}!</p>
{:else}
  <p>Please log in to view your profile</p>
{/if}
```

--------------------------------

### Real-time Chat Component with Convex Svelte

Source: https://context7.com/get-convex/convex-svelte/llms.txt

A Svelte component for a chat application using `useQuery` for real-time messages and `useConvexClient` for sending messages. Supports features like filtering, stale data display, and query skipping.

```svelte
<!-- Chat.svelte -->
<script lang="ts">
  import { useQuery, useConvexClient } from 'convex-svelte';
  import { api } from '../convex/_generated/api.js';
  import type { Doc } from '../convex/_generated/dataModel.js';

  const { initialMessages = [] as Doc<'messages'>[] } = $props();

  let useStale = $state(true);
  let muteWordsString = $state('');
  let muteWords = $derived(
    muteWordsString.split(',').map(x => x.trim()).filter(x => x)
  );
  let toSend = $state('');
  let author = $state('me');
  let skipQuery = $state(false);

  // Subscribe to messages with all features
  const messages = useQuery(
    api.messages.list,
    () => (skipQuery ? 'skip' : { muteWords: muteWords }),
    () => ({ initialData: initialMessages, keepPreviousData: useStale })
  );

  const client = useConvexClient();

  function onSubmit(e: SubmitEvent) {
    e.preventDefault();
    const data = Object.fromEntries(
      new FormData(e.target as HTMLFormElement).entries()
    );
    toSend = '';
    client.mutation(api.messages.send, {
      author: data.author as string,
      body: data.body as string
    });
  }
</script>

<div class="chat">
  <label>
    Hide messages containing:
    <input type="text" bind:value={muteWordsString} placeholder="vim, emacs" />
  </label>

  <label>
    <input type="checkbox" bind:checked={useStale} />
    Display old results while loading
  </label>

  <label>
    <input type="checkbox" bind:checked={skipQuery} />
    Skip query
  </label>

  <form onsubmit={onSubmit}>
    <input type="text" name="author" bind:value={author} />
    <input type="text" name="body" bind:value={toSend} />
    <button type="submit" disabled={!toSend}>Send</button>
  </form>

  {#if messages.isLoading}
    Loading...
  {:else if messages.error}
    <p>Failed to load: {messages.error.message}</p>
  {:else}
    <ul class:stale={messages.isStale}>
      {#each messages.data as message}
        <li>
          <strong>{message.author}</strong>: {message.body}
        </li>
      {/each}
    </ul>
  {/if}
</div>

<style>
  .stale { opacity: 0.6; }
</style>
```

--------------------------------

### Conditionally Skip Convex Queries

Source: https://github.com/get-convex/convex-svelte/blob/main/README.md

Skip a query by returning the string 'skip' from the arguments function. This is useful for queries dependent on conditions like authentication or user input. When skipped, `isLoading` is false, `error` is null, and `data` is undefined.

```svelte
<script lang="ts">
import { useQuery } from "convex-svelte";
import { api } from "../convex/_generated/api.js";

let auth = $state({ isAuthenticated: true });

const activeUserResponse = useQuery(
  api.users.queries.getActiveUser,
  () => (auth.isAuthenticated ? {} : 'skip')
);
</script>

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

--------------------------------

### Use a Convex Query in React

Source: https://github.com/get-convex/convex-svelte/blob/main/src/convex/README.md

Call a Convex query function from a React component using the `useQuery` hook. Pass arguments as the second parameter.

```typescript
const data = useQuery(api.functions.myQueryFunction, {
	first: 10,
	second: 'hello'
});
```

--------------------------------

### Define a Convex Query Function

Source: https://github.com/get-convex/convex-svelte/blob/main/src/convex/README.md

Define a query function with argument validators and implement database reads. Use `v` for argument validation.

```typescript
// functions.js
import { query } from './_generated/server';
import { v } from 'convex/values';

export const myQueryFunction = query({
	// Validators for arguments.
	args: {
		first: v.number(),
		second: v.string()
	},

	// Function implementation.
	handler: async (ctx, args) => {
		// Read the database as many times as you need here.
		// See https://docs.convex.dev/database/reading-data.
		const documents = await ctx.db.query('tablename').collect();

		// Arguments passed from the client are properties of the args object.
		console.log(args.first, args.second);

		// Write arbitrary JavaScript here: filter, aggregate, build derived data,
		// remove non-public properties, or create new objects.
		return documents;
	}
});
```

--------------------------------

### Use a Convex Mutation in React

Source: https://github.com/get-convex/convex-svelte/blob/main/src/convex/README.md

Call a Convex mutation function from a React component using the `useMutation` hook. Mutations can be fired and forgotten or their results can be awaited.

```typescript
const mutation = useMutation(api.functions.myMutationFunction);
function handleButtonPress() {
	// fire and forget, the most common way to use mutations
	mutation({ first: 'Hello!', second: 'me' });
	// OR
	// use the result once the mutation has completed
	mutation({ first: 'Hello!', second: 'me' }).then((result) => console.log(result));
}
```

--------------------------------

### Define a Convex Mutation Function

Source: https://github.com/get-convex/convex-svelte/blob/main/src/convex/README.md

Define a mutation function with argument validators for data manipulation. Mutations can also read from the database.

```typescript
// functions.js
import { mutation } from './_generated/server';
import { v } from 'convex/values';

export const myMutationFunction = mutation({
	// Validators for arguments.
	args: {
		first: v.string(),
		second: v.string()
	},

	// Function implementation.
	handler: async (ctx, args) => {
		// Insert or modify documents in the database here.
		// Mutations can also read from the database like queries.
		// See https://docs.convex.dev/database/writing-data.
		const message = { body: args.first, author: args.second };
		const id = await ctx.db.insert('messages', message);

		// Optionally, return a value from your mutation.
		return await ctx.db.get(id);
	}
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.