Svelte Guidelines

Mutation Pattern Preference

In Svelte Files (.svelte)

Always prefer createMutation from TanStack Query for mutations. This provides:

• Loading states (isPending)
• Error states (isError)
• Success states (isSuccess)
• Better UX with automatic state management

The Preferred Pattern

Pass onSuccess and onError as the second argument to .mutate() to get maximum context:

<script lang="ts">
	import { createMutation } from '@tanstack/svelte-query';
	import * as rpc from '$lib/query';

	// Create mutation with just .options (no parentheses!)
	const deleteSessionMutation = createMutation(
		rpc.sessions.deleteSession.options,
	);

	// Local state that we can access in callbacks
	let isDialogOpen = $state(false);
</script>

<Button
	onclick={() => {
		// Pass callbacks as second argument to .mutate()
		deleteSessionMutation.mutate(
			{ sessionId },
			{
				onSuccess: () => {
					// Access local state and context
					isDialogOpen = false;
					toast.success('Session deleted');
					goto('/sessions');
				},
				onError: (error) => {
					toast.error(error.title, { description: error.description });
				},
			},
		);
	}}
	disabled={deleteSessionMutation.isPending}
>
	{#if deleteSessionMutation.isPending}
		Deleting...
	{:else}
		Delete
	{/if}
</Button>

Why This Pattern?

• More context: Access to local variables and state at the call site
• Better organization: Success/error handling is co-located with the action
• Flexibility: Different calls can have different success/error behaviors

In TypeScript Files (.ts)

Always use .execute() since createMutation requires component context:

// In a .ts file (e.g., load function, utility)
const result = await rpc.sessions.createSession.execute({
	body: { title: 'New Session' },
});

const { data, error } = result;
if (error) {
	// Handle error
} else if (data) {
	// Handle success
}

Exception: When to Use .execute() in Svelte Files

Only use .execute() in Svelte files when:

1. You don't need loading states
2. You're performing a one-off operation
3. You need fine-grained control over async flow

Inline Simple Handler Functions

When a handler function only calls .mutate(), inline it directly:

<!-- Avoid: Unnecessary wrapper function -->
<script>
	function handleShare() {
		shareMutation.mutate({ id });
	}
</script>

<!-- Good: Inline simple handlers -->
<Button onclick={() => shareMutation.mutate({ id })}>Share</Button>
<Button onclick={handleShare}>Share</Button>

Styling

For general CSS and Tailwind guidelines, see the styling skill.

shadcn-svelte Best Practices

Component Organization

• Use the CLI: bunx shadcn-svelte@latest add [component]
• Each component in its own folder under $lib/components/ui/ with an index.ts export
• Follow kebab-case for folder names (e.g., dialog/, toggle-group/)
• Group related sub-components in the same folder
• When using $state, $derived, or functions only referenced once in markup, inline them directly

Import Patterns

Namespace imports (preferred for multi-part components):

import * as Dialog from '$lib/components/ui/dialog';
import * as ToggleGroup from '$lib/components/ui/toggle-group';

Named imports (for single components):

import { Button } from '$lib/components/ui/button';
import { Input } from '$lib/components/ui/input';

Lucide icons (always use individual imports from @lucide/svelte):

// Good: Individual icon imports
import Database from '@lucide/svelte/icons/database';
import MinusIcon from '@lucide/svelte/icons/minus';
import MoreVerticalIcon from '@lucide/svelte/icons/more-vertical';

// Bad: Don't import multiple icons from lucide-svelte
import { Database, MinusIcon, MoreVerticalIcon } from 'lucide-svelte';

The path uses kebab-case (e.g., more-vertical, minimize-2), and you can name the import whatever you want (typically PascalCase with optional Icon suffix).

Styling and Customization

• Always use the cn() utility from $lib/utils for combining Tailwind classes
• Modify component code directly rather than overriding styles with complex CSS
• Use tailwind-variants for component variant systems
• Follow the background/foreground convention for colors
• Leverage CSS variables for theme consistency

Component Usage Patterns

Use proper component composition following shadcn-svelte patterns:

<Dialog.Root bind:open={isOpen}>
	<Dialog.Trigger>
		<Button>Open</Button>
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Title>Title</Dialog.Title>
		</Dialog.Header>
	</Dialog.Content>
</Dialog.Root>

Custom Components

• When extending shadcn components, create wrapper components that maintain the design system
• Add JSDoc comments for complex component props
• Ensure custom components follow the same organizational patterns
• Consider semantic appropriateness (e.g., use section headers instead of cards for page sections)

Self-Contained Component Pattern

Prefer Component Composition Over Parent State Management

When building interactive components (especially with dialogs/modals), create self-contained components rather than managing state at the parent level.

The Anti-Pattern (Parent State Management)

<!-- Parent component -->
<script>
	let deletingItem = $state(null);

	function handleDelete(item) {
		// delete logic
		deletingItem = null;
	}
</script>

{#each items as item}
	<Button onclick={() => (deletingItem = item)}>Delete</Button>
{/each}

<AlertDialog open={!!deletingItem}>
	<!-- Single dialog for all items -->
</AlertDialog>

The Pattern (Self-Contained Components)

<!-- DeleteItemButton.svelte -->
<script>
	let { item } = $props();
	let open = $state(false);

	function handleDelete() {
		// delete logic directly in component
	}
</script>

<AlertDialog.Root bind:open>
	<AlertDialog.Trigger>
		<Button>Delete</Button>
	</AlertDialog.Trigger>
	<AlertDialog.Content>
		<!-- Dialog content -->
	</AlertDialog.Content>
</AlertDialog.Root>

<!-- Parent component -->
{#each items as item}
	<DeleteItemButton {item} />
{/each}

Why This Pattern Works

• No parent state pollution: Parent doesn't need to track which item is being deleted
• Better encapsulation: All delete logic lives in one place
• Simpler mental model: Each row has its own delete button with its own dialog
• No callbacks needed: Component handles everything internally
• Scales better: Adding new actions doesn't complicate the parent

When to Apply This Pattern

• Action buttons in table rows (delete, edit, etc.)
• Confirmation dialogs for list items
• Any repeating UI element that needs modal interactions
• When you find yourself passing callbacks just to update parent state

The key insight: It's perfectly fine to instantiate multiple dialogs (one per row) rather than managing a single shared dialog with complex state. Modern frameworks handle this efficiently, and the code clarity is worth it.