Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hana.leafphp.dev/llms.txt

Use this file to discover all available pages before exploring further.

SPAs usually handle authentication via tokens, with checks to find if the token exists, and rugged middleware that maintains the current state or invalidates the state depending on responses from the backend. Hana ships an authentication component powered by Hana Auth that automatically takes care of all of that. All you need to do is pass in your user, and Hana will take care of the rest.
Hana Store is automatically added to projects generated using create-hana-app, but you can manually install it from npm
npm install @hanabira/auth

​
Getting started

After installing Hana Auth, the first thing to do is to initialize your authentication using the createAuth function.
src/pages/_app.tsx
import { createAuth } from '@hanabira/auth';

createAuth();
This function takes in an optional config object that can be used to configure the auth utility. It is recommended to call this function in your root component so that it is only called once.

​
Auth Configuration

The config object has the following properties:
  • tokenKey: The key to use when saving the token to local storage. Defaults to token.
  • userKey: The key to use when saving the user to local storage. Defaults to user.
  • refreshTokenKey: The key to use when saving the refresh token to local storage. Defaults to refreshToken.
  • loginPath: The path to redirect to when the user is not authenticated. Defaults to /login.
  • logoutPath: The path to redirect to when the user logs out. Defaults to /login.
  • dashboardPath: The path to redirect to when the user is authenticated. Defaults to /dashboard.
  • cookie: Options to use when saving information to a cookie.
import { createAuth } from '@hanabira/auth';

...

createAuth({
  tokenKey: 'token',
  userKey: 'user',
  refreshTokenKey: 'refreshToken',
  loginPath: '/login',
  dashboardPath: '/dashboard',
});

​
Authentication types

The auth utility provides different types of authentication. These types are:
  • localstorage: This type of authentication uses the browser’s local storage to save the token and user information. This is the default type of authentication.
  • cookie: This type of authentication uses cookies to save the token and user information.
Auth with local storage is the default type of authentication. To use cookie authentication, you need to pass in the cookie option to the createAuth function. 
import { createAuth } from '@hanabira/auth';

createAuth({
  cookie: {
    path: '/',
    expires: 60,
    domain: 'localhost',
    sameSite: 'Lax',
  },
});
The cookie option takes in the following properties:
  • path: The path where the cookie is available. Defaults to /.
  • expires: Define when the cookie will be removed. Value can be a Number which will be interpreted as days from time of creation or a Date instance. If omitted, the cookie becomes a session cookie.
  • domain: Define the domain where the cookie is available. Defaults to the domain of the page where the cookie was created.
  • sameSite: Asserts that a cookie must not be sent with cross-origin requests,providing some protection against cross-site request forgery attacks (CSRF)
  • secure: A boolean indicating if the cookie transmission requires a secure protocol (https). Defaults to false.
From here, everything else is the same as local storage authentication.

​
Auth states

Generally, there are two auth states: authenticated and unauthenticated. When the user is authenticated, the auth utility saves the token and user information to the appropriate storage. This information is then used to verify the auth state of the user and is removed when the user logs out. Hana Auth provides multiple ways to change and verify the auth state of the user.