Better Auth UI for Svelte 5

Common errors

• Failed to resolve import "better-auth-ui-svelte/css" from "<your-css-file>"

  cause Incorrect path or missing CSS file for TailwindCSS v4 import.
  fix Ensure your `better-auth-ui-svelte` package is correctly installed and that the `@import 'better-auth-ui-svelte/css';` statement is in a CSS file processed by TailwindCSS.

• Error: Hydration completed but contains mismatches.

  cause Client-side rendering output does not match server-side rendering output, often due to dynamic content or environmental differences during SSR.
  fix Check for components that render differently based on client-side state or environment variables. Ensure consistent configuration between SSR and CSR, and consider using `onMount` for client-only rendering logic for non-critical elements.

• Error: hooks called inside $derived

  cause Svelte 5 runes are misused, specifically calling reactive hooks (like those for data fetching or effects) within a `$derived` block.
  fix Move any side-effecting or hook-based logic out of `$derived` computations. `$derived` should only compute a value based on other reactive states, not perform actions. Use `$effect` for side effects.

• Infinite reactive loop detected in Svelte 5 form or effect.

  cause A state update within an `$effect` or form handler is causing the effect or form to re-evaluate and update the state again, leading to an endless cycle.
  fix Wrap state-setting calls within `$effect` blocks (e.g., `form.setFieldValue()`) in `untrack(() => { ... })` to prevent the update from re-triggering the effect itself. Carefully manage dependencies and side effects in Svelte 5 runes.

Warnings

• gotcha This library is in early stage development and has not been battle-tested in production environments. Issues may arise before v1.0 stable. Use at your own risk.
  Fix: Thoroughly test components in your specific application context and be prepared to address potential bugs or API changes. Monitor the GitHub repository for updates and contribute feedback.
• breaking For TailwindCSS v4, the CSS import mechanism changed from content configuration to a direct `@import` statement in your global CSS. Older content configuration for v3 is deprecated.
  Fix: For TailwindCSS v4, add `@import 'better-auth-ui-svelte/css';` to your global CSS file (e.g., `app.css`). Remove the `content: ['./node_modules/better-auth-ui-svelte/dist/**/*.{js,svelte}']` entry from your `tailwind.config.js` if upgrading.
• gotcha The Svelte port may evolve independently and diverge from the original React library's API and features over time, prioritizing the needs of the Svelte ecosystem and maintainer's projects.
  Fix: Consult the Svelte port's specific documentation and changelog, rather than relying solely on the React version's documentation, to stay informed about potential differences.
• gotcha Changes in Svelte 5's reactivity model, specifically the use of `$derived` and `$effect` runes, can lead to infinite reactive loops or delayed data loading if not handled carefully, particularly with form fields or data fetching.
  Fix: Ensure that `form.setFieldValue()` calls or similar state updates within `$effect` blocks are wrapped in `untrack()` to prevent re-triggering the effect unnecessarily. Verify that hooks are not called inside `$derived` computations, which can cause unexpected behavior.
• breaking The `UserButton` component's structure was enhanced with a `menuItems` snippet prop, allowing callers to inject custom `DropdownMenu` items.
  Fix: If you had custom logic for extending the `UserButton`'s dropdown, refactor to use the new `menuItems` snippet prop. For example: `<UserButton>{#snippet menuItems()}...your custom items...{/snippet}</UserButton>`.

Install

• npm install better-auth-ui-svelte npm
• yarn add better-auth-ui-svelte yarn
• pnpm add better-auth-ui-svelte pnpm

Imports

• AuthLayout
  wrong:

  const AuthLayout = require('better-auth-ui-svelte').AuthLayout;

  correct:

  import { AuthLayout } from 'better-auth-ui-svelte';

  The library primarily uses named exports. Direct CommonJS `require` for specific components is generally not recommended in modern SvelteKit projects which favor ESM.
• UserButton
  wrong:

  import UserButton from 'better-auth-ui-svelte/UserButton.svelte';

  correct:

  import { UserButton } from 'better-auth-ui-svelte';

  Components are re-exported from the main entry point; importing directly from '.svelte' files is not the intended public API.
• nlLocalization
  wrong:

  import { nlLocalization } from 'better-auth-ui-svelte/localization';

  correct:

  import { nlLocalization } from 'better-auth-ui-svelte';

  Localization objects are named exports from the root, not separate subpaths, since v0.8.0.

Quickstart

This quickstart demonstrates setting up the Better Auth client, integrating Tailwind CSS, and using fundamental UI components like `AuthLayout`, `UserButton`, and `ChangeEmailCard` in a SvelteKit project.

import { SvelteKitAuth } from 'better-auth/client';
import { AuthLayout, UserButton, ChangeEmailCard } from 'better-auth-ui-svelte';

// In src/lib/auth.ts (or similar)
export const auth = new SvelteKitAuth({
  apiEndpoint: '/api/auth'
});

// In src/routes/+layout.svelte
<script lang="ts">
  import { onMount } from 'svelte';
  import '../app.css'; // Your global CSS with Tailwind imports
  import { auth } from '$lib/auth';

  onMount(() => {
    // Initialize auth client if needed, or ensure stores are reactive
  });
</script>

<AuthLayout>
  <UserButton />
</AuthLayout>

<!-- In src/routes/settings/email/+page.svelte -->
<script lang="ts">
  import { auth } from '$lib/auth';
</script>

<ChangeEmailCard auth={auth} />