🚀 Complete Setup Guide - ZeroCarbon Quickstart

✅ What We Fixed

Your quickstart was configured for api.zerocarbon.codes (subdomain API), but your actual deployment uses:

Production: https://zerocarbon.codes/api/...
Local Dev: http://localhost:3000/api/...

We've updated all quickstart files to work with your real deployment.

📋 Prerequisites

Before you start:

Your API must be deployed and working
- Production: https://zerocarbon.codes
- Test it: https://zerocarbon.codes/api/v1/emissions/calculate (should respond)
Required API endpoints must be public (no auth for testing):
- /api/v1/emissions/calculate
- /api/v1/calculate/flight
- /api/v1/calculate/fuel
CORS must be configured for web demo to work

🧪 Step 1: Test Locally

Test the Node.js Demo

# From your project root
cd quickstart
node index.js

Expected Output:

╔═══════════════════════════════════════╗
║   ZeroCarbon API - Quick Start Demo   ║
╚═══════════════════════════════════════╝

Welcome! This demo shows how easy it is to calculate carbon emissions.
No API key needed for testing.

🔌 Demo 1: Electricity Emissions
Calculating emissions for 1,000 kWh of electricity in the US...

✅ Result: 386.5 kg CO2e
📊 Scope: Scope 2 (Indirect emissions)
...

Test with Local API

# Set environment variable to use localhost
$env:API_BASE="http://localhost:3000/api"
node index.js

Test the Python Demo

python quickstart/quickstart.py

Test the Web Demo

# Start your Next.js dev server
npm run dev

# Then open in browser:
# http://localhost:3000/quickstart/web-demo.html

Test cURL Examples

# Production
.\quickstart\curl-examples.sh

# Or with custom API
$env:API_BASE="http://localhost:3000/api"
.\quickstart\curl-examples.sh

🔧 Step 2: Configure Public API Access

Your API endpoints need to allow unauthenticated requests for the quickstart to work.

Option A: Add Public Testing Middleware

Create src/middleware/publicTesting.ts:

import { NextRequest, NextResponse } from 'next/server';

// IP-based rate limiting (simple in-memory store)
const rateLimitMap = new Map<string, { count: number; resetTime: number }>();

export function publicTestingMiddleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  
  // Allow public access to these endpoints
  const publicEndpoints = [
    '/api/v1/emissions/calculate',
    '/api/v1/calculate/flight',
    '/api/v1/calculate/fuel',
  ];
  
  const isPublicEndpoint = publicEndpoints.some(endpoint => 
    pathname.startsWith(endpoint)
  );
  
  if (!isPublicEndpoint) {
    return null; // Not a public endpoint, continue to auth
  }
  
  // Rate limiting: 1000 requests per day per IP
  const ip = request.ip || request.headers.get('x-forwarded-for') || 'unknown';
  const now = Date.now();
  const dayInMs = 24 * 60 * 60 * 1000;
  
  let rateLimit = rateLimitMap.get(ip);
  
  if (!rateLimit || now > rateLimit.resetTime) {
    rateLimit = { count: 0, resetTime: now + dayInMs };
    rateLimitMap.set(ip, rateLimit);
  }
  
  rateLimit.count++;
  
  if (rateLimit.count > 1000) {
    return NextResponse.json({
      error: 'Rate limit exceeded',
      message: 'You have exceeded the testing limit. Get a free API key at https://zerocarbon.codes/signup'
    }, { status: 429 });
  }
  
  // Add CORS headers for web demo
  const response = NextResponse.next();
  response.headers.set('Access-Control-Allow-Origin', '*');
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type');
  
  return response;
}

Option B: Update Existing Middleware

Add to your middleware.ts:

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  
  // Public testing endpoints (no auth required)
  const publicTestingEndpoints = [
    '/api/v1/emissions/calculate',
    '/api/v1/calculate/flight',
    '/api/v1/calculate/fuel',
  ];
  
  // Allow CORS for public endpoints
  if (publicTestingEndpoints.some(endpoint => pathname.startsWith(endpoint))) {
    // Handle OPTIONS request
    if (request.method === 'OPTIONS') {
      return new NextResponse(null, {
        status: 200,
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type, Authorization',
        },
      });
    }
    
    // Add CORS headers to response
    const response = NextResponse.next();
    response.headers.set('Access-Control-Allow-Origin', '*');
    response.headers.set('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
    response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    
    return response;
  }
  
  // ... rest of your auth middleware
}

export const config = {
  matcher: [
    '/api/:path*',
    // ... other routes
  ],
};

🌐 Step 3: Deploy Web Demo

Option 1: Host on Your Main Domain

# Copy web-demo.html to your public folder
cp quickstart/web-demo.html public/quickstart-demo.html

# Access at: https://zerocarbon.codes/quickstart-demo.html

Option 2: Deploy to Vercel (Separate)

cd quickstart

# Create vercel.json
@"
{
  "rewrites": [
    { "source": "/", "destination": "/web-demo.html" }
  ]
}
"@ | Out-File -Encoding utf8 vercel.json

# Deploy
npx vercel --prod

# Set custom domain (optional)
# vercel domains add quickstart.zerocarbon.codes

Option 3: Deploy to Netlify

cd quickstart

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=.

# Set site name: zerocarbon-quickstart

📦 Step 4: Publish NPM Package

cd quickstart

# 1. Login to NPM
npm login
# Enter your npm username, password, and email

# 2. Update package.json name if needed
# If "zerocarbon-quickstart" is taken, use:
#   @zerocarbon/quickstart
#   or @yourusername/zerocarbon-quickstart

# 3. Publish
npm publish --access public

# 4. Test installation
npx zerocarbon-quickstart
# (or your chosen package name)

Package.json should look like:

{
  "name": "zerocarbon-quickstart",
  "version": "1.0.0",
  "description": "Interactive quickstart for ZeroCarbon API",
  "main": "index.js",
  "bin": {
    "zerocarbon-quickstart": "./index.js"
  },
  "keywords": ["carbon", "emissions", "climate", "api", "quickstart"],
  "author": "ZeroCarbon",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/zerocarbon/quickstart"
  }
}

🔄 Step 5: Deploy to Replit

Method 1: GitHub Import

Create GitHub repo:

cd quickstart
git init
git add .
git commit -m "Initial commit: ZeroCarbon API Quickstart"

# Create repo on GitHub, then:
git remote add origin https://github.com/yourusername/zerocarbon-quickstart.git
git branch -M main
git push -u origin main

Import to Replit:
- Go to https://replit.com
- Click "Create Repl"
- Select "Import from GitHub"
- Enter your repo URL: yourusername/zerocarbon-quickstart
- Click "Import"
Configure Repl:
- Run command: node index.js
- Make repl public (Share → Public)
- Get link: https://replit.com/@yourusername/zerocarbon-quickstart

Method 2: Direct Upload

Create new Repl on Replit.com
Select "Node.js" template
Upload all quickstart files
Set run command to node index.js
Make public and get shareable link

🎨 Step 6: Deploy to CodeSandbox

Method 1: GitHub Import

Go to https://codesandbox.io
Click "Create Sandbox"
Select "Import from GitHub"
Enter: yourusername/zerocarbon-quickstart
Make sandbox public
Get link: https://codesandbox.io/s/github/yourusername/zerocarbon-quickstart

Method 2: Direct Create

Create new Node.js sandbox
Upload files from quickstart/ directory
Make public
Get shareable link

📝 Step 7: Update README and Docs

Update quickstart/README.md with your actual links:

# ZeroCarbon API - 5-Minute Quickstart

## Try It Now

**Option 1: NPM (30 seconds)**
```bash
npx zerocarbon-quickstart

Option 2: Web Demo (10 seconds) 👉 Open Interactive Demo 👈

Option 3: Replit (20 seconds)

Option 4: CodeSandbox


---

## 🧪 Step 8: End-to-End Testing

### Test Checklist

```powershell
# 1. Test local Node.js demo
node quickstart/index.js

# 2. Test with production API
$env:API_BASE="https://zerocarbon.codes/api"
node quickstart/index.js

# 3. Test Python demo
python quickstart/quickstart.py

# 4. Test cURL examples
.\quickstart\curl-examples.sh

# 5. Test web demo
# Open: http://localhost:3000/quickstart-demo.html
# (or your deployed URL)

# 6. Test NPM package
npx zerocarbon-quickstart

# 7. Test from different computer/network
# Use online tools: replit.com, codesandbox.io

# 8. Test rate limiting
# Make >1000 requests and verify 429 error

Validation Checks

🎯 Step 9: YC Application Integration

Update Your YC Application

In "How do you know people want your product?":

We're the fastest carbon API to integrate. Try it yourself RIGHT NOW:

1. Run in terminal: npx zerocarbon-quickstart
2. Or open: https://zerocarbon.codes/quickstart-demo.html
3. Or fork: https://replit.com/@yourusername/zerocarbon-quickstart

You'll get a real carbon calculation in under 60 seconds.

Our beta users integrate in 18 minutes average (vs. 2-3 hours for competitors).
The secret? Zero friction—no signup, no API key, no sales call. Just code.

In "Product Demo URL":

https://zerocarbon.codes/quickstart-demo.html

During YC Interview (If Selected)

Have this ready to screen share:

Open terminal
Run: npx zerocarbon-quickstart
Show real-time results
Say: "This is what every developer experiences. Zero friction. This is our moat."

🚨 Troubleshooting

Issue: "ENOTFOUND api.zerocarbon.codes"

Cause: Old hardcoded URL Fix:

# Set correct API base
$env:API_BASE="https://zerocarbon.codes/api"
node quickstart/index.js

Issue: CORS errors in web demo

Cause: Missing CORS headers Fix: Add to your API middleware:

response.headers.set('Access-Control-Allow-Origin', '*');

Issue: 401 Unauthorized

Cause: Endpoint requires authentication Fix: Update middleware to allow public access (see Step 2)

Issue: 404 Not Found

Cause: Endpoint doesn't exist Fix: Check your API routes exist:

/api/v1/emissions/calculate
/api/v1/calculate/flight
/api/v1/calculate/fuel

Issue: Slow response times

Cause: Database query performance Fix:

Add database indexes
Cache common calculations
Use Vercel Edge Functions

Issue: NPM publish fails

Cause: Package name already taken Fix: Use scoped package:

{
  "name": "@zerocarbon/quickstart"
}

📊 Step 10: Monitor Usage

Set Up Analytics

Track these metrics:

// Add to your API routes
import { analytics } from '@/lib/analytics';

export async function POST(request: Request) {
  // ... your endpoint logic
  
  // Track quickstart usage
  await analytics.track('quickstart_api_call', {
    endpoint: '/v1/emissions/calculate',
    source: request.headers.get('referer'),
    userAgent: request.headers.get('user-agent'),
  });
}

Monitor:

Daily API calls from quickstart
Conversion: quickstart → signup → paid
Geographic distribution
Most popular endpoints
Error rates

Create Dashboard

Track on your admin dashboard:

Quickstart demos run today: X
NPM downloads this week: Y
Replit forks: Z
Conversion rate: A%

✅ Final Checklist

Before announcing your quickstart:

Technical:

All demos tested on 3 different machines
API endpoints working in production
CORS configured correctly
Rate limiting tested
Error messages are helpful
Response times < 1 second

Distribution:

Documentation:

README updated with actual links
YC application updated
API docs mention quickstart
Homepage has "Try Demo" button

Marketing:

Tweet prepared about quickstart
Reddit post drafted (r/programming)
Email to beta users
YC application submitted

🎬 Next Steps

Test everything (Step 8 checklist)
Deploy web demo (Step 3)
Publish NPM package (Step 4)
Create Replit/CodeSandbox (Steps 5-6)
Update YC application (Step 9)
Announce on Twitter
Monitor usage (Step 10)

💡 Pro Tips

Make it bulletproof:
- Demos should NEVER fail
- Have fallback mock data
- Show helpful error messages
Track everything:
- Log every demo run
- Know exactly what YC partners see
- Fix issues within 1 hour
Optimize for speed:
- Cache common calculations
- Use CDN for web demo
- Aim for <200ms API responses
Be available:
- Monitor email during YC review
- Fix issues immediately
- Have phone ready for urgent bugs

📞 Support

If you need help:

Test locally first: node quickstart/index.js
Check API is running: Visit https://zerocarbon.codes/api/v1/emissions/calculate
Verify CORS: Check browser console for errors
Check rate limits: Make sure you haven't hit 1000 requests
Review logs: Check Vercel deployment logs

Ready to launch? Start with Step 1! 🚀

FilesExpand file tree

SETUP_GUIDE.md

Latest commit

History

SETUP_GUIDE.md

File metadata and controls

🚀 Complete Setup Guide - ZeroCarbon Quickstart

✅ What We Fixed

📋 Prerequisites

🧪 Step 1: Test Locally

Test the Node.js Demo

Test with Local API

Test the Python Demo

Test the Web Demo

Test cURL Examples

🔧 Step 2: Configure Public API Access

Option A: Add Public Testing Middleware

Option B: Update Existing Middleware

🌐 Step 3: Deploy Web Demo

Option 1: Host on Your Main Domain

Option 2: Deploy to Vercel (Separate)

Option 3: Deploy to Netlify

📦 Step 4: Publish NPM Package

🔄 Step 5: Deploy to Replit

Method 1: GitHub Import

Method 2: Direct Upload

🎨 Step 6: Deploy to CodeSandbox

Method 1: GitHub Import

Method 2: Direct Create

📝 Step 7: Update README and Docs

Validation Checks

🎯 Step 9: YC Application Integration

Update Your YC Application

During YC Interview (If Selected)

🚨 Troubleshooting

Issue: "ENOTFOUND api.zerocarbon.codes"

Issue: CORS errors in web demo

Issue: 401 Unauthorized

Issue: 404 Not Found

Issue: Slow response times

Issue: NPM publish fails

📊 Step 10: Monitor Usage

Set Up Analytics

Create Dashboard

✅ Final Checklist

🎬 Next Steps

💡 Pro Tips

📞 Support