SolidStart

This guide shows how to integrate gau with SolidStart, using Drizzle (SQLite or PostgreSQL) and GitHub as examples.

1. Follow the basic setup

   Complete the Getting Started guide.

   Complete the Drizzle guide:

   1. Set up your schema in src/server/db/schema.ts
   2. Set up your database in src/server/db/index.ts
   
   

2. Set up API Route

   Create a catch-all route for auth endpoints on the server.

   src/routes/api/auth/[...gau].ts

   import { SolidAuth } from '@rttnd/gau/solidstart'
   import { auth } from '~/server/auth'
   
   export const { GET, POST, OPTIONS } = SolidAuth(auth)

3. Add Middleware

   Add the middleware to attach getSession to event.locals. Optionally, you can preload the session for selected paths or for all requests. See Eager vs Lazy Loading.

   src/middleware.ts

   import { authMiddleware } from '@rttnd/gau/solidstart'
   import { createMiddleware } from '@solidjs/start/middleware'
   import { auth } from './server/auth'
   
   export default createMiddleware({
     onRequest: [authMiddleware(true, auth)],
   })

   And register the middleware in app.config.ts:

   app.config.ts

   export default defineConfig({
     middleware: 'src/middleware.ts',
   })

   Now, in server code, you can access event.locals.getSession() which returns { user, session, accounts, providers }.

   For full type-safety, add the following to src/global.d.ts:

   src/global.d.ts

   import type { GauSession, ProviderIds } from '@rttnd/gau'
   import type { Auth } from './server/auth'
   
   declare global {
     namespace App {
       interface RequestEventLocals {
         getSession: () => Promise<GauSession<ProviderIds<Auth>>>
       }
     }
   }
   
   export {}

4. Set up the Client

   Wrap your application in an AuthProvider and use the useAuth hook to access session data.

   SSR

   Use createAsync to fetch the session on the server. This will serialize the session into the initial HTML.

   src/server/session.ts

   import { query } from '@solidjs/router'
   import { getRequestEvent } from 'solid-js/web'
   
   export const getSession = query(async () => {
     'use server'
     const event = getRequestEvent()
     return event?.locals.getSession()
   }, 'session')

   src/app.tsx

   // @refresh reload
   import { AuthProvider } from '@rttnd/gau/client/solid'
   import { Router } from '@solidjs/router'
   import { FileRoutes } from '@solidjs/start/router'
   import { Suspense } from 'solid-js'
   import { createAsync } from '@solidjs/router'
   import { getSession } from '~/server/session'
   
   export default function App() {
     return (
       <Router
         root={(props) => {
           const session = createAsync(() => getSession())
           return (
             <Suspense>
               <AuthProvider session={session} baseUrl={clientEnv.VITE_API_URL}>
                 {props.children}
               </AuthProvider>
             </Suspense>
           )
         }}
       >
         <FileRoutes />
       </Router>
     )
   }

   CSR

   If you use ssr: false, the setup is simple. The session will be fetched client-side after hydration.

   src/app.tsx

   // @refresh reload
   import { AuthProvider } from '@rttnd/gau/client/solid'
   import { Router } from '@solidjs/router'
   import { FileRoutes } from '@solidjs/start/router'
   import { Suspense } from 'solid-js'
   
   export default function App() {
     return (
       <AuthProvider>
         <Router
           root={props => (
             <Suspense>{props.children}</Suspense>
           )}
         >
           <FileRoutes />
         </Router>
       </AuthProvider>
     )
   }

   Note

   If your frontend and backend are on different hosts, set baseUrl to the full URL of your backend’s auth API. Use envs to set it for development and production.

   <AuthProvider baseUrl={import.meta.env.VITE_API_URL}>

   Next, to get full TypeScript support for your provider IDs, create a typed useAuth hook. This is a great practice as you only have to type it once.

   src/lib/auth.ts

   import type { Auth } from '~/server/auth'
   import { useAuth as useAuthCore } from '@rttnd/gau/client/solid'
   
   export const useAuth = () => useAuthCore<Auth>()

   Note

   Exporting and importing the Auth type is optional, but it gives better types for the auth.signIn method. By default, the provider param is string, but with the Auth type, it will be a union of string literals of the configured providers, like 'github' | 'google'.

   Now you can use your custom useAuth hook in any component to access the session and authentication methods.

   src/routes/index.tsx

   import { useAuth } from '~/lib/auth'
   import { Show } from 'solid-js'
   
   export default function Home() {
     const auth = useAuth()
   
     return (
       <Show
         when={auth.session().user}
         fallback={(
           <button onClick={() => auth.signIn('github')}>Sign in with GitHub</button>
         )}
       >
         <button onClick={() => auth.signOut()}>Sign Out</button>
       </Show>
     )
   }

   For protecting routes on the client side, you can use the Protected helper:

   src/routes/dashboard.tsx

   import { Protected } from '@rttnd/gau/client/solid'
   
   export default Protected(
     (session) => (
       <div>
         <h1>Dashboard</h1>
         <p>Welcome, {session().user?.name}!</p>
       </div>
     ),
     '/login' // redirect URL
   )

   Note

   For better security, consider server-side protection using route data functions. See the Protected Routes section for more details.

5. File Structure

   • Directorysrc

     • Directorylib

       • auth.ts
       • session.ts
     • Directoryroutes

       • Directoryapi

         • Directoryauth

           • […gau].ts
       • index.tsx
     • Directoryserver

       • auth.ts
     • app.tsx
     • global.d.ts
     • middleware.ts
   • app.config.ts
   • package.json

6. Next Steps

   • Explore other OAuth Providers.
   • See Deployment for production tips.
   • Learn about how gau works.