Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Node.js 20.x or higher
  • npm, yarn, or pnpm package manager
  • Git for version control
  • A Supabase account (free tier works fine)
  • A Cloudflare account (for deployment)

​
Clone the Repository

First, clone the JCV Fitness repository: 
git clone https://github.com/your-org/jcv-fitness.git
cd jcv-fitness

​
Install Dependencies

1

Install packages

Install all required dependencies:
npm install
2

Configure environment variables

Copy the example environment file and configure your variables:
cp .env.example .env.local
See Environment Variables for detailed configuration.
3

Set up database

Run the Supabase migrations to set up your database schema:See Database Setup for complete instructions.

​
Development Server

Start the Next.js development server: 
npm run dev
The application will be available at http://localhost:3000

​
Available Scripts

Here are all the available npm scripts:
ScriptCommandDescription
Developmentnpm run devStart Next.js development server
Buildnpm run buildBuild production-ready static export
Startnpm run startStart production server (after build)
Lintnpm run lintRun ESLint to check code quality
Testnpm testRun Vitest tests in watch mode
Test (CI)npm run test:runRun tests once (for CI/CD)
Video Studionpm run video:devOpen Remotion Studio for video editing
Video Buildnpm run video:buildRender horizontal promo video
Video Verticalnpm run video:build:verticalRender vertical promo video
Video Stillnpm run video:stillRender single frame from video

​
Tech Stack Overview

JCV Fitness is built with:
  • Frontend: Next.js 16, React 19, TypeScript
  • Styling: Tailwind CSS 4
  • State Management: Zustand 5
  • Authentication: Supabase Auth (magic links)
  • Database: Supabase PostgreSQL with RLS
  • Payments: MercadoPago (primary), Wompi (future)
  • Hosting: Cloudflare Pages (static export)
  • Workers: Cloudflare Workers (webhook handling)
  • Video: Remotion for promotional content
  • Validation: Zod for type-safe schemas
  • Testing: Vitest + Testing Library

​
Project Structure

jcv-fitness/
├── src/
│   ├── app/                    # Next.js 16 app directory
│   ├── features/               # Feature-based modules
│   │   ├── auth/              # Authentication (magic link)
│   │   ├── dashboard/         # User dashboard
│   │   ├── meal-plan/         # Meal plan display
│   │   ├── payment/           # MercadoPago/Wompi integration
│   │   ├── plans/             # Plan viewer, tracking
│   │   ├── subscription/      # Subscription management
│   │   ├── wizard/            # 9-step plan generator
│   │   └── workout-plan/      # Workout plan display
│   ├── components/            # Shared UI components
│   ├── lib/                   # Utilities and helpers
│   └── remotion/              # Video rendering config
├── supabase/
│   └── migrations/            # Database migrations
├── cloudflare-worker/         # Webhook worker
├── docs/                      # Project documentation
├── openspec/                  # Feature specifications
└── public/                    # Static assets

​
Verify Installation

1

Run the build

Ensure everything compiles correctly:
npm run build
You should see a successful static export to the out/ directory.
2

Run tests

Verify all tests pass:
npm run test:run

​
Next Steps

Environment Variables

Configure your Supabase, MercadoPago, and other environment variables

Database Setup

Set up your Supabase database with migrations and RLS policies

​
Troubleshooting

​
Port 3000 already in use

If port 3000 is already in use, you can specify a different port: 
PORT=3001 npm run dev

​
Module not found errors

Delete node_modules and reinstall: 
rm -rf node_modules package-lock.json
npm install

​
TypeScript errors

Ensure you’re using TypeScript 5.x: 
npx tsc --version
If needed, reinstall TypeScript: 
npm install -D typescript@latest

Build docs developers (and LLMs) love

Get started for freeTalk to us