auth-setup

Auth Setup

Production-ready authentication for any web app in under 45 minutes. 2 auth providers (Better Auth & Firebase), Google OAuth, copy-paste UI components, and a verification script. GitHub & Apple OAuth coming soon.

When to Use

• Starting a new project needing user authentication
• Adding auth to an existing app (auto-detects and adapts to existing theme)
• Migrating between auth providers
• Setting up OAuth social login (Google, GitHub, Apple)
• Need login/register page components

CRITICAL — New Project Scaffolding

If scaffolding a new Next.js project, never run create-next-app . in the current directory. Claude Code plugins (OMC, gstack) create dotfiles (.omc/, .claude/) that conflict with create-next-app, which requires a completely empty directory. The dotfiles are recreated by hooks between deletion and scaffolding, causing an infinite failure loop.

Correct pattern — scaffold in /tmp, pin to Next.js 14:

SCAFFOLD_DIR=/tmp/nextjs-scaffold-$RANDOM && \
npx create-next-app@14 "$SCAFFOLD_DIR" \
  --typescript --tailwind --eslint --app --src-dir \
  --import-alias "@/*" --use-npm --no-turbopack && \
cp -a "$SCAFFOLD_DIR"/. . && rm -rf "$SCAFFOLD_DIR"

Why @14 not @latest? Next.js 16 deprecated middleware.ts in favor of proxy.ts. All templates, guides, and middleware examples in this plugin use the middleware.ts convention (Next.js 14/15). Using @latest will install Next.js 16+ and the build will fail. See pitfall #37 for details.

Or scaffold into a named subdirectory, then move files up.

shadcn/ui: Use npx [email protected] init -d (NOT shadcn@2 or shadcn@latest). [email protected]+ expects Tailwind v4's CSS-based config and fails with Next.js 14's tailwind.config.ts. After shadcn init, you MUST install tailwindcss-animate — shadcn adds it to tailwind.config.ts but does NOT auto-install it: {pm} install tailwindcss-animate (use package manager detected in Step 0). See pitfall #44.

Provider Decision Framework