@siteai/auth-astro

Astro shell helpers and prebuilt .astro components for SiteAI customer sites.

The intended architecture is:

• Astro owns the page shell, routing, and static markup.
• @siteai/auth-react owns authenticated behavior and UI inside hydrated islands.
• Auth-gated pages should prefer client-side protection (ProtectedPage.astro or composite *Island components), not server-side redirects or per-request auth middleware.

Compatible with Astro 4.x and 5.x.

Install

npm install @siteai/auth-astro

Wiring the integration

Add siteaiAuth() to your astro.config.mjs integrations array. This ensures @siteai/auth-react and @siteai/auth-core are pre-bundled correctly by Vite.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import { siteaiAuth } from '@siteai/auth-astro/integration';

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

Preferred pattern

For customer SiteAI sites, treat auth pages and member-only pages as Astro shell + client island/app surface.

• Public pages can stay plain Astro.
• Login / signup / account pages should mount composite islands from @siteai/auth-react.
• Simple protected pages should wrap their content in ProtectedPage.astro.

---
import ProtectedPage from '@siteai/auth-astro/ProtectedPage.astro';

const apiUrl = import.meta.env.PUBLIC_SITEAI_API_URL;
const siteId = import.meta.env.PUBLIC_SITEAI_SITE_ID;
---

<ProtectedPage apiUrl={apiUrl} siteId={siteId}>
  <main class="mx-auto max-w-4xl px-4 py-10">
    <h1>My Account</h1>
    <p>This Astro page shell stays static-friendly; auth checking happens in the client island.</p>
  </main>
</ProtectedPage>

AuthIsland.astro renders a client-side auth UI island (login / user menu). ProtectedPage.astro wraps a page and redirects unauthenticated visitors after hydration.

Legacy helpers

createAuthMiddleware and protectedRoute are still exported for compatibility, but they are deprecated as the default pattern on Cloudflare Pages because they recreate server-side first-paint auth checks.

Use them only when you are maintaining an existing site that already depends on them and you are not yet ready to migrate that route to ProtectedPage.astro or a composite @siteai/auth-react island.

Deprecated middleware example

Wire session propagation in src/middleware.ts. The middleware runs on the server, so use non-prefixed env vars — the PUBLIC_ prefix would leak the values to the browser bundle.

import { createAuthMiddleware } from '@siteai/auth-astro';

export const onRequest = createAuthMiddleware({
  apiUrl: import.meta.env.SITEAI_API_URL,
  siteId: import.meta.env.SITEAI_SITE_ID,
});

Deprecated guarded-page example:

import { protectedRoute } from '@siteai/auth-astro';

Prebuilt components

Import the .astro island components via their subpath exports. Pass apiUrl and siteId as props — these values reach the client bundle at hydration, so source them from PUBLIC_-prefixed env vars.

---
import AuthIsland from '@siteai/auth-astro/AuthIsland.astro';
import ProtectedPage from '@siteai/auth-astro/ProtectedPage.astro';

const apiUrl = import.meta.env.PUBLIC_SITEAI_API_URL;
const siteId = import.meta.env.PUBLIC_SITEAI_SITE_ID;
---

<AuthIsland apiUrl={apiUrl} siteId={siteId}>
  <slot />
</AuthIsland>

<ProtectedPage apiUrl={apiUrl} siteId={siteId} />

Environment variables

Typical setups define two pairs of variables pointing at the same underlying values:

• Server-side (middleware): SITEAI_API_URL, SITEAI_SITE_ID. Set in .env; never PUBLIC_-prefixed.
• Client-side (island components need the values at hydration): PUBLIC_SITEAI_API_URL, PUBLIC_SITEAI_SITE_ID. The PUBLIC_ prefix is how Astro/Vite exposes env vars to the browser.

Contract

Emitted by the SiteAI Auth Builder curated skill on VibeControl. The builder now emits client-side protected pages and composite auth islands by default; it should not teach createAuthMiddleware / protectedRoute(Astro) as the primary setup path.

License

MIT © BUILD3R Dev