create-ab-app 0.1.1

package/template/src/routes/docs/structure.tsx

@@ -0,0 +1,150 @@
+import {
+  Cell,
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Row,
+  Section,
+  Table,
+} from "@/components/docs/doc-primitives"
+
+export default function StructurePage() {
+  return (
+    <DocPage
+      title="Project structure"
+      summary="Where things live and which folder owns what."
+    >
+      <Section>
+        <CodeBlock>{`src/
+  config/
+    env.ts            Every environment value, plus the preflight check
+    navigation.ts     The sidebar, as data
+  lib/
+    sso/              Auth + billing. The only folder that imports the SDK
+    http.ts           Client for your own API (bearer + 401 handling)
+    utils.ts          cn()
+  components/
+    ui/               shadcn primitives
+    docs/             Building blocks for these documentation pages
+    layouts/
+      app-layout.tsx  Sidebar shell for authenticated routes
+    app-sidebar.tsx   Sidebar composition
+    nav-main.tsx      Nav group, entitlement-aware
+    nav-user.tsx      Sidebar user menu
+    header-user.tsx   Header user menu (same items)
+    user-menu.tsx     Shared menu pieces
+    theme-toggle.tsx  Light / dark / system
+  hooks/
+    use-user-identity.ts
+  routes/
+    docs/             These pages
+    app/example.tsx   Live data example
+    auth/             One-line wrappers over the SDK screens
+  styles/
+    aas-theme.css     Maps SDK tokens onto shadcn tokens
+  App.tsx             Route map
+  main.tsx            Providers`}</CodeBlock>
+      </Section>
+
+      <Section title="Inside src/lib/sso">
+        <P>
+          This is the important folder. Everything the SDK needs is bound here so
+          the rest of the app stays plain React.
+        </P>
+        <Table head={["File", "Responsibility"]}>
+          <Row>
+            <Cell>
+              <Code>config.ts</Code>
+            </Cell>
+            <Cell>
+              The three SDK inputs, bound once. Spread <Code>ssoProps</Code> into any
+              SDK component.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>token-store.ts</Code>
+            </Cell>
+            <Cell>
+              The only place that touches token storage. Cross-tab aware; falls back
+              to memory when storage is blocked.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>auth-provider.tsx</Code>
+            </Cell>
+            <Cell>
+              Owns the token app-wide. Pairs with <Code>auth-context.ts</Code>, which
+              exports <Code>useAuth()</Code>.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>auth-screens.tsx</Code>
+            </Cell>
+            <Cell>
+              The SDK's Login / Signup / ForgotPassword / VerifyEmail, bound to
+              config, token store and router.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>protected-route.tsx</Code>
+            </Cell>
+            <Cell>
+              <Code>ProtectedRoute</Code> and <Code>PublicOnlyRoute</Code>.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>queries.ts</Code>
+            </Cell>
+            <Cell>
+              Cached, pre-bound useProfile / useWallet / useCreditWallets /
+              useRawSubscription.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>entitlements.ts</Code>
+            </Cell>
+            <Cell>
+              Normalises the raw /subscription payload into something checkable.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>require-plan.tsx</Code>
+            </Cell>
+            <Cell>Per-feature gate component.</Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>account-settings.tsx</Code>
+            </Cell>
+            <Cell>
+              Opens the SDK's Account Settings modal — the billing surface.
+            </Cell>
+          </Row>
+          <Row>
+            <Cell>
+              <Code>index.ts</Code>
+            </Cell>
+            <Cell>The barrel. This is what the rest of the app imports.</Cell>
+          </Row>
+        </Table>
+      </Section>
+
+      <Section title="Why the barrel matters">
+        <Note>
+          Product code imports <Code>@/lib/sso</Code>. If you ever swap the auth
+          provider, or the SDK changes its signatures, the blast radius is this one
+          folder instead of every component that happened to call it.
+        </Note>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/docs/theming.tsx

@@ -0,0 +1,88 @@
+import {
+  Code,
+  CodeBlock,
+  DocPage,
+  Note,
+  P,
+  Section,
+} from "@/components/docs/doc-primitives"
+
+export default function ThemingPage() {
+  return (
+    <DocPage
+      title="UI & theming"
+      summary="shadcn/ui, the SDK's own stylesheet, and how the two are kept in sync."
+    >
+      <Section title="Components">
+        <P>
+          shadcn/ui with the <Code>sidebar-07</Code> block as the app shell. Blocks
+          are installed once and then owned by you —{" "}
+          <Code>npx shadcn@latest add sidebar-07</Code> overwrites{" "}
+          <Code>app-sidebar.tsx</Code> and friends, so never re-run it against
+          customised files.
+        </P>
+        <P>
+          The block's team switcher was dropped (one project per app) and its nav
+          data replaced by <Code>src/config/navigation.ts</Code>. The user menu is
+          shared between the sidebar footer and the header via{" "}
+          <Code>user-menu.tsx</Code>, so both stay in sync.
+        </P>
+      </Section>
+
+      <Section title="Two stylesheets, one theme">
+        <P>
+          The SDK's CSS is scoped (<Code>[data-aas]</Code>, an <Code>sso:</Code>{" "}
+          utility prefix) and shipped <em>unlayered</em>. That means it cannot leak
+          into your app and your Tailwind preflight cannot override it — but it also
+          means it will not inherit your theme. So the tokens are mapped explicitly:
+        </P>
+        <CodeBlock>{`/* src/styles/aas-theme.css */
+:root,
+.dark {
+  --aas-primary: var(--primary);
+  --aas-background: var(--background);
+  --aas-border: var(--border);
+  --aas-radius: var(--radius);
+  /* … */
+}`}</CodeBlock>
+        <Note tone="warn" title="Import order matters">
+          Tailwind first, then <Code>ab-ecosystem-sso/styles.css</Code>, then the
+          bridge. Both selectors are declared so the mapping resolves against
+          whichever element carries the active palette.
+        </Note>
+      </Section>
+
+      <Section title="Overriding SDK styles">
+        <P>
+          Because the SDK's CSS is unlayered, a plain Tailwind utility of equal
+          specificity loses to it. Use the important modifier:
+        </P>
+        <CodeBlock>{`// src/lib/sso/auth-screens.tsx
+const authClassNames = { card: "max-w-sm!" }   // narrows the SDK's max-w-md`}</CodeBlock>
+        <P>
+          Each screen also accepts <Code>root</Code>, <Code>button</Code>,{" "}
+          <Code>input</Code>, <Code>label</Code>, <Code>link</Code>,{" "}
+          <Code>logo</Code>, <Code>error</Code> and more.
+        </P>
+      </Section>
+
+      <Section title="Dark mode">
+        <P>
+          <Code>next-themes</Code> with <Code>attribute="class"</Code> toggles{" "}
+          <Code>.dark</Code> on the root element, which is what both the shadcn
+          tokens and the bridge above key off. The header toggle offers light, dark
+          and system. Because the bridge is theme-aware, the SDK's auth screens and
+          Account Settings modal follow along.
+        </P>
+      </Section>
+
+      <Section title="Notifications">
+        <P>
+          Sonner, mounted in <Code>main.tsx</Code>. Auth toasts all fire from{" "}
+          <Code>auth-screens.tsx</Code> under a single toast id, so a retry replaces
+          the previous notification instead of stacking a second one.
+        </P>
+      </Section>
+    </DocPage>
+  )
+}

package/template/src/routes/not-found.tsx

@@ -0,0 +1,12 @@
+import { Link } from "react-router-dom"
+
+import { Button } from "@/components/ui/button"
+
+export default function NotFoundPage() {
+  return (
+    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
+      <p className="text-muted-foreground text-sm">404 — page not found</p>
+      <Button render={<Link to="/" />}>Back to dashboard</Button>
+    </div>
+  )
+}

package/template/src/styles/aas-theme.css

@@ -0,0 +1,21 @@
+/**
+ * Maps the SDK's --aas-* variables onto the shadcn tokens so its screens and
+ * modal match the app. Declared on both selectors so the mapping resolves
+ * against whichever element carries the active palette.
+ */
+:root,
+.dark {
+  --aas-primary: var(--primary);
+  --aas-primary-foreground: var(--primary-foreground);
+  --aas-background: var(--background);
+  --aas-foreground: var(--foreground);
+  --aas-card: var(--card);
+  --aas-card-foreground: var(--card-foreground);
+  --aas-muted: var(--muted);
+  --aas-muted-foreground: var(--muted-foreground);
+  --aas-border: var(--border);
+  --aas-input: var(--input);
+  --aas-ring: var(--ring);
+  --aas-destructive: var(--destructive);
+  --aas-radius: var(--radius);
+}

package/template/src/vite-env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_AUTH_PROJECT_ID: string
+  readonly VITE_AUTH_API_BASE_URL?: string
+  readonly VITE_API_BASE_URL?: string
+  readonly VITE_APP_NAME?: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/template/tsconfig.app.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+
+    /* Paths */
+    "paths": { "@/*": ["./src/*"] },
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/template/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ],
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

package/template/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/template/vercel.json

@@ -0,0 +1,3 @@
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
+}

package/template/vite.config.ts

@@ -0,0 +1,17 @@
+import path from "node:path"
+import tailwindcss from "@tailwindcss/vite"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      "@": path.resolve(import.meta.dirname, "./src"),
+    },
+  },
+  server: {
+    port: 5173,
+  },
+})

package/variants/minimal/src/App.tsx

@@ -0,0 +1,43 @@
+import { Navigate, Route, Routes } from "react-router-dom"
+
+import { AppLayout } from "@/components/layouts/app-layout"
+import { ProtectedRoute, PublicOnlyRoute } from "@/lib/sso"
+import ForgotPasswordPage from "@/routes/auth/forgot-password"
+import LoginPage from "@/routes/auth/login"
+import SignupPage from "@/routes/auth/signup"
+import VerifyEmailPage from "@/routes/auth/verify-email"
+import HomePage from "@/routes/app/home"
+import NotFoundPage from "@/routes/not-found"
+
+export default function App() {
+  return (
+    <Routes>
+      {/* Auth — no layout wrapper: each SDK screen renders its own centered page. */}
+      <Route element={<PublicOnlyRoute />}>
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="/signup" element={<SignupPage />} />
+        <Route path="/forgot-password" element={<ForgotPasswordPage />} />
+      </Route>
+
+      {/*
+        Emailed links. Not behind PublicOnlyRoute: a user who just signed up is
+        already signed in, and must still be able to verify or reset.
+      */}
+      <Route path="/reset-password/:token" element={<ForgotPasswordPage />} />
+      <Route path="/verify/:token" element={<VerifyEmailPage />} />
+      {/* Aliases for links that carry the token as ?token= instead. */}
+      <Route path="/reset-password" element={<ForgotPasswordPage />} />
+      <Route path="/verify-email" element={<VerifyEmailPage />} />
+
+      {/* Add enforceActiveSubscription for a hard paywall on the whole shell. */}
+      <Route element={<ProtectedRoute />}>
+        <Route element={<AppLayout />}>
+          <Route path="/" element={<HomePage />} />
+        </Route>
+      </Route>
+
+      <Route path="/404" element={<NotFoundPage />} />
+      <Route path="*" element={<Navigate to="/404" replace />} />
+    </Routes>
+  )
+}

package/variants/minimal/src/components/app-sidebar.tsx

@@ -0,0 +1,50 @@
+import * as React from "react"
+import { Link } from "react-router-dom"
+import { GalleryVerticalEndIcon } from "lucide-react"
+
+import { NavMain } from "@/components/nav-main"
+import { NavUser } from "@/components/nav-user"
+import { CreditBalance } from "@/components/credit-balance"
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+} from "@/components/ui/sidebar"
+import { env } from "@/config/env"
+import { navMain } from "@/config/navigation"
+
+export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  return (
+    <Sidebar collapsible="icon" {...props}>
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" render={<Link to="/" />}>
+              <div className="bg-primary text-primary-foreground flex aspect-square size-8 items-center justify-center rounded-lg">
+                <GalleryVerticalEndIcon className="size-4" />
+              </div>
+              <div className="grid flex-1 text-left text-sm leading-tight">
+                <span className="truncate font-medium">{env.appName}</span>
+              </div>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+
+      <SidebarContent>
+        <NavMain items={navMain} />
+      </SidebarContent>
+
+      <SidebarFooter>
+        <CreditBalance />
+        <NavUser />
+      </SidebarFooter>
+      <SidebarRail />
+    </Sidebar>
+  )
+}

package/variants/minimal/src/config/navigation.ts

@@ -0,0 +1,19 @@
+import { HomeIcon } from "lucide-react"
+
+/** Anything that renders like a Lucide icon. */
+export type IconComponent = React.ComponentType<{ className?: string }>
+
+export type NavItem = {
+  title: string
+  url: string
+  icon?: IconComponent
+  /** Item ids that unlock this entry. Omit to show it to every signed-in user. */
+  requiresIds?: string[]
+  items?: { title: string; url: string; requiresIds?: string[] }[]
+}
+
+/** The sidebar, as data. */
+export const navMain: NavItem[] = [{ title: "Home", url: "/", icon: HomeIcon }]
+
+/** Every nav entry, flattened — used for breadcrumb titles. */
+export const allNavItems: NavItem[] = [...navMain]

package/variants/minimal/src/routes/app/home.tsx

@@ -0,0 +1,45 @@
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { useAccountSettings, useEntitlements, useProfile } from "@/lib/sso"
+
+export default function HomePage() {
+  const { data: profile } = useProfile()
+  const { isActive, planId } = useEntitlements()
+  const { open } = useAccountSettings()
+
+  return (
+    <div className="mx-auto flex w-full max-w-3xl flex-col gap-6">
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">
+          Welcome{profile?.firstName ? `, ${profile.firstName}` : ""}
+        </h1>
+        <p className="text-muted-foreground text-sm">
+          Start building. Auth and billing live in <code>src/lib/sso</code>.
+        </p>
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Subscription</CardTitle>
+          <CardDescription>
+            {isActive ? `Active — ${planId}` : "No active plan"}
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <Button
+            variant={isActive ? "outline" : "default"}
+            onClick={() => open("plans")}
+          >
+            {isActive ? "Manage plan" : "Choose a plan"}
+          </Button>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}