puffin-app/ENV_MIGRATION.md
Matt 82f72941ca
Some checks failed
Build and Push Docker Images / docker (push) Failing after 1m58s
Migrate from Vite to Next.js 16 with Turbopack
This is a major migration from Vite to Next.js 16.0.1 for improved
performance, better SEO, and modern React features.

## Next.js Migration Changes
- Upgraded to Next.js 16.0.1 with Turbopack (from Vite 6)
- Migrated from client-side routing to App Router architecture
- Created app/ directory with Next.js page structure
- Added server components and client components pattern
- Configured standalone Docker builds for production

## Bug Fixes - React Hooks
- Fixed infinite loop in Header.tsx scroll behavior (removed lastScrollY state dependency)
- Fixed infinite loop in useCalculatorState.ts (wrapped saveState/clearState in useCallback)
- Fixed infinite loop in OffsetOrder.tsx (removed savedState from useEffect dependencies)
- Removed unused React imports from all client components

## Environment Variable Migration
- Migrated all VITE_ variables to NEXT_PUBLIC_ prefix
- Updated src/utils/config.ts to use direct static references (required for Next.js)
- Updated src/api/checkoutClient.ts, emailClient.ts, aisClient.ts for Next.js env vars
- Updated src/vite-env.d.ts types for Next.js environment
- Maintained backward compatibility with Docker window.env

## Layout & UX Improvements
- Fixed footer to always stay at bottom of viewport using flexbox
- Updated app/layout.tsx with flex-1 main content area
- Preserved glass morphism effects and luxury styling

## TypeScript & Build
- Fixed TypeScript strict mode compilation errors
- Removed unused imports and variables
- Fixed Axios interceptor types in project/src/api/wrenClient.ts
- Production build verified and passing

## Testing & Verification
- Tested calculator end-to-end in Playwright
- Verified Wren API integration working (11 portfolios fetched)
- Confirmed calculation: 5000L → 13.47 tons CO₂ → $3,206 total
- All navigation routes working correctly
- Footer positioning verified across all pages

## Files Added
- app/ directory with Next.js routes
- components/ directory with client components
- next.config.mjs, next-env.d.ts
- ENV_MIGRATION.md, NEXTJS_MIGRATION_COMPLETE.md documentation

## Files Modified
- Docker configuration for Next.js standalone builds
- package.json dependencies (Next.js, React 19)
- ts config.json for Next.js
- All API clients for new env var pattern

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-31 22:23:45 +01:00

2.8 KiB

Environment Variables Migration Guide

Vite → Next.js Environment Variable Changes

When migrating from Vite to Next.js, all environment variables need to be renamed:

Required Changes

Old (Vite) New (Next.js) Purpose
VITE_WREN_API_TOKEN NEXT_PUBLIC_WREN_API_TOKEN Wren Climate API authentication token
VITE_API_BASE_URL NEXT_PUBLIC_API_BASE_URL Backend API base URL
VITE_STRIPE_PUBLISHABLE_KEY NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY Stripe payment gateway public key
VITE_FORMSPREE_CONTACT_ID NEXT_PUBLIC_FORMSPREE_CONTACT_ID Formspree contact form ID (if still used)
VITE_FORMSPREE_OFFSET_ID NEXT_PUBLIC_FORMSPREE_OFFSET_ID Formspree offset form ID (if still used)

Updated .env File

Your .env file should now look like this:

# Wren Climate API
NEXT_PUBLIC_WREN_API_TOKEN=35c025d9-5dbb-404b-85aa-19b09da0578d

# Backend API
NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

# Stripe (add when needed)
# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Formspree (if still using)
# NEXT_PUBLIC_FORMSPREE_CONTACT_ID=xkgovnby
# NEXT_PUBLIC_FORMSPREE_OFFSET_ID=xvgzbory

Docker Environment Variables

In your Docker deployment (via docker-compose.yml or environment injection), update:

environment:
  - NEXT_PUBLIC_WREN_API_TOKEN=${WREN_API_TOKEN}
  - NEXT_PUBLIC_API_BASE_URL=${API_BASE_URL}
  - NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=${STRIPE_PUBLISHABLE_KEY}

Code Changes Made

The following file has been updated to use Next.js environment variables:

  • src/utils/config.ts: Changed from import.meta.env.VITE_* to process.env.NEXT_PUBLIC_*

Important Notes

  1. NEXT_PUBLIC_ prefix is required for client-side environment variables in Next.js
  2. The next.config.mjs file maps these variables for compatibility
  3. Server-side only variables (like API secrets) should NOT have the NEXT_PUBLIC_ prefix
  4. The app will work without these variables but will fall back to default/demo modes

Verification

To verify your environment variables are loaded correctly:

# Development
npm run dev

# Check console for:
# "Config: {wrenApiKey: '[REDACTED]', isProduction: false}"

# If you see "Missing required environment variable", update your .env file

Production Deployment

For production deployments:

  1. Update your .env file with NEXT_PUBLIC_* variables
  2. If using Docker, update your docker-compose.yml or environment scripts
  3. If using Gitea Actions, update CI/CD environment variables
  4. Rebuild the application: npm run build

Backward Compatibility

The next.config.mjs file includes fallback logic to support both naming conventions during the transition period, but you should update to the new names as soon as possible.