Custom UI: Integration with popular vite powered UI libraries

[vitorfigmgs]

Related Pull requests

• SST Component for deploying custom auth.

---

Overview

This PR introduces a Vite-powered meta-framework that enables fully customizable UIs for the password provider pages (It can easily be extended to support other providers later). It allows you to use any modern UI framework (initially React) with with full HMR support and SSR with just a few lines of configuration.

How to Use It

1. Configuration
Create an openauth.config.ts file to define your plugins and integrations:

import { defineConfig } from "@openauthjs/vite";
import { react } from "@openauthjs/react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  integrations: [react()],
  plugins: [tailwindcss()],
});

2. Setup the Provider
Use CustomPasswordUI inside your issuer configuration:

const app = issuer({
  subjects,
  allow: async () => true,
  providers: {
    password: PasswordProvider(
      CustomPasswordUI({
        sendCode: async (email, code) => {
          console.log(email, code);
        }
      })
    )
  }
});

3. Define Pages & Entrypoints

• Pages (src/pages/): Create components to render each route (e.g., src/pages/login.tsx).
• main.tsx: Required client-only entrypoint for browser hydration.
• layout.tsx: Server-only Hono component used to build the HTML shell (head and meta tags).

4. Data Loading (Optional)
You can use loader functions to run server-side logic (like database fetching) and pass data to your page components or customize response headers:

providers: {
  password: PasswordProvider(
    CustomPasswordUI({
      sendCode: async (email, code) => {
        console.log(email, code);
      },
      loader: {
        login: async () => {
          const dbData = await getDataFromDb();

          return {
            data: dbData,
            responseInit: {
              headers: {
                "x-custom-header": "hello",
              },
            },
          };
        },
      }
    })
  )
}

5. OpenAuth CLI
Use the CLI from the @openauthjs/vite package to manage your project:

Run the dev server:

openauth dev

Build for production:

openauth build

6. Deploy to Production
Use the sst.aws.Auth component alongside these CLI commands to deploy your auth server to an AWS Lambda function, or to run dev mode integrated with your other SST components.

How it works

• @openauthjs/vite: The main package for this feature. It compiles server/client code (making a heavy usage of vite virtual modules plugins) to provide an SSR and dev mode HMR experience experience similar to Next.js or TanStack Start.
• Integrations: Framework-specific modules that provide Vite plugins, interact with the Hono SSR rendering logic, and points to a Renderer (our vite virutal module plugins only include the rederers in the server bundle if it was pointed by an integration).
• Renderer: Contains all the logic for server-side rendering the chosen UI framework's components.
• Integration Client: Eovides functions for main.tsx to hydrate SSR pages and handle OpenAuth data (like form submissions and page state).
• CustomPasswordUI: Implements the Password provider interface. It renders the Hono layout shell and triggers the specific Renderer for the active route.

How to Test

To test these changes, please use the companion SST example PR

Related Issues

• Closes Integration with Framework and custom UI #259

Small change in the packages/openauth/src/provider/oauth2.ts

To reference the virtual.d.ts type in @openauthjs/openauth without type errors, I updated the TypeScript config with:

• "lib": ["ESNext"]
• "types": ["node"]
• "rootDir": "./src"

This resolved the underlying issue from provider/oauth2.ts , so I had to remove remove the @ts-ignore from this file.