Integrate Hanko with Remix

Create a Remix application

Create a new Remix application using the official starter template. Run the following command to create a new Remix application:

npx create-remix@latest

Install `@teamhanko/hanko-elements`

The Hanko Elements package provides pre-built authentication components (hanko-auth, hanko-profile) and a JavaScript SDK. Install the package:

cd project-name
npm install @teamhanko/hanko-elements

cd project-name
pnpm add @teamhanko/hanko-elements

cd project-name
bun add @teamhanko/hanko-elements

cd project-name
yarn add @teamhanko/hanko-elements

Set up your Hanko project

Create a Hanko project in the Cloud Console to get your API URL. Go to the Hanko Console and create a project for this application.

Set the APP URL to your development URL (typically http://localhost:5173/ for Remix).

Add the Hanko API URL

Add your Hanko API URL to your environment file. In Remix, environment variables without a public prefix are server-side only. Retrieve the API URL from the Hanko Console and add it to your .env file:

.env

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.

Create client-side utilities

The @teamhanko/hanko-elements package only works client-side. Use Remix’s .client.ts file convention to ensure code only runs in the browser. Create a client-side utility file:

utils/hanko.client.ts

import { register, Hanko } from "@teamhanko/hanko-elements";

export { register, Hanko };

Create Hanko components

Create a components folder with two files: HankoAuth.tsx and HankoProfile.tsx.

Hanko Auth

The HankoAuth component provides login and registration functionality. It uses Remix’s loader to pass the API URL from server to client, and handles the onSessionCreated event for post-login navigation. For more information see the Auth component documentation.

components/HankoAuth.tsx

import { useNavigate, useLoaderData } from "@remix-run/react";
import { Suspense, useCallback, useEffect, useState } from "react";
import { register, type Hanko } from "../utils/hanko.client";

export const loader = () => {
    return { hankoUrl: process.env.HANKO_API_URL }; 
};

const HankoAuth = () => {
  const [hanko, setHanko] = useState<Hanko>();
  const navigate = useNavigate();

  const data = useLoaderData<typeof loader>();
  const hankoUrl = data.hankoUrl || '';

  const redirectAfterLogin = useCallback(() => {
      navigate("/dashboard");//Path user gets navigated to once they log in
  }, [navigate]);

  useEffect(() => {
      if (hanko) {
          hanko.onSessionCreated(() => {
              // Successfully Logged In
              redirectAfterLogin();
          });
      }
  }, [hanko, redirectAfterLogin]);

  useEffect(() => {
      register(hankoUrl)
          .catch((error: Error) => {
              console.error(error.message);
          })
          .then((result) => {
              if (result) {
                  setHanko(result.hanko);
              }
          });
  }, [hankoUrl]);

  return (
      <div className="">
          <Suspense fallback={"Loading..."}>
              <hanko-auth />
          </Suspense>
      </div>
  );
};

export default HankoAuth;

Hanko Profile

The HankoProfile component allows users to manage their email addresses and passkeys. For more information see the Profile component documentation.

components/HankoProfile.tsx

import { useLoaderData } from "@remix-run/react";
import { Suspense, useEffect, } from "react";
import { register } from "../utils/hanko.client";

export const loader = () => {
    return { hankoUrl: process.env.HANKO_API_URL };
};

const HankoProfile = () => {
    const data = useLoaderData<typeof loader>();
    const hankoUrl = data.hankoUrl || '';

    useEffect(() => {
        register(hankoUrl).catch((error) => {
            // handle error
            console.log(error);
          });
    });

    return(
        <Suspense fallback={"Loading..."}>
            <hanko-profile />
        </Suspense>
    )
}
  
export default HankoProfile;

Setup your routes

Create your routes in the /routes folder. You’ll need _index.tsx for the login page and dashboard.tsx for the user dashboard. Create the main login route:

routes/_index.tsx

import HankoAuth from "../components/HankoAuth";

export const loader = () => {
  return { hankoUrl: process.env.HANKO_API_URL }; 
};

export default function Index() {
  return (
    <>
      <HankoAuth></HankoAuth>
    </>
  );
}

Create the dashboard route:

routes/dashboard.tsx

import HankoProfile from "../components/HankoProfile";

export const loader = () => {
  return { hankoUrl: process.env.HANKO_API_URL }; 
};

export default function Dashboard() {
  return (
    <>
      <HankoProfile></HankoProfile>
    </>
  );
}

By now you should be able to go to / to see the <HankoAuth>, and to /dashboard to see the <HankoProfile>. They should look something like this👇

If HankoAuth is not loading please restart the application as it might’ve not loaded the .env correctly the first time.

HankoProfile will only look like the picture while you are logged in.

Implement logout functionality

Create a logout button using the Hanko SDK’s logout method. Create LogoutButton.tsx:

components/LogoutButton.tsx

import { useLoaderData, useNavigate } from "@remix-run/react";
import { useEffect, useState, } from "react";
import { type Hanko, } from "../utils/hanko.client";


export const loader = () => {
    return { hankoUrl: process.env.HANKO_API_URL };
};

const LogoutButton = () => {

    const data = useLoaderData<typeof loader>();
    const hankoUrl = data.hankoUrl || '';

    const navigate = useNavigate();
    const [hanko, setHanko] = useState<Hanko>();
  
    useEffect(() => {
      import("@teamhanko/hanko-elements").then(({ Hanko }) =>
        setHanko(new Hanko(hankoUrl ?? ""))
      );
    }, []);

    const logout = async () => {
        try {
            await hanko?.logout();

            navigate("/");//Path the user will be redirected to once logged out
            
            return;
        } catch (error) {
            console.error("Error during logout:", error);
        }
    };

    return <button onClick={logout}>Logout</button>;
}
  
export default LogoutButton;

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.

Securing routes

Protect routes by validating session tokens in loader functions. Create a server-side authentication utility to handle session validation. Create app/services/auth.server.ts:

app/services/auth.server.ts

import { parse } from "cookie";

export async function ValidateCurrentSession(request: Request, hankoUrl: string){

    const cookies = parse(request.headers.get("Cookie") || "");
    const token = cookies.hanko;

    const validationOptions = { 
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: `{"session_token":"${token}"}`
    }
    try {
    const response = await fetch(hankoUrl + '/sessions/validate', validationOptions);

    if (!response.ok) throw new Error('Session validation failed');
    
    const verifiedResponse = await response.json();

    return verifiedResponse.is_valid
    
    } catch (error) {
    console.log(error)
    return false;
    }
}

Use the authentication service in your protected routes. Update your dashboard route to validate sessions:

app/routes/dashboard.tsx

import HankoProfile from "../components/HankoProfile";
import LogoutButton from "../components/LogoutButton";

import { type LoaderFunction, redirect } from "@remix-run/node";
import { ValidateCurrentSession } from "../services/auth.server";

export const loader: LoaderFunction = async ({request}) => {
  const hankoUrl = process.env.HANKO_API_URL || "";
  const validated = await ValidateCurrentSession(request , hankoUrl);

  if(!validated){
    return redirect("/");//Path to redirect to if user is not authenticated
  }

  return { hankoUrl: hankoUrl }; 
};

export default function Dashboard() {
  return (
    <>
      <HankoProfile></HankoProfile>
      <LogoutButton></LogoutButton>
    </>
  );
}

Try it yourself

Remix example

Full source code available on our GitHub

Getting started

Guides

Using the Hanko API

Integrations

Resources

FAQ & support

Integrate Hanko with Remix

Create a Remix application

Install `@teamhanko/hanko-elements`

Set up your Hanko project

Add the Hanko API URL

Create client-side utilities

Create Hanko components

Hanko Auth

Hanko Profile

Setup your routes

Implement logout functionality

Customize component styles

Securing routes

Try it yourself

Remix example

​Create a Remix application

​Install @teamhanko/hanko-elements

​Set up your Hanko project

​Add the Hanko API URL

​Create client-side utilities

​Create Hanko components

​Hanko Auth

​Hanko Profile

​Setup your routes

​Implement logout functionality

​Customize component styles

​Securing routes

​Try it yourself

Remix example

Create a Remix application

Install `@teamhanko/hanko-elements`

Set up your Hanko project

Add the Hanko API URL

Create client-side utilities

Create Hanko components

Hanko Auth

Hanko Profile

Setup your routes

Implement logout functionality

Customize component styles

Securing routes

Try it yourself