PixelAI

A multi-provider AI thumbnail generator that lets you create custom thumbnails using OpenAI, Replicate, Fal, Stability, and HuggingFace. Built with Next.js, React, TypeScript, and powered by the AI SDK.

Features

• Multi-provider support: Choose from five AI image providers (OpenAI, Replicate, Fal, Stability, HuggingFace)
• Provider auto-detection: Providers without configured API keys are automatically disabled in the UI
• Quota system: Free tier supports 10 image generations per day per user
• Cloud storage: Generated images are stored in Vercel Blob for fast, global access
• Firestore history: Track all generated images with owner-scoped access control
• Firebase Auth: Secure authentication with support for multiple providers
• Type-safe: Strict TypeScript with rigorous type checking throughout

Tech Stack

• Framework: Next.js 16 App Router
• React: 19 (with React 19 concurrent features)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS v4, shadcn/ui (Base UI preset)
• AI Integration: AI SDK v7 (ai@7) with custom provider adapters
• Auth & Database: Firebase Auth + Firestore
• Storage: Vercel Blob
• Testing: Vitest 4 (three projects: node/quota/jsdom) + Playwright for e2e
• Package Manager: pnpm 10
• Runtime: Node.js 22

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10+
• Java (macOS: brew install openjdk then add to PATH for quota tests)

Installation

1. Clone and install:

   git clone <repo>
   cd pixelai
   pnpm install

2. Set up environment:

   cp .env.example .env.local

3. Configure Firebase (in .env.local):

   • NEXT_PUBLIC_FIREBASE_API_KEY
   • NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN
   • NEXT_PUBLIC_FIREBASE_PROJECT_ID
   • NEXT_PUBLIC_FIREBASE_APP_ID
   • FIREBASE_PROJECT_ID (admin)
   • FIREBASE_CLIENT_EMAIL (admin)
   • FIREBASE_PRIVATE_KEY (admin)

4. Configure at least one provider (in .env.local):

   • OPENAI_API_KEY — OpenAI image generation
   • REPLICATE_API_TOKEN — Replicate models
   • FAL_API_KEY — Fal (first-party AI SDK support)
   • STABILITY_API_KEY — Stability AI
   • HUGGINGFACE_API_KEY — HuggingFace

5. Configure storage (in .env.local):

   • BLOB_READ_WRITE_TOKEN — Vercel Blob access token

6. Dev-only bypass (optional, never in production):

   • AUTH_DEV_BYPASS=1 — Skip auth verification during local development (server refuses this in production)

7. Feature flags (optional):

   • FEATURE_YT_IMPORT — YouTube URL import feature (not yet implemented)

Scripts

Script	Purpose
pnpm dev	Start local development server (default: localhost:3000)
pnpm build	Build for production
pnpm start	Start production server
pnpm lint	Run ESLint via Next.js linter
pnpm test	Run unit/integration tests (node + jsdom projects)
pnpm test:quota	Run quota tests against Firestore emulator (requires Java; see prerequisites)
pnpm test:watch	Run tests in watch mode

Development

pnpm dev
# Open http://localhost:3000

This starts Next.js dev server with full HMR and TypeScript checking.

Testing

Run all tests:

pnpm test           # Unit/integration (node + jsdom)
pnpm test:quota     # Quota enforcement (Firestore emulator on port 8181)
pnpm exec playwright test  # E2E tests (Task 16+)

Quota tests require Java on PATH. On macOS:

brew install openjdk
export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"
pnpm test:quota

Architecture

Provider Registry

Image providers are defined in lib/ai/registry.ts (server metadata) and lib/ai/provider-meta.ts (client-safe metadata). Custom adapters for HuggingFace and Stability live in lib/ai/adapters/.

Request Flow

1. Client selects provider and sends text prompt
2. POST /api/generate with Firebase ID token
3. Server verifies token and checks quota (Firestore transactional: 10/day limit)
4. Image generation via provider adapter (55s timeout)
5. Upload to Vercel Blob
6. Write generation record to Firestore
7. Return Blob URL to client

History

View all generated images at /history. Images are owner-scoped via Firestore queries on uid field. Delete button removes Blob entry and Firestore doc.

Deployment

Vercel

1. Link project:

   vercel link

2. Pull environment from Vercel (or set manually):

   vercel pull

   Ensure all vars from .env.example are set in your Vercel project dashboard.

3. Deploy preview or production:

   vercel deploy        # Preview
   vercel --prod        # Production

Firebase Setup

1. Enable Auth providers in Firebase Console:

   • Google, GitHub, etc. as needed by your login UI

2. Deploy Firestore rules:

   firebase deploy --only firestore:rules

3. Create composite index (on first production query error, or proactively via console):

   • Collection: generations
   • Fields: uid (Ascending), createdAt (Descending)
   • Console path: Firestore → Indexes → Create Composite Index

Environment Variables in Vercel

Set these in your Vercel project settings:

• All NEXT_PUBLIC_FIREBASE_* (public, safe to expose)
• All FIREBASE_* (admin; keep private)
• OPENAI_API_KEY, REPLICATE_API_TOKEN, FAL_API_KEY, STABILITY_API_KEY, HUGGINGFACE_API_KEY (provider keys; leave blank to disable)
• BLOB_READ_WRITE_TOKEN (Vercel Blob)

Never set AUTH_DEV_BYPASS in production — the server explicitly refuses it.

Route Configuration

Image generation has a 55-second timeout set via route segment config (Next.js route.ts maxDuration). No vercel.json needed.

Development Notes

• TypeScript Strict Mode: Full strict checking enabled; no any in product code
• React Server Components: App Router uses RSCs by default; client components marked with 'use client'
• Server Actions: Use 'use server' for mutations; Server Actions enforce type safety
• Styling: Tailwind v4 with shadcn/ui (Base UI preset) for accessible components
• Testing: Vitest for unit tests, Playwright for e2e flows (added in Task 16)

License

MIT