Chameleon

Frequently Asked Questions

Common questions and answers about Chameleon

Find answers to common questions about Chameleon AI SaaS framework.

General Questions

What is Chameleon?

Chameleon is a full-stack Next.js boilerplate for building AI SaaS applications. It includes authentication, payments, AI integrations, admin dashboard, and everything you need to launch quickly.

Is Chameleon free?

Chameleon is open-source and available on GitHub. However, some cloud services used by Chameleon (like databases, AI APIs, payment processing) may have their own costs.

What technologies does Chameleon use?

  • Frontend: Next.js 15, React, TypeScript, Tailwind CSS, Shadcn UI
  • Backend: Next.js API Routes, Drizzle ORM
  • Database: PostgreSQL or MySQL
  • Auth: NextAuth.js with Google & GitHub OAuth
  • Payment: Stripe & Creem
  • AI: Vercel AI SDK with multiple providers
  • Deployment: Vercel, Cloudflare, or self-hosted

Can I use Chameleon for commercial projects?

Yes! Chameleon is designed for commercial use. You can build and sell SaaS products with it.

Installation & Setup

What are the minimum requirements?

  • Node.js 18 or later
  • pnpm (recommended) or npm
  • Git
  • A database (PostgreSQL or MySQL)

How long does setup take?

  • Basic setup: 10-15 minutes
  • With AI providers: 30-45 minutes
  • Production deployment: 1-2 hours (including domain setup, payment config, etc.)

Do I need all the cloud services?

No! For local development, you only need:

  • Database connection
  • NextAuth secret

Optional services (can be added later):

  • OAuth providers (Google, GitHub)
  • Stripe for payments
  • AI provider API keys
  • File storage
  • Analytics

Can I use MySQL instead of PostgreSQL?

Yes! Chameleon supports both. Just change your DATABASE_URL connection string.

# PostgreSQL
DATABASE_URL="postgresql://user:pass@host:5432/db"

# MySQL
DATABASE_URL="mysql://user:pass@host:3306/db"

Development

How do I add a new page?

  1. Create a new file in src/app/[locale]/(your-group)/your-page/page.tsx
  2. Export a default React component
  3. The page will automatically be available at /your-page

See Create New Page Tutorial for details.

How do I customize the landing page?

Edit the content in src/i18n/pages/landing/en.json. See the Landing Page Tutorial for step-by-step instructions.

How do I add a new AI provider?

  1. Create a provider SDK in src/aisdk/your-provider/
  2. Update src/services/generation.ts
  3. Configure credit costs in src/services/constant.ts
  4. Add UI options in the AI generator component

See AI Integration Guide for details.

Why am I getting TypeScript errors?

Common causes:

  • Missing types: Run pnpm install to ensure all dependencies are installed
  • Cache issues: Restart the TypeScript server in VS Code (Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server")
  • Outdated Next.js: Make sure you're on Next.js 15+

How do I change the color scheme?

  1. Visit a theme generator:

  2. Copy the generated CSS variables

  3. Paste into src/app/theme.css

  4. Refresh your browser

AI Features

Which AI provider should I use?

For images:

  • Replicate Flux: Best cost/quality ratio (~$0.003 per image)
  • OpenAI DALL-E 3: Highest quality (~$0.04 per image)
  • Kling: Good for Asian aesthetics

For videos:

  • Seedance (Volcengine): Fast, high quality (~$0.10 per video)
  • Kling: Professional quality

For text:

  • DeepSeek: Most cost-effective
  • OpenAI GPT-4: Highest quality
  • OpenRouter: Access to many models

Do I need to configure AI providers before deployment?

No! You can:

  1. Deploy first
  2. Configure AI keys later in the admin panel (/admin/ai-config)

How are AI credits calculated?

Each AI generation deducts credits based on the provider and type:

TypeProviderCost
ImageReplicate3 credits
ImageOpenAI5 credits
VideoSeedance10 credits
VideoKling10 credits

Configure custom costs in src/services/constant.ts.

Can users get free credits?

Yes! Users automatically get:

  • 100 credits on signup
  • 1 credit per day for check-in (via /api/ping)
  • Commission credits from referrals

Configure amounts in your database or code.

Payment & Monetization

How do I set up Stripe payments?

  1. Create a Stripe account
  2. Get API keys from dashboard
  3. Add to environment variables: 
    STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
  4. Configure webhook: https://your-domain.com/api/pay/notify/stripe
  5. Update pricing files (src/i18n/pages/pricing/) with your price IDs

See Payment Setup Guide for details.

Can I use a different payment provider?

Chameleon includes Stripe and Creem. To add others:

  1. Create a new API route in src/app/api/pay/
  2. Implement payment logic
  3. Add webhook handler
  4. Update UI to show new option

How does the credit system work?

  1. Users purchase credit packages via Stripe
  2. Credits are added to their account
  3. AI generations deduct credits automatically
  4. Users can view balance and history in /my-credits

See Credit System Guide for details.

How do referrals work?

  1. Each user gets a unique invite code
  2. They share link: https://your-domain.com/i/THEIR_CODE
  3. When referrals make purchases, original user earns commission
  4. Commission converts to credits

Configure commission rates in your database.

Database

How do I run migrations?

# Push schema changes to database
pnpm db:push

# Generate migrations (optional)
pnpm db:generate

# View database in Drizzle Studio
pnpm db:studio

How do I add a new table?

  1. Define schema in src/models/schema.ts
  2. Run pnpm db:push
  3. Access via Drizzle ORM

Example:

// src/models/schema.ts
export const yourTable = pgTable("your_table", {
  id: serial("id").primaryKey(),
  name: varchar("name", { length: 255 }),
  createdAt: timestamp("created_at").defaultNow(),
});

Can I use Supabase?

Yes! Supabase provides PostgreSQL. Just use your Supabase connection string:

DATABASE_URL="postgresql://postgres:[password]@[host].supabase.co:5432/postgres"

Deployment

Which hosting platform is best?

Vercel (Recommended):

  • ✅ Built for Next.js
  • ✅ Easiest setup
  • ✅ Free hobby tier
  • ✅ Automatic HTTPS
  • ✅ Built-in database option

Cloudflare Pages:

  • ✅ Global CDN
  • ✅ Generous free tier
  • ✅ DDoS protection

Dokploy (Self-hosted):

  • ✅ Full control
  • ✅ No platform costs
  • ⚠️ Requires server management

How do I deploy to Vercel?

  1. Push code to GitHub
  2. Import to Vercel
  3. Add environment variables
  4. Deploy!

See Vercel Deployment Guide for step-by-step instructions.

Do I need a custom domain?

No! Vercel and Cloudflare provide free *.vercel.app or *.pages.dev domains. Custom domains are optional but recommended for production.

How do I set up environment variables in production?

In Vercel:

  1. Project Settings → Environment Variables
  2. Add each variable
  3. Redeploy

In Cloudflare:

  1. Pages → Settings → Environment Variables
  2. Add variables
  3. Redeploy

Important: Use production keys (e.g., sk_live_... for Stripe, not sk_test_...).

Troubleshooting

Build fails with "Cannot find module"

# Solution 1: Clean install
rm -rf node_modules .next
pnpm install

# Solution 2: Clear Next.js cache
rm -rf .next
pnpm build

"DYNAMIC_SERVER_USAGE" error

This means a page is trying to use dynamic rendering but is configured for static generation.

Solution: Add to your page:

export const dynamic = 'force-dynamic';

Or make the page truly static by removing dynamic functions.

Database connection fails

Check:

  • Connection string is correct
  • Database server is running
  • Firewall allows connections
  • SSL mode matches database requirements

For serverless (Vercel/Cloudflare):

# Use connection pooling
DATABASE_URL="postgresql://...?pgbouncer=true"

Authentication not working

Common issues:

  • NEXTAUTH_URL doesn't match your domain
  • NEXTAUTH_SECRET is not set or too short
  • OAuth callback URL not configured in provider
  • Cookies blocked (check browser settings)

Solution:

  1. Verify all auth environment variables
  2. Check OAuth provider dashboard
  3. Clear browser cookies and retry

AI generation fails

Check:

  • Credit balance is sufficient
  • API key is configured (in admin or env vars)
  • Provider is enabled in /admin/ai-config
  • Network can reach provider API

Debug:

// Check logs in Vercel Functions or local terminal
console.log("Provider:", provider);
console.log("API Key:", apiKey ? "Set" : "Missing");

Stripe webhook not working

Check:

  • Webhook URL is correct: https://your-domain.com/api/pay/notify/stripe
  • Webhook secret is set: STRIPE_WEBHOOK_SECRET
  • Events are selected in Stripe Dashboard
  • Check Stripe webhook logs for errors

Test locally:

stripe listen --forward-to localhost:3000/api/pay/notify/stripe

Support

Where can I get help?

How do I report a bug?

  1. Check if it's already reported in GitHub Issues
  2. If not, create a new issue with:
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment (Node.js version, OS, etc.)
    • Error messages or screenshots

Can I request a feature?

Yes! Create a feature request in GitHub Issues with:

  • Clear description of the feature
  • Use case / why it's needed
  • Any relevant examples or mockups

Performance

How can I optimize my app?

Images:

  • Use Next.js <Image> component
  • Enable image optimization
  • Use WebP format

Database:

  • Add indexes to frequently queried columns
  • Use connection pooling for serverless
  • Cache frequent queries

API:

  • Implement rate limiting
  • Cache API responses where appropriate
  • Use Redis for session storage (optional)

Is Chameleon production-ready?

Yes! Chameleon is designed for production use. However, always:

  • Test thoroughly before launching
  • Use production API keys (not test keys)
  • Enable monitoring and error tracking
  • Have a backup strategy for your database

Licensing

What license does Chameleon use?

Chameleon is open-source. Check the LICENSE file in the repository for specific terms.

Can I remove the "Powered by Chameleon" footer?

Yes, you can customize or remove any branding. However, we appreciate attribution if you keep it!

Can I sell projects built with Chameleon?

Yes! You can build and sell commercial products using Chameleon.

Still have questions?