FAQs

Answers to common questions about StarterApp implementation, AI-assisted development workflows, and architectural decisions.

General Questions

What is StarterApp?

StarterApp provides a production-ready foundation for SaaS applications built with Next.js 15. The codebase includes authentication, billing, security, and real-time data synchronization with AI-assisted development patterns.

Core technologies:

• Next.js 15 with App Router and Server Components
• TypeScript with strict mode configuration
• Convex for real-time data synchronization
• BetterAuth for authentication flows
• UseAutumn for Stripe billing integration
• Tailwind CSS for styling
• Turborepo for monorepo management

How does AI development work with StarterApp?

The codebase implements context engineering through configuration files that provide architectural patterns to AI agents:

• .cursor/rules/core.mdc: Cursor IDE context
• .windsurfrules: Windsurf IDE context
• .github/copilot-instructions.md: GitHub Copilot context
• CLAUDE.md: Claude Code context
• AGENTS.md: General AI agent context

These files instruct AI agents to read /llms/CORE.md, which loads architecture documentation, security patterns, and template references. The /llms/templates/ directory contains production-tested implementations for authentication, billing, API routes, and testing patterns.

AI agents generate code following StarterApp conventions through automatic pattern application. The validation pipeline (pnpm validate) catches deviations through type checking, linting, and tests.

Why use a starter kit instead of building from scratch?

Production infrastructure implementation requires significant development time. Authentication needs password hashing, session management, OAuth flows, and email verification. Billing requires webhook handling, subscription state management, and feature gating. Security demands CSRF protection, Content Security Policy headers, and rate limiting.

System integration multiplies complexity. Authentication connects to billing for feature access. Security wraps all endpoints. Error handling applies throughout. Testing covers integration points. A starter kit provides these implementations immediately.

Why choose StarterApp over other starter kits?

StarterApp differentiates through AI-first architecture. Context engineering files, template libraries, and validation pipelines enable AI agents to implement features without extensive prompting.

The codebase uses current patterns: Next.js 15 with App Router, React Server Components, and latest TypeScript features. The monorepo structure provides clear boundaries and type safety.

Security implementation follows established practices: CSRF protection on state-changing operations, Content Security Policy with nonce-based enforcement for the dashboard, rate limiting at edge and business logic layers.

Development Questions

What is the AI workflow for adding features?

Feature implementation follows a structured workflow:

The workflow ensures AI-generated code matches production patterns.

How do I add a protected page with AI?

Request protected page creation through natural language:

Create a user settings page following llms/templates/auth-page-template.tsx

The AI generates code including:

• Cache-disabling exports (revalidate = 0, dynamic = 'force-dynamic', fetchCache = 'force-no-store')
• Authentication check via getCurrentSession() or requireUser()
• Redirect to sign-in for unauthenticated users
• Proper metadata configuration

Validation confirms pattern adherence:

pnpm typecheck && pnpm lint

What if AI generates incorrect code?

The validation pipeline catches errors through multiple layers:

# Type safety
pnpm typecheck

# Code quality
pnpm lint

# Test execution
pnpm test

# Build verification
pnpm build

# Run all checks
pnpm validate

TypeScript compilation failures indicate type errors or incorrect API usage. Ultracite reports pattern violations and code quality issues. Tests verify behavior and security requirements. The AI uses error messages to correct implementation automatically.

Which AI agent should I use?

Agent selection depends on development workflow preferences:

Claude Code:

• Native slash commands in .claude/commands
• Pre-configured workflows for architecture, debugging, PRP generation
• Best for structured development with explicit command execution

Cursor:

• Composer mode for multi-file editing
• Custom rules via .cursor/rules/core.mdc
• Best for rapid iteration with inline AI assistance

GitHub Copilot:

• Inline completions with custom instructions
• Chat participants (@workspace, @terminal)
• Best for developers already using GitHub ecosystem

Windsurf:

• Cascade multi-file editing
• Standalone AI-native IDE
• Best for developers wanting integrated AI experience

All agents read StarterApp context automatically.

Troubleshooting

Authentication not working

Symptoms: Sign-in fails or redirects incorrectly

Solution: Verify OAuth configuration:

1. Check Google Cloud Console redirect URI matches: http://localhost:3000/api/auth/callback/google
2. Confirm GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env.local
3. Ensure BETTER_AUTH_SECRET has at least 32 characters

Sync to Convex:

pnpm convex:env

Convex connection failed

Symptoms: Application displays Convex connection errors

Solution: Verify environment variables:

1. Check .env.local contains NEXT_PUBLIC_CONVEX_URL
2. Confirm URL format: https://xxx-xxx-000.convex.cloud
3. Verify deployment exists in Convex Dashboard

Test connection:

npx convex dev

Module not found errors

Symptoms: Import statements show "Cannot find module @workspace/..."

Solution: Verify workspace dependencies are installed:

# Clean and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Ensure TypeScript recognizes workspace paths:

pnpm typecheck

Related Documentation