Astro Adapter
Adapter for integrating Better Auth Studio with Astro applications.
Import
import { betterAuthStudio } from 'better-auth-studio/astro';
betterAuthStudio()
Creates an Astro-compatible API route handler for Better Auth Studio.
Function Signature
function betterAuthStudio(config: StudioConfig): (ctx: { request: Request }) => Promise<Response>
Parameters
Studio configuration object containing authentication and feature settings.Show StudioConfig properties
Your Better Auth instance
Base path for the studio routes. Default: "/api/studio"
Access control configuration for the studio
Customization options for branding and theming
Last-seen tracking configuration
IP geolocation provider configuration
Event tracking and ingestion configuration
Tools configuration with exclude list
Returns
An async function that accepts an Astro context object and returns a Response
Usage
Catch-all API Route
Create a catch-all endpoint to handle all studio requests:
// pages/api/studio/[...all].ts
import { betterAuthStudio } from 'better-auth-studio/astro';
import { auth } from '~/lib/auth';
import { defineStudioConfig } from 'better-auth-studio';
import type { APIRoute } from 'astro';
const studioConfig = defineStudioConfig({
auth,
basePath: '/api/studio',
metadata: {
title: 'My App Studio',
theme: 'dark'
},
events: {
enabled: true,
tableName: 'auth_events'
}
});
const handler = betterAuthStudio(studioConfig);
export const ALL: APIRoute = async (ctx) => {
return handler(ctx);
};
Simplified Version
// pages/api/studio/[...all].ts
import { betterAuthStudio } from 'better-auth-studio/astro';
import { auth } from '~/lib/auth';
import type { APIRoute } from 'astro';
const handler = betterAuthStudio({ auth });
export const ALL: APIRoute = handler;
With Access Control
// pages/api/studio/[...all].ts
import { betterAuthStudio } from 'better-auth-studio/astro';
import { auth } from '~/lib/auth';
import type { APIRoute } from 'astro';
const handler = betterAuthStudio({
auth,
access: {
roles: ['admin'],
allowEmails: ['[email protected]']
}
});
export const ALL: APIRoute = handler;
With Custom Middleware
// pages/api/studio/[...all].ts
import { betterAuthStudio } from 'better-auth-studio/astro';
import { auth } from '~/lib/auth';
import type { APIRoute, APIContext } from 'astro';
const studioHandler = betterAuthStudio({ auth });
export const ALL: APIRoute = async (ctx: APIContext) => {
// Custom middleware logic
console.log(`Studio request: ${ctx.request.method} ${ctx.url}`);
// Call studio handler
const response = await studioHandler(ctx);
console.log(`Studio response: ${response.status}`);
return response;
};
Separate HTTP Methods
You can also export individual HTTP method handlers:
// pages/api/studio/[...all].ts
import { betterAuthStudio } from 'better-auth-studio/astro';
import { auth } from '~/lib/auth';
import type { APIRoute } from 'astro';
const handler = betterAuthStudio({ auth });
export const GET: APIRoute = handler;
export const POST: APIRoute = handler;
export const PUT: APIRoute = handler;
export const DELETE: APIRoute = handler;
export const PATCH: APIRoute = handler;
Implementation Details
Request Conversion
The adapter converts Astro context objects to the universal format:
type UniversalRequest = {
url: string; // Pathname + search (with basePath stripped)
method: string; // ctx.request.method
headers: Record<string, string>; // ctx.request.headers
body?: any; // Parsed from ctx.request
};
Base Path Handling
The adapter automatically strips the base path from URLs:
// If basePath is '/api/studio'
// And request URL is '/api/studio/users'
// The universal URL will be '/users'
Content Type Handling
The adapter handles multiple content types:
application/json → ctx.request.json()application/x-www-form-urlencoded → FormData converted to objectmultipart/form-data → FormData converted to object- Other → Attempts to parse as text, then JSON
Error Handling
Errors are caught and returned as JSON responses:
{
error: "Internal server error"
}
500
Astro API Routes
ALL Handler
The ALL export handles all HTTP methods:
export const ALL: APIRoute = handler;
export const GET = handler;
export const POST = handler;
export const PUT = handler;
export const DELETE = handler;
export const PATCH = handler;
File Location
API routes must be placed in the pages/api/ directory:
pages/api/studio/[...all].ts → /api/studio/*
File Structure
project/
├── src/
│ ├── pages/
│ │ └── api/
│ │ └── studio/
│ │ └── [...all].ts
│ └── lib/
│ └── auth.ts
└── astro.config.mjs