feat(examples): add svelte example

deploy/docker-compose/todo-svelte.yaml

@@ -0,0 +1,15 @@
+services:
+  todo-backend:
+    build: ../../examples/express
+    ports:
+      - "8002:8002"
+    environment:
+      - HANKO_API_URL=http://hanko:8000
+    networks:
+      - intranet
+  todo-frontend:
+    build: ../../examples/svelte
+    ports:
+      - "8888:8888"
+    networks:
+      - intranet

docs/docs/guides/svelte.mdx

@@ -0,0 +1,110 @@
+---
+title: Svelte + Hanko
+sidebar_label: Svelte
+keywords:
+  - hanko
+  - svelte
+  - integration
+sidebar_custom_props:
+  docCardIconName: svelte
+---
+
+# Svelte
+
+In this guide you will learn how to add authentication to your Svelte application using the Hanko custom element.
+
+## Install dependencies
+Install the `@teamhanko/hanko-elements` package:
+
+```shell npm2yarn
+npm install @teamhanko/hanko-elements
+```
+
+## Import & use custom element
+
+Import the `register` function from `@teamhanko/hanko-elements/hanko-auth` in the component where you want to use the
+Hanko custom element. Call `register` to register the `<hanko-auth>` element with the browser's
+[`CustomElementRegistry`](https://developer.mozilla.org/de/docs/Web/API/CustomElementRegistry).
+Then use the `<hanko-auth>` element in your component template.
+
+:::info
+
+When adding the `<hanko-auth>` element to your JSX you must provide the URL of the Hanko API via the `api`
+attribute. If you are using [Hanko Cloud](https://cloud.hanko.io), you can find the API URL on your project dashboard.
+If you are self-hosting you need to provide the URL of your running Hanko backend.
+
+:::
+
+```js title="Login.svelte" showLineNumbers
+<script>
+  import { onMount } from "svelte";
+  import { register } from '@teamhanko/hanko-elements/hanko-auth';
+
+  const api = import.meta.env.VITE_HANKO_API;
+  const lang = import.meta.env.VITE_HANKO_LANG;
+
+  onMount(async () => {
+    // register the component
+    // see: https://github.com/teamhanko/hanko/blob/main/frontend/elements/README.md#script
+    register({ shadow: true }).catch((e) => {
+      console.error(e)
+    });
+  });
+</script>
+
+<div class="content">
+  <hanko-auth {api} {lang}/>
+</div>
+```
+
+## Defining login callbacks
+
+The `<hanko-auth>` element dispatches a custom `hankoAuthSuccess` event on successful login. React to this
+event in order to, for example, redirect your users to protected pages in your application.
+
+To do so, apply an event listener with an appropriate redirect callback:
+
+```js {2-3,9-14,23,26-28,32} title="Login.svelte" showLineNumbers
+<script>
+  import { onDestroy, onMount } from "svelte";
+  import { useNavigate } from "svelte-navigator";
+  import { register } from '@teamhanko/hanko-elements/hanko-auth';
+
+  const api = import.meta.env.VITE_HANKO_API;
+  const lang = import.meta.env.VITE_HANKO_LANG;
+
+  const navigate = useNavigate();
+  let element;
+
+  const redirectToTodos = () => {
+    navigate('/todo');
+  };
+
+  onMount(async () => {
+    // register the component
+    // see: https://github.com/teamhanko/hanko/blob/main/frontend/elements/README.md#script
+    register({ shadow: true }).catch((e) => {
+      console.error(e)
+    });
+
+    element.addEventListener('hankoAuthSuccess', redirectToTodos);
+  });
+
+  onDestroy(() => {
+    element.removeEventListener('hankoAuthSuccess', redirectToTodos);
+  });
+</script>
+
+<div class="content">
+  <hanko-auth bind:this={element} {api} {lang}/>
+</div>
+```
+
+## UI customization
+
+The styles of the `hanko-auth` element can be customized using CSS variables and parts. See our guide
+on customization [here](https://github.com/teamhanko/hanko/tree/main/frontend/elements#ui-customization).
+
+## Backend request authentication
+
+If you want to authenticate requests in your own backend, please view our [backend guide](/guides/backend).

docs/sidebars.js

@@ -29,7 +29,7 @@ const sidebars = {
         slug: '/guides/frontend',
         keywords: ['guides']
       },
-      items: ['guides/angular', "guides/react", "guides/next", "guides/vue"]
+      items: ['guides/angular', "guides/next", "guides/react", "guides/svelte", "guides/vue"]
     },
     'guides/backend'
   ],

docs/src/theme/DocCard/styles.module.css

@@ -35,3 +35,8 @@
   display: flex;
   align-items: center;
 }
+
+.cardIcon img{
+  max-width: 100%;
+  max-height: 100%;
+}

examples/README.md

@@ -13,6 +13,7 @@ It contains:
   - [Next.js](nextjs)
   - [React](react)
   - [Vue](vue)
+  - [Svelte](svelte)
 
 ## How to run
 ### Manual
@@ -38,3 +39,7 @@ docker compose -f deploy/docker-compose/base.yaml -f deploy/docker-compose/todo-
 ```
 docker compose -f deploy/docker-compose/base.yaml -f deploy/docker-compose/todo-vue.yaml -p "hanko-todo-vue" up --build
 ```
+#### Svelte
+```
+docker compose -f deploy/docker-compose/base.yaml -f deploy/docker-compose/todo-svelte.yaml -p "hanko-todo-svelte" up --build
+```

examples/svelte/.dockerignore

@@ -0,0 +1 @@
+node_modules

examples/svelte/.env

@@ -0,0 +1,2 @@
+VITE_HANKO_API=http://localhost:8000
+VITE_TODO_API=http://localhost:8002

examples/svelte/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/svelte/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["svelte.svelte-vscode"]
+}

examples/svelte/Dockerfile

@@ -0,0 +1,19 @@
+# pull official base image
+FROM node:16-alpine
+
+# set working directory
+WORKDIR /app
+
+# add `/app/node_modules/.bin` to $PATH
+ENV PATH /app/node_modules/.bin:$PATH
+
+# install app dependencies
+COPY package.json ./
+COPY package-lock.json ./
+RUN npm install
+
+# add app
+COPY . ./
+
+# start app
+CMD ["npm", "start"]

examples/svelte/README.md

@@ -0,0 +1,19 @@
+# Hanko Svelte example
+
+## Starting the app
+
+### Prerequisites
+
+- a running Hanko API (see the instructions on how to run the API [in Docker](../backend/README.md#Docker) or [from Source](../backend/README.md#from-source))
+- a running express backend (see the [README](../express) for the express backend)
+
+### Set up environment variables
+
+In the `.env` file set up the correct environment variables:
+
+- `VITE_HANKO_API`: this is the URL of the Hanko API (default: `http://localhost:8000`, can be customized using the `server.public.address` option in the [configuration file](../../backend/docs/Config.md))
+- `VITE_TODO_API`: this is the URL of the [express](../express) backend (default: `http://localhost:8002`)
+
+### Run development server
+
+Run `npm install` to install dependencies, then run `npm run start` for a development server. Navigate to `http://localhost:8888/`. The application will automatically reload if you change any of the source files.

examples/svelte/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/favicon.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hanko Svelte Example</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>