Svelte Guidelines $derived Value Mapping: Use satisfies Record , Not Ternaries When a $derived expression maps a finite union to output values, use a satisfies Record lookup. Never use nested ternaries. Never use $derived.by() with a switch just to map values.
Why
satisfies Record
wins:
Compile-time exhaustiveness: add a value to the union and TypeScript errors on the missing key. Nested ternaries silently fall through.
It's a data declaration, not control flow. The mapping is immediately visible.
$derived()
stays a single expression — no need for
$derived.by()
.
Reserve
$derived.by()
for multi-statement logic where you genuinely need a function body. For value lookups, keep it as
$derived()
with a record.
as const
is unnecessary when using
satisfies
.
satisfies Record
- <Button
- onclick={() => {
- // Pass callbacks as second argument to .mutate()
- deleteSession.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={deleteSession.isPending}
- >
- {#if deleteSession.isPending}
- Deleting...
- {:else}
- Delete
- {/if}
- 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: You don't need loading states You're performing a one-off operation You need fine-grained control over async flow No handle* Functions - Always Inline Never create functions prefixed with handle in the script tag. If the function is used only once and the logic isn't deeply nested, inline it directly in the template:
/items/${item.id})} />
This keeps related logic co-located with the UI element that triggers it, making the code easier to follow.
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:
Children Prop Never Needs Type Annotation The children prop is implicitly typed in Svelte. Never annotate it:
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)
{#each items as item}
{/each}
The Pattern (Self-Contained Components)
- {#each items as 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.