gridpilot.gg/apps/website/README.md

GridPilot Landing Page

Pre-launch landing page for GridPilot with email signup functionality.

Features

• Mode Switching: Toggle between pre-launch (landing page only) and alpha (full platform) modes
• Email Capture: Collect email signups with validation and rate limiting
• Production Ready: Configured for Vercel deployment with KV storage

Local Development Setup

Prerequisites

• Node.js 20+
• npm or pnpm

Installation

1. Clone the repository and navigate to the website directory:

cd apps/website

2. Install dependencies:

npm install

3. Copy environment variables:

cp .env.example .env.local

4. Configure environment variables in .env.local:

# Application Mode (pre-launch or alpha)
NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch

# Vercel KV (required for email signups)
KV_REST_API_URL=your_kv_rest_api_url_here
KV_REST_API_TOKEN=your_kv_rest_api_token_here

# Site URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

5. Start the development server:

npm run dev

Visit http://localhost:3000 to see the landing page.

Environment Variables

Required Variables

Variable	Description	Example
NEXT_PUBLIC_GRIDPILOT_MODE	Application mode (server & client)	pre-launch or alpha
KV_REST_API_URL	Vercel KV REST API endpoint	From Vercel Dashboard
KV_REST_API_TOKEN	Vercel KV authentication token	From Vercel Dashboard
NEXT_PUBLIC_SITE_URL	Public site URL	https://gridpilot.com

Getting Vercel KV Credentials

1. Go to Vercel Dashboard
2. Navigate to Storage → Create Database → KV
3. Create a new KV database (free tier available)
4. Copy the KV_REST_API_URL and KV_REST_API_TOKEN from the database settings
5. Add them to your environment variables

Mode Switching

The application supports two modes:

Pre-Launch Mode (Default)

• Shows landing page with email capture
• Only / and /api/signup routes are accessible
• All other routes return 404

To activate:

NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch

Post-Launch Mode

• Full platform access
• All routes are accessible
• Landing page is still available at /

To activate:

NEXT_PUBLIC_GRIDPILOT_MODE=alpha

Email Signup API

Endpoint

POST /api/signup

Request Body

{
  "email": "user@example.com"
}

Response

Success (200):

{
  "success": true,
  "message": "Successfully added to waitlist"
}

Error (400/409/429/500):

{
  "error": "Error message here"
}

Features

• Validation: Email format validation using Zod
• Rate Limiting: Max 5 submissions per IP per hour
• Duplicate Prevention: Prevents duplicate email submissions
• Disposable Email Detection: Blocks common disposable email services
• Storage: Emails stored in Vercel KV with timestamp and IP

Accessing Submitted Emails

Submitted emails are stored in Vercel KV under the key signups:emails.

Option 1: Vercel KV Dashboard

1. Go to Vercel Dashboard
2. Navigate to Storage → Your KV Database
3. Browse the signups:emails hash

Option 2: CLI (with Vercel KV SDK)

import { kv } from '@vercel/kv';

// Get all signups
const signups = await kv.hgetall('signups:emails');
console.log(signups);

Deployment

Vercel Deployment (Recommended)

1. Connect Repository

   • Go to Vercel Dashboard
   • Import your Git repository
   • Select the apps/website directory as the root

2. Configure Build Settings

   • Framework Preset: Next.js
   • Build Command: npm run build
   • Output Directory: .next
   • Install Command: npm install

3. Set Environment Variables

   In Vercel Dashboard → Project Settings → Environment Variables:

   Production:

   NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch
   KV_REST_API_URL=<your_vercel_kv_url>
   KV_REST_API_TOKEN=<your_vercel_kv_token>
   NEXT_PUBLIC_SITE_URL=https://gridpilot.com
   

   Preview (optional): Same as production, or use different values for testing

4. Deploy

   • Click "Deploy"
   • Vercel will automatically deploy on every push to main branch

Switching to Post-Launch Mode

When ready to launch the full platform:

1. Go to Vercel Dashboard → Project Settings → Environment Variables
2. Update NEXT_PUBLIC_GRIDPILOT_MODE to alpha
3. Redeploy the application (automatic if you save changes)

Custom Domain Setup

1. Go to Vercel Dashboard → Project Settings → Domains
2. Add your domain (e.g., gridpilot.com)
3. Follow DNS configuration instructions
4. Update NEXT_PUBLIC_SITE_URL environment variable to match your domain

Build & Test

Build for Production

npm run build

This creates an optimized production build in .next/ directory.

Start Production Server

npm run start

Lint

npm run lint

Testing Email Signup

Test Locally

1. Start the development server
2. Navigate to http://localhost:3000
3. Scroll to "Want Early Access?" section
4. Enter an email and click "Join Waitlist"

Test Scenarios

• ✅ Valid email submission
• ✅ Invalid email format rejection
• ✅ Duplicate email prevention
• ✅ Rate limiting (5 submissions per hour)
• ✅ Loading states
• ✅ Error messages
• ✅ Success confirmation

Test Rate Limiting

Submit the same email 5 times within an hour. The 6th submission should return a 429 error.

Troubleshooting

Email Signup Not Working

Issue: API returns 500 error

Solution: Check that KV_REST_API_URL and KV_REST_API_TOKEN are correctly set in environment variables

Mode Switching Not Working

Issue: Routes still show 404 in alpha mode

Solution:

1. Ensure NEXT_PUBLIC_GRIDPILOT_MODE is set to alpha
2. Restart the development server or redeploy to Vercel
3. Clear browser cache

Rate Limiting Issues

Issue: Rate limiting not working in development

Solution: Vercel KV may need to be properly configured. Check KV dashboard for errors.

Project Structure

apps/website/
├── app/
│   ├── api/
│   │   └── signup/
│   │       └── route.ts          # Email signup API endpoint
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx                  # Landing page
├── components/
│   ├── landing/
│   │   ├── EmailCapture.tsx      # Email signup form
│   │   ├── FAQ.tsx
│   │   ├── FeatureGrid.tsx
│   │   ├── Hero.tsx
│   │   └── RatingExplainer.tsx
│   ├── mockups/                  # UI mockups
│   ├── shared/
│   │   └── ModeGuard.tsx         # Client-side mode guard
│   └── ui/                       # Reusable UI components
├── lib/
│   ├── email-validation.ts       # Email validation utilities
│   ├── mode.ts                   # Mode detection utilities
│   └── rate-limit.ts             # Rate limiting utilities
├── middleware.ts                 # Next.js middleware for route protection
├── .env.example                  # Environment variables template
└── README.md                     # This file

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Validation: Zod
• Storage: Vercel KV (Redis)
• Deployment: Vercel

Support

For issues or questions, contact the development team or open an issue in the repository.