create-aron-app 0.1.0 → 0.1.1

package/templates/_base/.cursor/agents/skills/clerk/clerk-custom-ui/core-3/custom-sign-up.md

@@ -0,0 +1,259 @@
+# Custom Sign-Up Flow
+
+Build a custom sign-up experience using the `useSignUp()` hook.
+
+## Hook API
+
+```typescript
+import { useSignUp } from '@clerk/nextjs' // or @clerk/react, @clerk/expo
+
+const { signUp, errors, fetchStatus } = useSignUp()
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `signUp` | `SignUpFuture` | Sign-up object with namespaced methods |
+| `errors` | `Errors<SignUpFields>` | Structured error object |
+| `fetchStatus` | `'idle' \| 'fetching'` | Network request status |
+
+## Sign-Up Methods
+
+### Password (Email/Password)
+
+```typescript
+const { error } = await signUp.password({
+  emailAddress: 'user@example.com',
+  password: 'securePassword123',
+  firstName: 'Jane',  // optional
+  lastName: 'Doe',    // optional
+})
+```
+
+### SSO (OAuth)
+
+```typescript
+const { error } = await signUp.sso({
+  strategy: 'oauth_google', // or 'oauth_github', etc.
+  redirectUrl: '/dashboard', // where to go after SSO completes
+  redirectCallbackUrl: '/sso-callback', // intermediate callback route
+})
+```
+
+### Web3
+
+```typescript
+const { error } = await signUp.web3({ strategy: 'web3_solana_signature' })
+```
+
+### Update (add fields to existing sign-up)
+
+Use `update()` to add optional fields (name, metadata, legal acceptance, locale) to an existing sign-up before finalization.
+
+```typescript
+const { error } = await signUp.update({
+  firstName: 'Jane',
+  lastName: 'Doe',
+  unsafeMetadata: { referralSource: 'twitter' },
+  legalAccepted: true,
+})
+```
+
+## Email / Phone Verification
+
+After creating a sign-up, verify the user's email or phone:
+
+### Email Code
+
+```typescript
+// Send verification code
+const { error } = await signUp.verifications.sendEmailCode()
+
+// Verify the code
+const { error } = await signUp.verifications.verifyEmailCode({ code: '123456' })
+```
+
+### Phone Code
+
+```typescript
+// Send verification code
+const { error } = await signUp.verifications.sendPhoneCode()
+
+// Verify the code
+const { error } = await signUp.verifications.verifyPhoneCode({ code: '123456' })
+```
+
+### Email Link
+
+```typescript
+// verificationUrl: where the user lands after clicking the email link (relative or absolute)
+const { error } = await signUp.verifications.sendEmailLink({ verificationUrl: '/verify' })
+// User clicks the link in their email to verify
+```
+
+## Finalizing Sign-Up
+
+After successful sign-up and verification, call `finalize()` to activate the session:
+
+```typescript
+await signUp.finalize({
+  navigate: async ({ session, decorateUrl }) => {
+    const destination = session.currentTask
+      ? `/sign-up/tasks/${session.currentTask.key}`
+      : '/'
+    const url = decorateUrl(destination)
+    // decorateUrl may return an absolute URL for Safari ITP
+    if (url.startsWith('http')) {
+      window.location.href = url
+    } else {
+      router.push(url)
+    }
+  },
+})
+```
+
+### Transferable Sign-Ups
+
+If `signUp.isTransferable` is `true`, the identifier matches an existing user and the sign-up should be transferred to a sign-in flow. This involves coordinating between sign-up and sign-in resources. See the [transferable sign-up docs](https://clerk.com/docs/custom-flows/overview) for the full implementation.
+
+### Reset State
+
+Clear local sign-up state and start over:
+
+```typescript
+signUp.reset()
+```
+
+## Error Handling
+
+All methods return `Promise<{ error: ClerkError | null }>`. Errors are also available reactively on the hook:
+
+```typescript
+const { signUp, errors } = useSignUp()
+
+// Field-level errors
+errors?.fields?.emailAddress // { code, message, longMessage? }
+errors?.fields?.password     // { code, message, longMessage? }
+errors?.fields?.firstName    // { code, message, longMessage? }
+errors?.fields?.lastName     // { code, message, longMessage? }
+errors?.fields?.phoneNumber  // { code, message, longMessage? }
+errors?.fields?.username     // { code, message, longMessage? }
+errors?.fields?.code         // { code, message, longMessage? }
+
+// Global errors
+errors?.global // ClerkGlobalHookError[] | null
+
+// Raw error array
+errors?.raw // ClerkError[] | null
+```
+
+## Complete Example: Phone OTP Sign-Up
+
+From [the docs](https://clerk.com/docs/guides/development/custom-flows/authentication/email-sms-otp). Uses phone OTP with inline comments for adapting to email OTP.
+
+```tsx
+'use client'
+
+import * as React from 'react'
+import { useAuth, useSignUp } from '@clerk/nextjs'
+import { useRouter } from 'next/navigation'
+
+export default function SignUpPage() {
+  const { signUp, errors, fetchStatus } = useSignUp()
+  const { isSignedIn } = useAuth()
+  const router = useRouter()
+
+  const handleSubmit = async (formData: FormData) => {
+    // For email OTP: collect the email address instead of the phone number
+    const phoneNumber = formData.get('phoneNumber') as string
+
+    // For email OTP: change create({ phoneNumber }) to create({ emailAddress })
+    const error = await signUp.create({ phoneNumber })
+
+    // For email OTP: change sendPhoneCode() to sendEmailCode()
+    if (!error) await signUp.verifications.sendPhoneCode()
+  }
+
+  const handleVerify = async (formData: FormData) => {
+    const code = formData.get('code') as string
+
+    // For email OTP: change verifyPhoneCode() to verifyEmailCode()
+    await signUp.verifications.verifyPhoneCode({ code })
+
+    if (signUp.status === 'complete') {
+      await signUp.finalize({
+        navigate: ({ session, decorateUrl }) => {
+          if (session?.currentTask) {
+            // Handle pending session tasks
+            // See https://clerk.com/docs/guides/development/custom-flows/authentication/session-tasks
+            console.log(session?.currentTask)
+            return
+          }
+
+          const url = decorateUrl('/')
+          if (url.startsWith('http')) {
+            window.location.href = url
+          } else {
+            router.push(url)
+          }
+        },
+      })
+    }
+  }
+
+  if (signUp.status === 'complete' || isSignedIn) {
+    return null
+  }
+
+  if (
+    signUp.status === 'missing_requirements' &&
+    // For email OTP: check for phone_number instead of email_address
+    signUp.unverifiedFields.includes('phone_number') &&
+    signUp.missingFields.length === 0
+  ) {
+    return (
+      <>
+        <h1>Verify your account</h1>
+        <form action={handleVerify}>
+          <div>
+            <label htmlFor="code">Code</label>
+            <input id="code" name="code" type="text" />
+          </div>
+          {errors.fields.code && <p>{errors.fields.code.message}</p>}
+          <button type="submit" disabled={fetchStatus === 'fetching'}>
+            Verify
+          </button>
+        </form>
+        {/* For email OTP: change sendPhoneCode() to sendEmailCode() */}
+        <button onClick={() => signUp.verifications.sendPhoneCode()}>I need a new code</button>
+      </>
+    )
+  }
+
+  return (
+    <>
+      <h1>Sign up</h1>
+      <form action={handleSubmit}>
+        {/* For email OTP: collect the emailAddress instead */}
+        <div>
+          <label htmlFor="phoneNumber">Phone number</label>
+          <input id="phoneNumber" name="phoneNumber" type="tel" />
+          {errors.fields.phoneNumber && <p>{errors.fields.phoneNumber.message}</p>}
+        </div>
+        <button type="submit" disabled={fetchStatus === 'fetching'}>
+          Continue
+        </button>
+      </form>
+      {errors && <p>{JSON.stringify(errors, null, 2)}</p>}
+
+      {/* Required for sign-up flows. Clerk's bot sign-up protection is enabled by default */}
+      <div id="clerk-captcha" />
+    </>
+  )
+}
+```
+
+## Docs
+
+- [Custom sign-up flow](https://clerk.com/docs/custom-flows/overview)
+- [Email/phone OTP custom flow](https://clerk.com/docs/guides/development/custom-flows/authentication/email-sms-otp)
+- [useSignUp() reference](https://clerk.com/docs/references/react/use-sign-up)

package/templates/_base/.cursor/agents/skills/clerk/clerk-custom-ui/core-3/show-component.md

@@ -0,0 +1,125 @@
+# `<Show>` Component
+
+The `<Show>` component conditionally renders content based on authentication state, roles, permissions, billing plans, and features.
+
+> **Core 2 ONLY (skip if current SDK):** The `<Show>` component does not exist in Core 2. Use `<SignedIn>`, `<SignedOut>`, and `<Protect>` instead. See migration table below.
+
+## Import
+
+```typescript
+import { Show } from '@clerk/nextjs'       // Next.js
+import { Show } from '@clerk/react'         // React
+import { Show } from '@clerk/react-router'  // React Router
+import { Show } from '@clerk/expo'          // Expo
+```
+
+## Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `when` | `string \| object \| function` | Condition for rendering children |
+| `fallback?` | `ReactNode` | Content shown when condition fails |
+| `treatPendingAsSignedOut?` | `boolean` | Treat pending sessions as signed-out (default: `true`) |
+
+## `when` Prop Variants
+
+### Authentication State
+
+```tsx
+// Show content only when signed in
+<Show when="signed-in">
+  <p>Welcome back!</p>
+</Show>
+
+// Show content only when signed out
+<Show when="signed-out">
+  <p>Please sign in.</p>
+</Show>
+```
+
+### Role Check
+
+```tsx
+<Show when={{ role: 'org:admin' }}>
+  <AdminPanel />
+</Show>
+```
+
+### Permission Check
+
+```tsx
+<Show when={{ permission: 'org:billing:manage' }}>
+  <BillingSettings />
+</Show>
+```
+
+### Billing Feature Check
+
+```tsx
+<Show when={{ feature: 'widgets' }}>
+  <WidgetBuilder />
+</Show>
+```
+
+### Billing Plan Check
+
+```tsx
+<Show when={{ plan: 'gold' }}>
+  <PremiumContent />
+</Show>
+```
+
+### Custom Condition (Function)
+
+```tsx
+<Show when={(has) => has({ role: 'org:admin' }) || has({ permission: 'org:billing:manage' })}>
+  <SettingsPanel />
+</Show>
+```
+
+## Fallback Content
+
+Show alternative content when the condition fails:
+
+```tsx
+<Show when="signed-in" fallback={<p>Please sign in to continue.</p>}>
+  <Dashboard />
+</Show>
+```
+
+## Session Tasks and Pending State
+
+The `treatPendingAsSignedOut` prop controls how pending sessions (sessions with incomplete tasks) are handled:
+
+```tsx
+// Default: pending sessions are treated as signed-out
+<Show when="signed-in" treatPendingAsSignedOut>
+  <Dashboard />
+</Show>
+
+// Treat pending sessions as signed-in (e.g., to show task completion UI)
+<Show when="signed-in" treatPendingAsSignedOut={false}>
+  <TaskCompletionFlow />
+</Show>
+```
+
+## Security Caveat
+
+**`<Show>` only visually hides content** — it remains in browser source. It is not a security boundary. For protecting sensitive data, always verify authentication server-side with `auth()` or use `auth.protect()` in middleware.
+
+## Migration from Core 2
+
+| Core 2 | Current |
+|--------|---------|
+| `<SignedIn>` | `<Show when="signed-in">` |
+| `<SignedOut>` | `<Show when="signed-out">` |
+| `<Protect role="org:admin">` | `<Show when={{ role: 'org:admin' }}>` |
+| `<Protect permission="org:billing:manage">` | `<Show when={{ permission: 'org:billing:manage' }}>` |
+| `<Protect condition={(has) => expr}>` | `<Show when={(has) => expr}>` |
+| `<Protect fallback={...}>` | `<Show when={...} fallback={...}>` |
+| *(no equivalent)* | `<Show when={{ feature: 'widgets' }}>` |
+| *(no equivalent)* | `<Show when={{ plan: 'gold' }}>` |
+
+## Docs
+
+- [Show component reference](https://clerk.com/docs/components/control/show)

package/templates/_base/.cursor/agents/skills/clerk/clerk-nextjs-patterns/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: clerk-nextjs-patterns
+description: Advanced Next.js patterns - middleware, Server Actions, caching with Clerk.
+license: MIT
+allowed-tools: WebFetch
+metadata:
+  author: clerk
+  version: "2.1.0"
+---
+
+# Next.js Patterns
+
+> **Version**: Check `package.json` for the SDK version — see `clerk` skill for the version table. Core 2 differences are noted inline with `> **Core 2 ONLY (skip if current SDK):**` callouts.
+
+For basic setup, see `setup/`.
+
+## Impact Levels
+
+- **CRITICAL** - Breaking bugs, security holes
+- **HIGH** - Common mistakes
+- **MEDIUM** - Optimization
+
+## References
+
+| Reference | Impact |
+|-----------|--------|
+| `references/server-vs-client.md` | CRITICAL - `await auth()` vs hooks |
+| `references/middleware-strategies.md` | HIGH - Public-first vs protected-first, `proxy.ts` (Next.js <=15: `middleware.ts`) |
+| `references/server-actions.md` | HIGH - Protect mutations |
+| `references/api-routes.md` | HIGH - 401 vs 403 |
+| `references/caching-auth.md` | MEDIUM - User-scoped caching |
+
+## Mental Model
+
+Server vs Client = different auth APIs:
+- **Server**: `await auth()` from `@clerk/nextjs/server` (async!)
+- **Client**: `useAuth()` hook from `@clerk/nextjs` (sync)
+
+Never mix them. Server Components use server imports, Client Components use hooks.
+
+Key properties from `auth()`:
+- `isAuthenticated` — boolean, replaces the `!!userId` pattern
+- `sessionStatus` — `'active'` | `'pending'`, for detecting incomplete session tasks
+- `userId`, `orgId`, `orgSlug`, `has()`, `protect()` — unchanged
+
+> **Core 2 ONLY (skip if current SDK):** `isAuthenticated` and `sessionStatus` are not available. Check `!!userId` instead.
+
+## Minimal Pattern
+
+```typescript
+// Server Component
+import { auth } from '@clerk/nextjs/server'
+
+export default async function Page() {
+  const { isAuthenticated, userId } = await auth()  // MUST await!
+  if (!isAuthenticated) return <p>Not signed in</p>
+  return <p>Hello {userId}</p>
+}
+```
+
+> **Core 2 ONLY (skip if current SDK):** `isAuthenticated` is not available. Use `if (!userId)` instead.
+
+### Conditional Rendering with `<Show>`
+
+For client-side conditional rendering based on auth state:
+
+```tsx
+import { Show } from '@clerk/nextjs'
+
+<Show when="signed-in" fallback={<p>Please sign in</p>}>
+  <Dashboard />
+</Show>
+```
+
+> **Core 2 ONLY (skip if current SDK):** Use `<SignedIn>` and `<SignedOut>` components instead of `<Show>`. See `custom-ui/core-3/show-component.md` for the full migration table.
+
+## Common Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `undefined` userId in Server Component | Missing `await` | `await auth()` not `auth()` |
+| Auth not working on API routes | Missing matcher | Add `'/(api|trpc)(.*)'` to `proxy.ts` (Next.js <=15: `middleware.ts`) |
+| Cache returns wrong user's data | Missing userId in key | Include `userId` in `unstable_cache` key |
+| Mutations bypass auth | Unprotected Server Action | Check `auth()` at start of action |
+| Wrong HTTP error code | Confused 401/403 | 401 = not signed in, 403 = no permission |
+
+## See Also
+
+- `setup/`
+- `orgs/`
+
+## Docs
+
+[Next.js SDK](https://clerk.com/docs/reference/nextjs/overview)

package/templates/_base/.cursor/agents/skills/clerk/clerk-nextjs-patterns/references/api-routes.md

@@ -0,0 +1,50 @@
+# API Routes (HIGH)
+
+## Auth Check Pattern
+
+```typescript
+import { auth } from '@clerk/nextjs/server';
+
+export async function GET() {
+  const { isAuthenticated, userId } = await auth();
+  if (!isAuthenticated) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+  const data = await db.data.findMany({ where: { userId } });
+  return Response.json(data);
+}
+```
+
+> **Core 2 ONLY (skip if current SDK):** `isAuthenticated` is not available. Use `if (!userId)` instead.
+
+## 401 vs 403
+
+- **401** - Not authenticated
+- **403** - Authenticated but lacks permission
+
+```typescript
+export async function DELETE(req: Request) {
+  const { isAuthenticated, has } = await auth();
+  if (!isAuthenticated) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const isAdmin = await has({ role: 'org:admin' });
+  if (!isAdmin) return Response.json({ error: 'Forbidden' }, { status: 403 });
+
+  return Response.json({ success: true });
+}
+```
+
+## Org Route Protection
+
+```typescript
+export async function GET(req: Request, { params }: { params: { orgId: string } }) {
+  const { userId, orgId } = await auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  if (orgId !== params.orgId) return Response.json({ error: 'Forbidden' }, { status: 403 });
+
+  const orgData = await db.orgs.findUnique({ where: { id: orgId } });
+  return Response.json(orgData);
+}
+```
+
+[Docs](https://clerk.com/docs/reference/nextjs/auth)

package/templates/_base/.cursor/agents/skills/clerk/clerk-nextjs-patterns/references/caching-auth.md

@@ -0,0 +1,56 @@
+# Caching with Auth (CRITICAL)
+
+**CRITICAL**: Cache keys MUST include userId/orgId to prevent data leaking between users.
+
+## User-Scoped Cache
+
+```typescript
+import { auth } from '@clerk/nextjs/server';
+import { unstable_cache } from 'next/cache';
+
+export default async function ProfilePage() {
+  const { userId } = await auth();
+  if (!userId) return <div>Not signed in</div>;
+
+  const cachedGetUserData = unstable_cache(
+    () => getUserData(userId),
+    [`user-${userId}`],
+    { revalidate: 60, tags: [`user-${userId}`] }
+  );
+
+  const userData = await cachedGetUserData();
+  return <div>{userData.name}</div>;
+}
+```
+
+## Revalidate After Updates
+
+```typescript
+'use server';
+import { revalidateTag } from 'next/cache';
+import { auth } from '@clerk/nextjs/server';
+
+export async function updateProfile(formData: FormData) {
+  const { userId } = await auth();
+  if (!userId) throw new Error('Unauthorized');
+
+  await db.users.update({
+    where: { id: userId },
+    data: { name: formData.get('name') as string },
+  });
+  revalidateTag(`user-${userId}`);
+}
+```
+
+## Org-Scoped Cache
+
+```typescript
+const { orgId } = await auth();
+const getOrgData = unstable_cache(
+  () => db.orgData.findMany({ where: { organizationId: orgId } }),
+  [`org-${orgId}-data`],
+  { revalidate: 300, tags: [`org-${orgId}`] }
+);
+```
+
+[Docs](https://nextjs.org/docs/app/building-your-application/caching)

package/templates/_base/.cursor/agents/skills/clerk/clerk-nextjs-patterns/references/middleware-strategies.md

@@ -0,0 +1,68 @@
+# Middleware Strategies (HIGH)
+
+> **Filename:** `proxy.ts` (Next.js <=15: `middleware.ts`). The code is identical; only the filename changes.
+
+## Public-First (marketing sites, blogs)
+
+Protect specific routes, allow everything else:
+
+```typescript
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = createRouteMatcher([
+  '/dashboard(.*)',
+  '/settings(.*)',
+  '/api/private(.*)',
+]);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (isProtectedRoute(req)) await auth.protect();
+});
+
+export const config = {
+  matcher: [
+    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
+    '/(api|trpc)(.*)',
+  ],
+};
+```
+
+## Protected-First (internal tools, dashboards)
+
+Block everything, allow specific public routes:
+
+```typescript
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher([
+  '/',
+  '/sign-in(.*)',
+  '/sign-up(.*)',
+  '/api/public(.*)',
+]);
+
+export default clerkMiddleware(async (auth, req) => {
+  if (!isPublicRoute(req)) await auth.protect();
+});
+```
+
+## Session Tasks
+
+When session tasks are enabled (e.g., forced password reset, MFA setup), users may have a `pending` session status. You can handle this in middleware:
+
+```typescript
+export default clerkMiddleware(async (auth, req) => {
+  const { sessionStatus } = await auth();
+
+  // Redirect pending sessions to task completion page
+  if (sessionStatus === 'pending') {
+    return NextResponse.redirect(new URL('/sign-in/tasks', req.url));
+  }
+
+  if (isProtectedRoute(req)) await auth.protect();
+});
+```
+
+> **Core 2 ONLY (skip if current SDK):** `sessionStatus` is not available. Session tasks do not exist in Core 2.
+
+[Docs](https://clerk.com/docs/reference/nextjs/clerk-middleware)