Svelte

## Add Hanko to Svelte Application

**Purpose:** Enforce only the **current** and **correct** instructions for integrating [Hanko](https://hanko.io/) passwordless authentication into a Svelte application.  
**Scope:** All AI-generated advice or code related to Hanko must follow these guardrails for Svelte with Vite and svelte-routing.

---

## **1. Official Hanko Integration Overview**

Use only the **current** approach from Hanko's documentation:

- **Install** `@teamhanko/hanko-elements@latest` and `svelte-routing` for navigation
- **Set up** Hanko Cloud project at [cloud.hanko.io](https://cloud.hanko.io/) with correct APP URL (likely http://localhost:5173 for development)
- **Configure** `VITE_HANKO_API_URL` environment variable in `.env` (with VITE_ prefix for Vite)
- **Create** HankoAuth and HankoProfile Svelte components with reactive variables
- **Use** svelte-routing for navigation between login and dashboard pages
- **Implement** logout functionality with proper navigation
- **Handle** session events with `on:onSessionCreated` in components
- **Register** Hanko web components using the register function in onMount
- **Manage** authentication state with Svelte stores if needed

---

## **2. CRITICAL INSTRUCTIONS FOR AI MODELS**

### **2.1 – ALWAYS DO THE FOLLOWING**

1. **Use VITE_ prefix** for environment variables in Vite-based Svelte apps
2. **Import from import.meta.env** for environment variables in Vite
3. **Use onMount lifecycle** for registering Hanko components in Svelte
4. **Handle events with on:eventName** syntax (e.g., `on:onSessionCreated`)
5. **Use navigate from svelte-routing** for programmatic navigation
6. **Register components** using `register()` from hanko-elements in onMount
7. **Create reactive variables** with `let` for component state
8. **Install svelte-routing** alongside hanko-elements for navigation
9. **Use Router, Route, and link components** from svelte-routing
10. **Handle authentication redirects** with navigate function

### **2.2 – NEVER DO THE FOLLOWING**

1. **Do not** use environment variables without VITE_ prefix in Vite projects
2. **Do not** forget to register Hanko components in onMount lifecycle
3. **Do not** use React-style event handlers (onClick instead of on:click)
4. **Do not** skip component registration with register() function
5. **Do not** use window.location for navigation (use navigate instead)
6. **Do not** forget error handling in register() and logout() calls
7. **Do not** mix up Svelte event syntax with other framework patterns
8. **Do not** skip installing svelte-routing for navigation

---

## **3. CORRECT IMPLEMENTATION PATTERNS**

### **Environment Setup**
```bash
npm install @teamhanko/hanko-elements svelte-routing

VITE_HANKO_API_URL=https://your-hanko-api-url.hanko.io

<script>
  import { onMount } from "svelte";
  import { navigate } from "svelte-routing";
  import { register } from "@teamhanko/hanko-elements";
  
  const hankoApi = import.meta.env.VITE_HANKO_API_URL;

  const redirectAfterLogin = () => {
    navigate("/dashboard");
  };

  onMount(async () => {
    register(hankoApi).catch((error) => {
      console.error(error);
    });
  });
</script>

<hanko-auth on:onSessionCreated={redirectAfterLogin} />

<script>
  import { onMount } from "svelte";
  import { register } from "@teamhanko/hanko-elements";
  
  const hankoApi = import.meta.env.VITE_HANKO_API_URL;

  onMount(async () => {
    register(hankoApi).catch((error) => {
      console.error(error);
    });
  });
</script>

<hanko-profile />

<script>
  import { Hanko } from "@teamhanko/hanko-elements";
  import { navigate } from "svelte-routing";
  
  const hankoApi = import.meta.env.VITE_HANKO_API_URL;
  const hanko = new Hanko(hankoApi);
  
  const logout = () => {
    hanko.logout().catch((error) => {
      console.error(error);
    });
    navigate("/");
  };
</script>

<button on:click={logout}>Logout</button>

<script>
  import { Router, Route } from "svelte-routing";
  import LoginPage from "./LoginPage.svelte";
  import DashboardPage from "./DashboardPage.svelte";
</script>

<Router>
  <Route path="/" component={LoginPage} />
  <Route path="/dashboard" component={DashboardPage} />
</Router>

<!-- LoginPage.svelte -->
<script>
  import HankoAuth from "./components/HankoAuth.svelte";
</script>

<div>
  <h1>Login</h1>
  <HankoAuth />
</div>

<!-- DashboardPage.svelte -->
<script>
  import HankoProfile from "./components/HankoProfile.svelte";
  import LogoutButton from "./components/LogoutButton.svelte";
</script>

<div>
  <h1>Dashboard</h1>
  <HankoProfile />
  <LogoutButton />
</div>

<!-- ❌ DO NOT use environment variables without VITE_ prefix -->
<script>
  const hankoApi = process.env.HANKO_API_URL; // Wrong for Vite
</script>

<!-- ❌ DO NOT use React-style event handlers -->
<hanko-auth onClick={redirectAfterLogin} /> <!-- Wrong syntax -->

<!-- ❌ DO NOT forget to register components -->
<script>
  // Missing register() call in onMount
</script>
<hanko-auth />

<!-- ❌ DO NOT use window.location for navigation -->
<script>
  const redirectAfterLogin = () => {
    window.location.href = "/dashboard"; // Use navigate instead
  };
</script>

<!-- ❌ DO NOT skip svelte-routing installation -->
// Missing Router, Route components for navigation

<!-- ❌ DO NOT forget error handling -->
<script>
  onMount(async () => {
    register(hankoApi); // Missing .catch() for error handling
  });
</script>