​
Create a Nuxt application

Run the following command to create a new Nuxt application:

npm create nuxt project-name

​
Install @nuxtjs/hanko

Once you’ve initialized your Nuxt app, installing @nuxtjs/hanko module provides you with access to prebuilt components: hanko-auth, hanko-events and hanko-profile

cd project-name
npm install -D @nuxtjs/hanko

​
Setup your Hanko project

Go to the Hanko console and create a project for this application.

During creation make sure to input the URL you will be developing on as the APP URL.
(Most likely http://localhost:3000/)

​
Add the Hanko API URL

Retrieve the API URL from the Hanko console and place it in your .env file.

.env
NUXT_PUBLIC_HANKO_API_URL=https://f4****-4802-49ad-8e0b-3d3****ab32.hanko.io

If you are self-hosting you need to provide the URL of your running Hanko backend.

​
Configure Nuxt module

Add the @nuxtjs/hanko module to the modules section of your nuxt.config.ts file.

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@nuxtjs/hanko"],
  hanko: {
    apiURL: process.env.NUXT_PUBLIC_HANKO_API_URL,
    cookieName: 'hanko',
    redirects:{
      login: '/',//Path to redirect to when unauthenticated / logged out
      success: '/dashboard',//Path to redirect to once logged in
    }
  },
})

While the module comes pre-configured with the options for most common use cases, you have the flexibility to override them by adding a hanko section to your nuxt.config.ts file. For all overrides please refer to module’s repository.

Using Hanko Components

You can now use the components anywhere in your app (<hanko-auth>, <hanko-events>, <hanko-profile>). These will render only on client-side and all the props you can pass are strongly typed.

If you prefer not to auto-register these components, especially if you plan to use Hanko exclusively on the server side or wish to handle component registration programmatically, you can disable this feature. To do so, set the registerComponents option to false in your nuxt.config.ts file:

nuxt.config.ts
hanko: {
  registerComponents: false;
}

​
Setup Nuxt pages

Lets add the NuxtPage component to app.vue to use the Nuxt Page Router.

app.vue
<template>
  <div>
    <NuxtPage />
  </div>
</template>

After that lets create a folder called /pages and in there we will create index.vue and dashboard.vue.

​
Add <hanko-auth> component

The <hanko-auth> web component adds a login interface to your app. By default no action is taken after a successful login. But when you add the hanko-logged-out middleware to the login page it will automatically redirect the user to the page they were on before logging in, or to the optional redirects.success value in the module config.

Lets try this out in the index.vue page.

pages/index.vue
<script setup lang="ts">
definePageMeta({
  middleware: ['hanko-logged-out']
})
</script>
<template>
  <hanko-auth />
</template>

Alternatively you can redirect the user to a page of your choice by adding the <hanko-events> component to your page and listening for the onSessionCreated event.

pages/index.vue
<script setup lang="ts">
function afterLogin() {
 navigateTo("/user");
}
</script>
<template>
  <hanko-auth />
  <hanko-events @onSessionCreated="afterLogin()" />
</template>

​
Define event callbacks

To subscribe to events emitted by Hanko, you can add the <hanko-events> component to your page and listen for the events you are interested in.

pages/index.vue
<script setup lang="ts">
function updateSession() {
 // do something
}
</script>
<template>
  <hanko-events @onSessionCreated="updateSession()" />
</template>

By now, your sign-up and sign-in features should be working. You should see an interface similar to this 👇

​
Add <hanko-profile>

The <hanko-profile> component provides an interface, where users can manage their email addresses and passkeys.

Lets try this out in the dashboard.vue page.

pages/dashboard.vue
<template>
  <hanko-profile />
</template>

It should look like this 👇

​
Implement logout functionality

To log users out, use the @nuxtjs/hanko module’s built-in composable useHanko and call the logout method.

pages/dashboard.vue
<script setup lang="ts">
const hanko = useHanko()
  function logout() {
    hanko?.logout();
  }
  definePageMeta({
    middleware: ["hanko-logged-in"],
  });
</script>
<template>
  <hanko-profile />
  <button @click="logout">
      Log me out
  </button>
</template>

useHanko() composable

The useHanko composable provides access to the Hanko SDK which in turn allows access to the Hanko API, e.g. for accessing the current user info. The composable is auto-imported across the app and can simply be used with useHanko() anywhere in your code.

​
Customize component styles

You can customize the appearance of hanko-auth and hanko-profile components using CSS variables and parts. Refer to our customization guide. The styles can be scoped to the login/profile page to ensure they dont affect other parts to the app.

​
Securing routes with Middleware

Use the hanko-logged-in middleware to secure any route and force unauthenticated users to redirect back to the login redirect we set in the nuxt.config.ts.

<script setup lang="ts">
  definePageMeta({
    middleware: ["hanko-logged-in"],
  });
</script>

A global server middleware is added by @nuxtjs/hanko. After decoding and validating the session token for the request, a new hanko property is added to the event context. You can check the value of event.context.hanko to see if the request was authenticated. The user’s id is accessible though the sub claim/property.

/server/api/endpoint.ts
export default defineEventHandler(async (event) => {
  const hanko = event.context.hanko;
  if (!hanko || !hanko.sub) {
    return {
      status: 401,
      body: {
        message: "Unauthorized",
      },
    };
  }
  // Do something with the Hanko user
  return {
    hanko: event.context.hanko,
  };
});

​
Try it yourself

Nuxt example

Full source code available on our GitHub