Quick Start

Project Detection & Validation

🔍 Detecting your project...
  ✓ Next.js App Router detected
  ✓ TypeScript configuration found
  ✓ Package manager: pnpm detected
  ✓ No existing upload configuration
  ✓ Project structure validated

What's happening: The CLI automatically detects your project setup to ensure compatibility.

If you see warnings:

• ⚠️ Pages Router detected: Still works, but examples will be for App Router
• ⚠️ No TypeScript: JavaScript examples will be generated instead
• ⚠️ Existing configuration: CLI will ask if you want to overwrite
• ⚠️ Package manager not detected: Will default to npm

Provider Selection

? Which cloud storage provider would you like to use?
❯ Cloudflare R2 (recommended)
  AWS S3 (classic, widely supported)
  DigitalOcean Spaces (simple, affordable)
  Google Cloud Storage (enterprise-grade)
  MinIO (self-hosted, open source)
  Custom S3-compatible endpoint

How to choose:

Use arrow keys to navigate, Enter to select.

Credential Detection & Setup

🔧 Setting up Cloudflare R2...

🔍 Checking for existing credentials...
  ✓ Found CLOUDFLARE_R2_ACCESS_KEY_ID
  ✓ Found CLOUDFLARE_R2_SECRET_ACCESS_KEY
  ✓ Found CLOUDFLARE_R2_ACCOUNT_ID
  ⚠ CLOUDFLARE_R2_BUCKET_NAME not found

What this means:

• ✅ Found credentials: CLI detected existing environment variables
• ⚠️ Missing credentials: You'll be prompted to enter them
• ❌ No credentials: CLI will guide you through setup

If prompted for credentials:

? Enter your Cloudflare R2 Access Key ID: f1d2...
? Enter your Cloudflare R2 Secret Access Key: [hidden]
? Enter your Cloudflare Account ID: abc123...
? Enter your R2 bucket name: my-app-uploads-2024

Pro tips:

• Use a unique bucket name (globally unique across all R2)
• Account ID can be found in your Cloudflare dashboard
• Don't have credentials? Check our Cloudflare R2 setup guide

Bucket Creation

? Create bucket automatically? (Y/n)

Recommended: Yes - The CLI will:

• Create the bucket with proper permissions
• Set up CORS configuration for web uploads
• Configure public read access for uploaded files
• Test the connection to ensure everything works

Choose "No" if:

• You already have a bucket configured
• Your organization requires manual bucket creation
• You need custom bucket policies

Success looks like:

✅ Created R2 bucket: my-app-uploads-2024
✅ Configured CORS for web uploads
✅ Set up public read permissions
✅ Connection test successful

API Route Configuration

? Where should we create the upload API?
❯ app/api/upload/route.ts (recommended)
  app/api/s3-upload/route.ts (classic)
  Custom path

Recommendations:

• /api/upload: Clean, modern route name
• /api/s3-upload: If you want to be explicit about S3
• Custom path: If you have specific routing requirements

The CLI will create:

• Type-safe API route with validation
• Authentication middleware (ready to customize)
• Support for multiple upload types (images, documents)
• Proper error handling and responses

Component Generation

? Generate example upload page?
❯ Yes, create app/upload/page.tsx with full example
  Yes, just add components to components/ui/
  No, I'll build my own

Choose based on your needs:

Full example page - Best for:

• Learning how the library works
• Quick prototyping and testing
• Getting a working demo immediately

Components only - Best for:

• Adding uploads to existing pages
• Custom UI integration
• Building your own demo

No components - Best for:

• Experienced developers
• Custom implementation requirements
• API-only usage

File Generation & Installation

🛠️ Generating files...

✨ Created files:
  ├── app/api/upload/route.ts        # Type-safe API endpoint
  ├── app/upload/page.tsx            # Demo upload page
  ├── components/ui/upload-button.tsx # Simple upload button
  ├── components/ui/upload-dropzone.tsx # Drag & drop component
  ├── lib/upload-client.ts           # Type-safe client
  └── .env.example                   # Environment template

📦 Installing dependencies with pnpm...
  ✓ pushduck
  ✓ @aws-sdk/client-s3
  ✓ react-dropzone

🎉 Setup complete! Your uploads are ready.

What happens:

1. Files generated with your specific configuration
2. Dependencies installed using your detected package manager
3. Types generated for full TypeScript support
4. Environment configured with your settings

Package Manager Support:

• npm: npm install commands
• pnpm: pnpm add commands
• yarn: yarn add commands
• bun: bun add commands

Next steps shown:

🚀 Next steps:
  1. Start your dev server: pnpm dev
  2. Visit: http://localhost:3000/upload
  3. Try uploading a file!
  
📚 Learn more:
  • API Reference: /docs/api
  • Providers: /docs/providers
  • Examples: /docs/examples