# Civic Auth Integration Prompt for V0
## Prerequisites
Before starting, you need a Civic Auth Client ID and domain setup:
1. Visit https://auth.civic.com
2. Sign up or log in to your account
3. Create a new application to obtain your Client ID
4. Copy the Client ID for use in this integration
5. **IMPORTANT FOR V0**: Since V0 is a hosted platform, you MUST add your app's domain to Civic Auth:
- In the Civic Auth dashboard, navigate to "Domains"
- Add your V0 app's URL (e.g., https://your-app-name.vercel.app/)
- This is required because hosted platforms need domain verification for security
## Task
Stop. Do not use Supabase auth, NextAuth, or any other authentication system. Remove any existing auth dependencies and configuration files. Instead, implement authentication using Civic Auth only. Use Civic's authentication flow and API endpoints for all auth functionality including login, logout, and session management.
Add Civic Auth authentication to this Next.js application hosted on V0.
## Step 1: Get the Documentation (ABSOLUTELY REQUIRED)
**CRITICAL**: You MUST have the official documentation before proceeding.
Visit https://docs.civic.com/integration/nextjs and review the complete integration documentation using your available tools. If you cannot access the documentation, ask the user: "Please provide the content from https://docs.civic.com/integration/nextjs or paste the documentation content here."
**MANDATORY REQUIREMENTS:**
- ✅ You MUST have the complete documentation content before proceeding
- ✅ You MUST follow the documentation steps exactly as written
- ✅ Do NOT proceed until you have the documentation content
- ✅ Do NOT make assumptions about code structure or imports
**VERIFICATION REQUIRED:** After getting the documentation, you MUST confirm:
1. You have the complete Next.js integration documentation
2. You found the 4 main steps from the "Quick Start" section
3. You identified packages needed (Auth vs Auth + Web3)
4. You understand the middleware.ts file location (src/middleware.ts)
5. You found the UserButton component examples in the "Usage" section
**FALLBACK: Essential Code Structure (if documentation unavailable):**
Based on the official Next.js integration docs, use these exact code examples:
**1. next.config.ts** (PROJECT ROOT - NOT in src/):
import { createCivicAuthPlugin } from "@civic/auth/nextjs"
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
/* config options here */
};
const withCivicAuth = createCivicAuthPlugin({
clientId: "YOUR CLIENT ID"
});
export default withCivicAuth(nextConfig)
**2. src/app/api/auth/[...civicauth]/route.ts** (IN src/ directory):
import { handler } from "@civic/auth/nextjs"
export const GET = handler()
export const POST = handler()
**3. src/middleware.ts** (IN src/ directory):
import { authMiddleware } from "@civic/auth/nextjs/middleware"
export default authMiddleware();
export const config = {
matcher: [
'/((?!_next|favicon.ico|sitemap.xml|robots.txt|.*\\.jpg|.*\\.png|.*\\.svg|.*\\.gif).*)',
],
}
**4. Layout with CivicAuthProvider** (typically src/app/layout.tsx IN src/ directory):
import { CivicAuthProvider } from "@civic/auth/nextjs";
function Layout({ children }) {
return (
<CivicAuthProvider>
{children}
</CivicAuthProvider>
)
}
**5. UserButton Component:**
import { UserButton } from "@civic/auth/react";
export function TitleBar() {
return (
<div>
<h1>My App</h1>
<UserButton />
</div>
);
}
**Note:** Always prefer using the complete official documentation when available.
## Step 2: Gather Project Information
Ask the user for the following information if not provided:
**Required Information (MUST gather ALL before starting - ask user directly):**
- ✅ **Client ID** (REQUIRED - ask user: "Please provide your Civic Auth Client ID. If you don't have one, visit https://auth.civic.com to get it.")
- ✅ V0 app URL (e.g., https://your-app-name.vercel.app/) - can be added after initial implementation
- ✅ Domain registration status (can be done after deployment if URL unknown)
- ✅ Project type (new/existing Next.js project on V0)
- ✅ Web3 Support Needed (Yes/No) - This affects which imports and packages to use
- ✅ Protected routes that need authentication (e.g., /dashboard/*, /api/private/*)
- ✅ Existing authentication systems that need replacement
**DO NOT proceed with implementation until you have confirmed ALL of the above information, especially the Client ID.**
If any information is missing, ask specific questions and wait for responses before continuing. This prevents errors and ensures the integration matches the user's exact requirements.
## Step 3: Domain Registration (CRITICAL FOR V0)
V0 apps need their URLs registered with Civic Auth:
**If you already have your V0 app URL:**
1. Go to https://auth.civic.com
2. Navigate to "Domains" section
3. Add your V0 app URL (e.g., https://your-app-name.vercel.app/)
4. Save the domain registration
**If you don't have your V0 app URL yet (common for new apps):**
1. **Proceed with the implementation** - you can add the domain later
2. **When you test authentication**, you'll get a "redirect URL not found" error
3. **Copy the URL from your browser** when you get this error
4. **Go to https://auth.civic.com → Domains** and add that URL
5. **Refresh your app** - authentication should now work
## Step 4: Create Implementation Plan
After reviewing the documentation:
1. Analyze the current V0 project structure
2. Identify which code examples from the documentation apply
3. Choose the correct setup based on Web3 requirements:
- **If Web3 support needed**: Use "Auth + Web3" tab and @civic/auth-web3 packages
- **If no Web3 support**: Use "Auth" tab and @civic/auth packages
4. Plan the implementation order for V0's environment
5. Note any existing code that needs to be modified
## Step 5: Implement Civic Auth (FOLLOW DOCUMENTATION EXACTLY)
**CRITICAL**: Use ONLY the official documentation or content provided by user. Follow these steps in order:
**5.1 - Quick Start Implementation**
- Follow the "Quick Start" section from the documentation EXACTLY
- Complete ALL 4 steps: Plugin, API Route, Middleware, Frontend Integration
- Do NOT skip any steps or modify the code examples
**5.2 - Choose Correct Package**
Based on Web3 requirements from Step 2:
- **If Web3 support needed**: Use "Auth + Web3" tab (imports from @civic/auth-web3/react)
- **If no Web3 support**: Use "Auth" tab (imports from @civic/auth)
**5.3 - Implementation Order (DO NOT CHANGE)**
1. **Add the Civic Auth Plugin** (Step 1 in docs) - Configure next.config.ts
2. **Create the Civic Auth API Route** (Step 2 in docs) - Create route.ts file
3. **Middleware** (Step 3 in docs) - Create middleware.ts in src/ directory
4. **Frontend Integration** (Step 4 in docs) - Add CivicAuthProvider
5. **Add UserButton Component** - Implement the Civic UserButton for login/logout UI
**5.4 - Critical File Locations for V0 (Everything in src/ directory)**
- **Middleware**: `src/middleware.ts` (in src/ directory, NOT project root - this is essential!)
- **API Route**: `src/app/api/auth/[...civicauth]/route.ts` (in src/ directory structure)
- **Config**: `next.config.ts` (project root - only exception to src/ rule)
- **Environment**: Configure CIVIC_CLIENT_ID in V0's settings
**IMPORTANT - Next.js Directory Structure:**
- **Project Root**: `next.config.ts`, `package.json`, `tsconfig.json` (configuration files)
- **src/ Directory**: `src/middleware.ts`, `src/app/`, `src/components/`, all application code
- **API Routes**: `src/app/api/auth/[...civicauth]/route.ts`
- **Layout**: `src/app/layout.tsx` (with CivicAuthProvider)
**Rule**: Configuration files go in project root, ALL application code goes in src/
**5.5 - Code Adaptation**
- Use the EXACT code examples from the documentation (or fallback examples above if docs unavailable)
- Only adapt file paths/structure for V0's project layout
- Do NOT change imports, function names, or configuration options
- Preserve ALL code exactly as shown in the documentation
- If using fallback code, ensure the Client ID placeholder is replaced with user's actual Client ID
- **CRITICAL**: Always ask the user for their Client ID before starting implementation
## Important Notes
**DOCUMENTATION SOURCE:** https://docs.civic.com/integration/nextjs
- ✅ Use ONLY the official documentation - no web search tools
- ✅ The official documentation is the ONLY source of truth for this implementation
- ✅ All code examples, configuration options, and setup instructions are in that document
- ✅ **CRITICAL**: If Web3 support is needed, you MUST use @civic/auth-web3 packages and imports, not @civic/auth
- ✅ **V0 SPECIFIC**: Middleware file must be at `src/middleware.ts`, not project root
- ✅ **V0 SPECIFIC**: Test with actual V0 preview URLs, not localhost
- ✅ **V0 SPECIFIC**: Use Vercel environment variable configuration
**EXPECTED DOCUMENTATION CONTENT INCLUDES:**
- Quick Start with 4 steps: Plugin, API Route, Middleware, Frontend Integration
- Code examples for `next.config.ts`, `route.ts`, `src/middleware.ts`
- Import statements like `import { createCivicAuthPlugin } from "@civic/auth/nextjs"`
- Middleware configuration with proper matcher patterns
- CivicAuthProvider setup instructions
- Usage section with UserButton component examples
- Import statements like `import { UserButton } from "@civic/auth/react"`
- useUser hook examples for getting user information
If the documentation doesn't contain these elements, you must access the complete documentation.
**TROUBLESHOOTING DOCUMENTATION ACCESS:**
- If you cannot access the documentation, ask user: "Please provide the content from https://docs.civic.com/integration/nextjs"
- If user provides documentation content directly, acknowledge receipt and proceed with that content
- Do NOT proceed with implementation until you have the official documentation content
- Do NOT make assumptions about API structure or code examples
**WORKING WITH PROVIDED DOCUMENTATION:**
If the user provides the documentation content, you should:
1. Acknowledge that you received the documentation
2. Proceed with the verification requirements listed above
3. Use the provided content as your source of truth for implementation
4. Follow the exact code examples from the provided content
## CRITICAL: Middleware File Location
The middleware.ts file MUST be placed at src/middleware.ts (in the src/ directory), NOT in the project root. This is essential for V0 projects:
- ✅ CORRECT: src/middleware.ts
- ❌ WRONG: middleware.ts (project root - breaks authentication)
## V0 Environment Setup
When implementing on V0:
1. **Environment Variables**: Ensure CIVIC_CLIENT_ID is properly set in V0's environment
2. **Domain Configuration**:
- For new apps: Expect "redirect URL not found" error on first auth attempt
- Copy the URL from your browser and add it to Civic Auth domains
- For existing apps: Verify the V0 URL matches the registered domain
3. **Build Configuration**: Ensure V0's Next.js build process includes all necessary dependencies
4. **Deployment Testing**: Test authentication on both preview and production V0 URLs
## Next Steps
After completing basic authentication integration:
- **If Web3 was selected**: Use the [Solana](/ai-prompts/web3/solana) or [Ethereum](/ai-prompts/web3/ethereum) prompts to add specific wallet functionality
- **If no Web3**: Your basic authentication setup is complete
- **Production**: Ensure domain is registered in Civic Auth before going live
