website poc
This commit is contained in:
321
apps/website/README.md
Normal file
321
apps/website/README.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# GridPilot Landing Page
|
||||
|
||||
Pre-launch landing page for GridPilot with email signup functionality.
|
||||
|
||||
## Features
|
||||
|
||||
- **Mode Switching**: Toggle between pre-launch (landing page only) and post-launch (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:
|
||||
```bash
|
||||
cd apps/website
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Copy environment variables:
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
4. Configure environment variables in `.env.local`:
|
||||
```bash
|
||||
# Application Mode (pre-launch or post-launch)
|
||||
GRIDPILOT_MODE=pre-launch
|
||||
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:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Visit `http://localhost:3000` to see the landing page.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Required Variables
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `GRIDPILOT_MODE` | Application mode | `pre-launch` or `post-launch` |
|
||||
| `NEXT_PUBLIC_GRIDPILOT_MODE` | Client-side mode detection | Must match `GRIDPILOT_MODE` |
|
||||
| `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](https://vercel.com/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:
|
||||
```bash
|
||||
GRIDPILOT_MODE=pre-launch
|
||||
NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch
|
||||
```
|
||||
|
||||
### Post-Launch Mode
|
||||
|
||||
- Full platform access
|
||||
- All routes are accessible
|
||||
- Landing page is still available at `/`
|
||||
|
||||
To activate:
|
||||
```bash
|
||||
GRIDPILOT_MODE=post-launch
|
||||
NEXT_PUBLIC_GRIDPILOT_MODE=post-launch
|
||||
```
|
||||
|
||||
## Email Signup API
|
||||
|
||||
### Endpoint
|
||||
|
||||
`POST /api/signup`
|
||||
|
||||
### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
**Success (200):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully added to waitlist"
|
||||
}
|
||||
```
|
||||
|
||||
**Error (400/409/429/500):**
|
||||
```json
|
||||
{
|
||||
"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](https://vercel.com/dashboard)
|
||||
2. Navigate to **Storage** → Your KV Database
|
||||
3. Browse the `signups:emails` hash
|
||||
|
||||
**Option 2: CLI (with Vercel KV SDK)**
|
||||
```typescript
|
||||
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](https://vercel.com/new)
|
||||
- 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:**
|
||||
```
|
||||
GRIDPILOT_MODE=pre-launch
|
||||
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 `GRIDPILOT_MODE` and `NEXT_PUBLIC_GRIDPILOT_MODE` to `post-launch`
|
||||
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
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
This creates an optimized production build in `.next/` directory.
|
||||
|
||||
### Start Production Server
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
### Lint
|
||||
|
||||
```bash
|
||||
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 post-launch mode
|
||||
|
||||
**Solution**:
|
||||
1. Ensure `GRIDPILOT_MODE` and `NEXT_PUBLIC_GRIDPILOT_MODE` are both set to `post-launch`
|
||||
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.
|
||||
Reference in New Issue
Block a user