Hanko 2.0

[FreddyDevelop]

We are excited to announce the release of Hanko 2.0!

The main highlight of this release is the completely redesigned JavaScript SDK, built to work seamlessly with our Flow API introduced in version 1.0. This new SDK brings major improvements in flexibility, developer experience, and frontend state management when building custom UI using the Hanko API.

New JavaScript SDK

• New State Management: Introduces the State class for handling flow states, complete with event hooks (onBeforeStateChange, onAfterStateChange), serialization to localStorage, and auto-stepping through flows.
• Action Execution: Provides a new Action class for type-safe action invocation within authentication flows.
• Passkey Autofill Support: Integrates passkey autofill activation handlers for supported states.
• Persistence: Flow state persistence via localStorage, improving UX across sessions.

Example usage:

const hanko = new Hanko(/* params */);
const state = await hanko.createState("login");

await state.actions.continue_with_login_identifier.run({
  username: "user",
});

hanko.onBeforeStateChange(({state}) => {
  console.log(`Action invoked: ${state.invokedAction.name}`);
});

hanko.onAfterStateChange(({state}) => {
  console.log(`Action finished: ${state.previousAction.name}`);

  if (state.name == "login_init") {
    state.passkeyAutofillActivation();
  }
});

Warning

The new frontend SDK introduces breaking changes: If you are using a custom frontend based on the previous SDK, please review the SDK docs carefully. We also provide a guide on how to use the SDK to build a custom UI for the Flow API.

Updated Session Management Access

• The session management functions are now directly available on the top-level Hanko instance:
  • getUser()
  • validateSession()
  • getSessionToken()
  • logout()
• Previously, these functions were accessed through individual clients, which have now been removed.
• This change simplifies session handling and aligns with the overall SDK cleanup.
• Example code and documentation have been updated accordingly.

SDK Cleanup

• Removed deprecated clients (EmailClient, ThirdPartyClient, EnterpriseClient, TokenClient) and outdated session handling logic.
• Simplified configuration management by unifying internal options.
• Removed obsolete DTOs and related tests.

Backend Compatibility

There are no major changes to the backend compared to version 1.5.2. Updating the backend to use the new JavaScript SDK is not mandatory if you are currently on v1.5.2. However, we recommend upgrading to the latest backend version, as running the new frontend SDK with an older backend version is not officially supported and may lead to unexpected issues.

Custom Session Claims

Custom claims can now be added to the session token. A new configuration option, session.jwt_template, has been added that allows defining session.jwt_template.claims. Values can be arbitrarily nested and can use Go text templates.

The custom claims are also added to sessions/validate endpoint responses.

New Session Token Storage Option

A new option sessionTokenLocation was added to the HankoOptions configuration. You can now choose where the session token is stored on the client:

• cookie (default) — persists across tabs and sessions.
• sessionStorage — session ends automatically when the browser tab is closed.

This allows finer control over session lifetime, improving security for sensitive applications.

Tip

Use sessionStorage if you want user sessions to automatically end when a tab or browser window is closed.

Example configuration:

const hanko = new Hanko("https://your-hanko-instance", {
  sessionTokenLocation: "sessionStorage", // ends session on tab close
});

Note

This setting only works when session.enable_auth_token_header: true is set.

New Contributors

• @franklinkim made their first contribution in feat: update koanf v2.1.2 #2110

Full Changelog: backend/v1.5.2...backend/v2.0.0

Thanks to everyone who contributed to this release! 🫶
We are looking forward to your feedback and contributions.

---

This discussion was created from the release Hanko 2.0.