Forem: Hiroto Shioi

How to protect server functions with auth middleware in TanStack Start

Hiroto Shioi — Mon, 12 Jan 2026 07:22:15 +0000

Overview

This article explains how to implement an authentication middleware and use it to protect access to Server Functions.
While this guide uses Better Auth as an example, the same approach can be applied to other authentication services.

What You’ll Learn

The basics of TanStack Start Server Functions and middleware
How to implement authentication middleware integrated with Better Auth
A pattern for handling user sessions in a type-safe way

What Are Server Functions?

Server Functions are functions guaranteed to run on the server side. In TanStack Start, you can use Server Functions instead of REST APIs or GraphQL to exchange data between the client and server.

https://tanstack.com/start/latest/docs/framework/react/guide/server-functions

import { createServerFn } from '@tanstack/react-start'

export const getServerTime = createServerFn().handler(async () => {
  // Guaranteed to run on the server
  return new Date().toISOString()
})

// Can be called from anywhere
const time = await getServerTime()

What Is Middleware?

Middleware is a function that runs before a Server Function’s main handler. By using middleware, you can add cross-cutting concerns to Server Functions, such as authentication, logging, or error handling.

The authentication middleware introduced in this article checks whether a user is authenticated before allowing access to a specific Server Function.

https://tanstack.com/start/latest/docs/framework/react/guide/middleware

Benefits of Using Authentication Middleware

Using authentication middleware provides the following benefits:

Protect Server Functions and prevent access from unauthenticated users
Handle authenticated user information in a type-safe way within Server Functions
Improve maintainability through reusable authentication logic, making the codebase easier to change

Prerequisites

You must have completed the Better Auth setup by following the official documentation.

https://www.better-auth.com/docs/installation
https://www.better-auth.com/docs/integrations/tanstack

Steps

1. Implement `getUserSession`, a function that returns the authenticated user’s session

import { createServerFn } from "@tanstack/react-start";
import { getRequest } from "@tanstack/react-start/server";
import { auth } from "@/lib/auth";

export const getUserSession = createServerFn({ method: "GET" }).handler(
  async () => {
    const request = getRequest();

    if (!request?.headers) {
      return null;
    }

    const userSession = await auth.api.getSession({ headers: request.headers });

    if (!userSession) return null;

    return { user: userSession.user, session: userSession.session };
  }
);

2. Implement `authMiddleware`, an authentication middleware

import { redirect } from "@tanstack/react-router";
import { createMiddleware } from "@tanstack/react-start";
import { getUserSession } from "@/services/auth/server-functions";

export const authMiddleware = createMiddleware({ type: "function" }).server(
  async ({ next }) => {
    const userSession = await getUserSession();
    if (!userSession) {
      throw redirect({ to: "/" }); // Redirect to home if not authenticated
    }
    return next({ context: { userSession } });
  }
);

The key point here is returning userSession via the next function. This enables the Server Function handler to access the user session information.

3. Implement a Server Function using the authentication middleware

import { createServerFn } from "@tanstack/react-start";
import { authMiddleware } from "@/middlewares/auth";
import { todoRepository } from "@/services/todos/repository";

export const getTodos = createServerFn()
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    const { userSession } = context; // Type-safe access to session info
    const todoList = await todoRepository.get(userSession.user.id);
    return todoList;
  });

Summary

This article explained how to implement authentication middleware in TanStack Start and use it to protect access to Server Functions. By using authentication middleware, you can strengthen security and handle user information in a type-safe manner. While this guide used Better Auth as an example, the same approach can be applied to other authentication services.

Repository

https://github.com/HirotoShioi/tanstack-start-template

Introducing hiraku: A type-safe, imperative modal manager for shadcn/ui & Radix UI.

Hiroto Shioi — Thu, 11 Dec 2025 03:56:43 +0000

Managing modals in React can be a pain. You know the drill:

Define useState in the parent component.
Pass isOpen and onOpenChange down the tree.
Create callback functions to handle results.
Repeat for every single modal. 😩

"I just want to call a function to open a modal, like alert() or confirm()."

If you've ever thought this, I built hiraku for you.

It's a new library designed specifically for shadcn/ui (Radix UI) to make modal management simple, type-safe, and imperative.

The Problem: "Declarative" isn't always better

shadcn/ui is amazing. But the standard way of handling dialogs often leads to bloated parent components.

The Old Way:

function ParentComponent() {
  // 1. State clutter
  const [isOpen, setIsOpen] = useState(false);

  // 2. Logic fragmentation
  const handleConfirm = () => {
    // ... logic ...
    setIsOpen(false);
  }

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open</Button>
      <MyDialog 
        open={isOpen} 
        onOpenChange={setIsOpen} 
        onConfirm={handleConfirm} 
      />
    </>
  );
}

This separates the "trigger" logic from the "result" logic. It makes your code harder to read and maintain.

The Solution: Function-based Modals 🚀

hiraku lets you treat modals like function calls.

The hiraku Way:

const handleDelete = async () => {
  // 1. Open it
  await confirmDialog.open({
    title: "Delete Item",
    message: "Are you sure?",
  });

  // 2. Await the result right here
  const { role } = await confirmDialog.onDidClose();

  if (role === "confirm") {
    console.log("Item deleted!");
  }
};

Clean, linear, and easy to read.

Why hiraku? ✨

⚡️ Zero State Management: No more useState or isOpen props in your parents.
🎯 Intuitive API: Just createDialog() and open().
🪄 Call from Anywhere: Open modals from hooks, event handlers, or even pure utility functions (like API error handlers).
🔒 100% Type-Safe: Props and return values are fully typed.
🧩 shadcn/ui Ready: Designed to work seamlessly with your existing Radix UI components.
🪶 Lightweight: ~3KB (gzipped).

Quick Start

1. Install

npm install @hirotoshioi/hiraku

Add the ModalProvider to your app root:

import { ModalProvider } from "@hirotoshioi/hiraku";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
    <ModalProvider />
  </StrictMode>
);

2. Create a Controller

Wrap your component with createDialog. You don't need the <Dialog> wrapper anymore; hiraku handles it.

import { createDialog } from "@hirotoshioi/hiraku";

interface Props {
  title: string;
  message: string;
}

// Your component receives props directly
function InfoDialogContent({ title, message }: Props) {
  return (
    <DialogContent>
      <DialogHeader>
        <DialogTitle>{title}</DialogTitle>
        <DialogDescription>{message}</DialogDescription>
      </DialogHeader>
      <DialogFooter>
        {/* Close it via the controller */}
        <Button onClick={() => infoDialog.close()}>OK</Button>
      </DialogFooter>
    </DialogContent>
  );
}

// Create the controller
export const infoDialog = createDialog(InfoDialogContent);

3. Open it!

// Fully typed props!
await infoDialog.open({
  title: "Hello World",
  message: "This is so much easier.",
});

Getting Data Back (Type-Safe!)

You can even define what data the modal returns.

// Define the return type
export const editUserDialog = createDialog(EditUserDialog).returns<User>();

// In your component
const handleSave = (user: User) => {
  editUserDialog.close({ 
    role: "confirm", 
    data: user 
  });
};

// In your usage
const { data, role } = await editUserDialog.onDidClose();
if (role === "confirm" && data) {
  console.log("Updated user:", data);
}

Call Modals from API Utilities

Since hiraku controllers aren't hooks, you can import them anywhere. This is a game-changer for global error handling.

// api.ts
import { errorDialog } from "./dialogs/errorDialog";

export async function fetchData() {
  try {
    // ... fetch logic
  } catch (err) {
    // Open a modal directly from your non-React logic!
    await errorDialog.open({
      title: "Network Error",
      message: "Something went wrong.",
    });
  }
}

Migration is Easy

You don't have to rewrite your whole app. You can migrate one modal at a time. Just remove the isOpen props and wrap the component in createDialog.

Give it a try! 🌟

I built hiraku to make my own life easier when working with shadcn/ui, and I hope it helps you too.

Check it out on GitHub and let me know what you think!

👉 https://github.com/HirotoShioi/hiraku

(If you like it, a Star ⭐️ would make my day!)