How to Secure Your TanStack React Start App with Light-Auth

Light-Auth is a lightweight authentication solution designed for simplicity and ease of integration.
It provides essential authentication features with minimal setup, making it ideal for React developers, prototypes, and SSR frameworks.

You can find an introduction to Light-Auth here: Light-Auth: Authentication for SSR Frameworks

✅ Why Use Light-Auth?

• Quick Setup: Minimal configuration required.
• Supports OAuth Providers: Google, GitHub, and more.
• Lightweight: Minimal dependencies.
• Extensible: Easily customize for advanced use cases.
• Works Everywhere: Compatible with SSR frameworks like Next.js, Astro, SvelteKit, Nuxt, and TanStack Start.

🔐 How to Use Light-Auth with TanStack Start

This guide walks you through the steps to add authentication and authorization to your Tanstack Start application using Light-Auth.

👉 You can find the complete code for a sample Tanstack Start application here: Tanstack Start Sample with Light-Auth

1) Install Light-Auth

Once you have created your Tanstack Start application (you can follow this tutorial: Tanstack Start Build from Scratch), you can add Light-Auth for Tanstack using your preferred package manager:

npm -i @light-auth/tanstack-react-start

2) Add your OAUTH providers

Light-Auth uses Arctic providers

You will find the complete list of Arctic providers on the official website: Arctic v3

Each provider needs to be configure, usually with a ClientId, a Client Secret and a Redirect URI.

As an example, we are going to use a Google provider.

Note that Light-Auth can use multiple providers, but for sake of simplicity, we are going to use only one here.

Once you have configure your Google OAUTH2 from the google admin console, add a .env file at the root of your project:

GOOGLE_CLIENT_ID=<your_client_id_from_google_cloud>
GOOGLE_CLIENT_SECRET=<your_client_secret_from_google_cloud>
GOOGLE_REDIRECT_URI=http://localhost/api/auth/callback/google

LIGHT_AUTH_SECRET_VALUE=<any_random_secret_used_to_secure_server_cookies>

LIGHT_AUTH_SECRET_VALUE value is used to encrypt cookies, and is mandatory.

3) Configure vite

Add @light-auth/tanstack-react-start to the vite config as noExternal to avoid the SSR context loss.

If you want more info on why this step is mandatory, you can read more info here: SSR context loss

// file: "./vite.config.ts"

export default defineConfig({
  ...,
  ...,
  ssr: {
    noExternal: ['@light-auth/tanstack-react-start'],
  },
})

4) Configure Light-Auth

This file contains the authentication logic and configuration.
The exports consts are providers, handlers, signIn, signOut, getAuthSession, and getUser.

These constants are used throughout the application to manage authentication.

// file: "./lib/auth.ts"

import { Google} from "arctic";
import { CreateLightAuth } from "@light-auth/nextjs";

const googleProvider = {
  providerName: "google",
  arctic: new Google(
    process.env.GOOGLE_CLIENT_ID,
    process.env.GOOGLE_CLIENT_SECRET,
    process.env.GOOGLE_REDIRECT_URI
  ),
};

export const { providers, handlers, signIn, signOut, getAuthSession, getUser } = CreateLightAuth({
  providers: [googleProvider]
})

5) Add Light-Auth Handlers

This file contains the authentication handlers for the API.
These handlers are responsible for processing authentication requests and returning the appropriate responses.
The handlers are exported as GET and POST methods.

// file: "./routes/api/auth/$.tsx"

import { createServerFileRoute } from '@tanstack/react-start/server';
import { handlers } from "@/lib/auth";
export const ServerRoute = createServerFileRoute('/api/auth/$').methods(handlers)

That's it. Everything is now configured.
You just need now to implement your login page and use the exports constants everywhere you need them.

6) Add login page

This file contains the login page using a form action to login using your provider.

Note: You can also use client components to trigger the login process.
See the documentation Client Components for more information.

// file: "./routes/login.tsx"

import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start';
import { signIn } from '@/lib/auth';

export const Route = createFileRoute('/login')({
  component: RouteComponent,
})

export const actionSignIn = createServerFn().handler(() => signIn("google", "/profile"));


function RouteComponent() {
  return (
    <div>
      <form action={actionSignIn.url} method="POST">
        <button type="submit">login using a form action</button>
      </form>
    </div>
  );
}

7) Use Light-Auth in your Profile page

Retrieves the session information to check if user is authenticated or not and displays it.

// file: "./routes/profile.tsx"

import { createFileRoute, Link } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start';
import { getAuthSession as laGetAuthSession } from "@/lib/auth";

const getAuthSession = createServerFn({
  method: 'GET',
}).handler(() => {
  return laGetAuthSession()
})

export const Route = createFileRoute('/profile')({
  component: RouteComponent,
  loader: async () => {
    const session = await getAuthSession();
    return { session };
  },
})

function RouteComponent() {
  const state = Route.useLoaderData()
  const session = state.session;

  return (
    <div>
      {session != null ? (
        <div>
          <p>✅ You are logged in!</p>
          <div>Session Email: {session.email}</div>
          <div>Session Provider: {session.providerName}</div>
        </div>
      ) : (
        <div>
          <p>⚠️ You are not logged in</p>
          <a href="/login"> Go to Login Page </a>
        </div>
      )}
    </div>
  );
}

✅ Conclusion

By following these steps, you’ve successfully integrated Light-Auth into your TanStack React Start application.

This setup provides a secure, scalable, and easy-to-maintain authentication system with minimal configuration.

Next steps:

• Add more OAuth providers (GitHub, Twitter, etc.)
• Implement role-based access control
• Secure API routes with session validation

For more details, visit the Light-Auth official website.