docs: adjust README files

examples/README.md

@@ -0,0 +1,21 @@
+# Hanko Examples
+
+This directory contains examples that show
+
+- integration of web component(s) provided through the`@teamhanko/hanko-elements` package (see [elements](../elements)).
+- how to validate JSON Web Tokens (JWT) issued by the Hanko [API](../backend) in a custom backend
+
+It contains:
+
+- an example [express](express) backend - this is a simple version of the well-known todo app
+- example frontend applications using the following frameworks:
+  - [Angular](angular)
+  - [Next.js](nextjs)
+  - [React](react)
+  - [Vue](vue)
+
+## How to run
+
+1. Start the 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))
+2. Start the express backend (see the [README](express) for the express backend)
+3. Start one of the frontend applications (see the README for the app of your choice)

examples/angular/README.md

@@ -1,27 +1,21 @@
-# Angular
+# Hanko Angular example
 
 This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.3.
 
-## Development server
+## Starting the app
 
-Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+### Prerequisites
 
-## Code scaffolding
+- 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)
 
-Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+### Set up environment variables
 
-## Build
+In the `src/environments/environment.ts` file set up the correct environment variables:
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+- `hankoApi`: 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))
+- `todoApi`: this is the URL of the [express](../express) backend (default: `http://localhost:8002`)
 
-## Running unit tests
+### Run development server
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+Run `npm run start` for a development server. Navigate to `http://localhost:3000/`. The application will automatically reload if you change any of the source files.
-
-## Running end-to-end tests
-
-Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
-
-## Further help
-
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

examples/angular/src/app/login/login.component.html

@@ -2,6 +2,5 @@
   <hanko-auth
     (hankoAuthSuccess)="redirectToTodo()"
     [api]="api"
-    [lang]="lang"
   ></hanko-auth>
 </div>

examples/angular/src/app/login/login.component.ts

@@ -10,7 +10,6 @@ import { register } from '@teamhanko/hanko-elements/hanko-auth';
 })
 export class LoginComponent {
   api = environment.hankoApi;
-  lang = environment.hankoElementLang;
 
   constructor(private router: Router) {
     register({ shadow: true }).catch((e) => console.error(e));

examples/angular/src/environments/environment.ts

@@ -5,7 +5,6 @@
 export const environment = {
   production: false,
   hankoApi: 'http://localhost:8000',
-  hankoElementLang: 'en',
   todoApi: 'http://localhost:8002',
 };
 

examples/nextjs/.env

@@ -1,3 +1,2 @@
 NEXT_PUBLIC_HANKO_API=http://localhost:8000
-NEXT_PUBLIC_BACKEND=http://localhost:8002
+NEXT_PUBLIC_TODO_API=http://localhost:8002
-NEXT_PUBLIC_HANKO_LANG=en

examples/nextjs/README.md

@@ -1,34 +1,21 @@
+# Hanko Next.js example
+
 This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
 
-## Getting Started
+## Starting the app
 
-First, run the development server:
+### Prerequisites
 
-```bash
+- 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))
-npm run dev
+- a running express backend (see the [README](../express) for the express backend)
-# or
-yarn dev
-```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### Set up environment variables
 
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
+In the `.env` file set up the correct environment variables:
 
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
+- `NEXT_PUBLIC_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))
+- `NEXT_PUBLIC_TODO_API`: this is the URL of the [express](../express) backend (default: `http://localhost:8002`)
 
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+### Run development server
 
-## Learn More
+Run `npm run start` for a development server. Navigate to `http://localhost:3000/`. The application will automatically reload if you change any of the source files.
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.

examples/nextjs/components/HankoAuth.tsx

@@ -3,7 +3,6 @@ import { useCallback, useEffect } from "react";
 import { useRouter } from "next/router";
 
 const api = process.env.NEXT_PUBLIC_HANKO_API!;
-const lang = process.env.NEXT_PUBLIC_HANKO_LANG;
 
 function HankoAuth() {
   const router = useRouter();
@@ -22,7 +21,7 @@ function HankoAuth() {
       document.removeEventListener("hankoAuthSuccess", redirectToTodos);
   }, [redirectToTodos]);
 
-  return <hanko-auth api={api} lang={lang} />;
+  return <hanko-auth api={api} />;
 }
 
 export default HankoAuth;

examples/nextjs/package.json

@@ -3,10 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "start": "next dev"
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint"
   },
   "dependencies": {
     "@passageidentity/passage-elements": "^0.1.0-beta.54",

examples/nextjs/pages/todo.tsx

@@ -4,7 +4,7 @@ import { useRouter } from "next/router";
 import { TodoClient, Todos } from "../util/TodoClient";
 import styles from "../styles/Todo.module.css";
 
-const api = process.env.NEXT_PUBLIC_BACKEND!;
+const api = process.env.NEXT_PUBLIC_TODO_API!;
 
 const Todo: NextPage = () => {
   const client = useMemo(() => new TodoClient(api), []);

examples/react/.env

@@ -1,3 +1,2 @@
 REACT_APP_HANKO_API=http://localhost:8000
-REACT_APP_BACKEND=http://localhost:8002
+REACT_APP_TODO_API=http://localhost:8002
-REACT_APP_HANKO_LANG=en

examples/react/README.md

@@ -1,46 +1,21 @@
-# Getting Started with Create React App
+# Hanko React example
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+This is a [React](https://reactjs.org/) project bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
 
-## Available Scripts
+## Starting the app
 
-In the project directory, you can run:
+### Prerequisites
 
-### `npm start`
+- 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)
 
-Runs the app in the development mode.\
+### Set up environment variables
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
 
-The page will reload if you make edits.\
+In the `.env` file set up the correct environment variables:
-You will also see any lint errors in the console.
 
-### `npm test`
+- `NEXT_PUBLIC_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))
+- `NEXT_PUBLIC_TODO_API`: this is the URL of the [express](../express) backend (default: `http://localhost:8002`)
 
-Launches the test runner in the interactive watch mode.\
+### Run development server
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
 
-### `npm run build`
+Run `npm run start` for a development server. Navigate to `http://localhost:3000/`. The application will automatically reload if you change any of the source files.
-
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
-
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
-
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
-
-### `npm run eject`
-
-**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
-
-If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
-
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
-
-You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
-
-## Learn More
-
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
-
-To learn React, check out the [React documentation](https://reactjs.org/).

examples/react/package-lock.json

@@ -8,7 +8,7 @@
       "name": "example-react",
       "version": "0.1.0",
       "dependencies": {
-        "@teamhanko/hanko-elements": "^0.0.8-alpha.18",
+        "@teamhanko/hanko-elements": "^0.0.8-alpha.22",
         "@teamhanko/hanko-frontend-sdk": "^0.0.2-alpha",
         "@types/react": "^18.0.19",
         "@types/react-dom": "^18.0.6",
@@ -3396,7 +3396,7 @@
     },
     "node_modules/@teamhanko/hanko-elements": {
       "version": "0.0.8-alpha.22",
-      "resolved": "http://0.0.0.0:4873/@teamhanko%2fhanko-elements/-/hanko-elements-0.0.8-alpha.22.tgz",
+      "resolved": "http://localhost:4873/@teamhanko%2fhanko-elements/-/hanko-elements-0.0.8-alpha.22.tgz",
       "integrity": "sha512-BIrYJjVHJ8dAGHGDSqpnqKyNlAVkJJuljlPSdEO6sVjDy6L/wB6fSSviqtPDLyb8uh/wa0PaVucMRvVyGNbtwA==",
       "license": "MIT",
       "dependencies": {
@@ -18599,7 +18599,7 @@
     },
     "@teamhanko/hanko-elements": {
       "version": "0.0.8-alpha.22",
-      "resolved": "http://0.0.0.0:4873/@teamhanko%2fhanko-elements/-/hanko-elements-0.0.8-alpha.22.tgz",
+      "resolved": "http://localhost:4873/@teamhanko%2fhanko-elements/-/hanko-elements-0.0.8-alpha.22.tgz",
       "integrity": "sha512-BIrYJjVHJ8dAGHGDSqpnqKyNlAVkJJuljlPSdEO6sVjDy6L/wB6fSSviqtPDLyb8uh/wa0PaVucMRvVyGNbtwA==",
       "requires": {
         "@denysvuika/preact-translate": "^0.3.0",

examples/react/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "dependencies": {
-    "@teamhanko/hanko-elements": "^0.0.8-alpha.18",
+    "@teamhanko/hanko-elements": "^0.0.8-alpha.22",
     "@teamhanko/hanko-frontend-sdk": "^0.0.2-alpha",
     "@types/react": "^18.0.19",
     "@types/react-dom": "^18.0.6",
@@ -14,10 +14,7 @@
     "typescript": "^4.8.3"
   },
   "scripts": {
-    "start": "react-scripts start",
+    "start": "react-scripts start"
-    "build": "react-scripts build",
-    "test": "react-scripts test",
-    "eject": "react-scripts eject"
   },
   "eslintConfig": {
     "extends": [

examples/react/src/HankoAuth.tsx

@@ -4,7 +4,6 @@ import { register } from "@teamhanko/hanko-elements/hanko-auth";
 import styles from "./Todo.module.css";
 
 const api = process.env.REACT_APP_HANKO_API!;
-const lang = process.env.REACT_APP_HANKO_LANG;
 
 function HankoAuth() {
   const navigate = useNavigate();
@@ -14,7 +13,7 @@ function HankoAuth() {
   }, [navigate]);
 
   useEffect(() => {
-    register({ shadow: true });
+    register({ shadow: true }).catch((e) => console.error(e));
     document.addEventListener("hankoAuthSuccess", redirectToTodos);
     return () =>
       document?.removeEventListener("hankoAuthSuccess", redirectToTodos);
@@ -22,7 +21,7 @@ function HankoAuth() {
 
   return (
     <div className={styles.content}>
-      <hanko-auth api={api} lang={lang} />
+      <hanko-auth api={api} />
     </div>
   );
 }

examples/react/src/Todo.tsx

@@ -3,7 +3,7 @@ import { useNavigate } from "react-router-dom";
 import { TodoClient, Todos } from "./TodoClient";
 import styles from "./Todo.module.css";
 
-const api = process.env.REACT_APP_BACKEND!;
+const api = process.env.REACT_APP_TODO_API!;
 
 function Todo() {
   const navigate = useNavigate();

examples/vue/.env

@@ -1,3 +1,2 @@
 VITE_HANKO_API=http://localhost:8000
-VITE_HANKO_LANG=en
 VITE_TODO_API=http://localhost:8002

examples/vue/README.md

@@ -1,46 +1,21 @@
-# vue
+# Hanko React example
 
-This template should help get you started developing with Vue 3 in Vite.
+This is a [Vue](https://vuejs.org/) project bootstrapped with Vue version 3.2.39.
 
-## Recommended IDE Setup
+## Starting the app
 
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+### Prerequisites
 
-## Type Support for `.vue` Imports in TS
+- 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)
 
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
+### Set up environment variables
 
-If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
+In the `.env` file set up the correct environment variables:
 
-1. Disable the built-in TypeScript Extension
+- `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))
-    1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette
+- `VITE_TODO_API`: this is the URL of the [express](../express) backend (default: `http://localhost:8002`)
-    2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
-2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
 
-## Customize configuration
+### Run development server
 
-See [Vite Configuration Reference](https://vitejs.dev/config/).
+Run `npm run start` for a development server. Navigate to `http://localhost:3000/`. The application will automatically reload if you change any of the source files.
-
-## Project Setup
-
-```sh
-npm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
-npm run dev
-```
-
-### Type-Check, Compile and Minify for Production
-
-```sh
-npm run build
-```
-
-### Lint with [ESLint](https://eslint.org/)
-
-```sh
-npm run lint
-```

examples/vue/package.json

@@ -2,12 +2,7 @@
   "name": "vue",
   "version": "0.0.0",
   "scripts": {
-    "dev": "vite --port 3000",
+    "start": "vite --port 3000"
-    "build": "run-p type-check build-only",
-    "preview": "vite preview --port 3000",
-    "build-only": "vite build",
-    "type-check": "vue-tsc --noEmit",
-    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
   },
   "dependencies": {
     "@teamhanko/hanko-elements": "^0.0.8-alpha.22",

examples/vue/src/components/HankoAuth.vue

@@ -8,7 +8,6 @@ onMounted(() => {
 });
 
 const api = import.meta.env.VITE_HANKO_API;
-const lang = import.meta.env.VITE_HANKO_LANG;
 
 const router = useRouter();
 
@@ -18,5 +17,5 @@ const redirectToTodo = () => {
 </script>
 
 <template>
-  <hanko-auth @hankoAuthSuccess="redirectToTodo" :api="api" :lang="lang" />
+  <hanko-auth @hankoAuthSuccess="redirectToTodo" :api="api" />
 </template>