🌿 NutriCompass - Smart Supplement & Nutrition Guide

NutriCompass is a comprehensive, evidence-based nutrition and supplement recommendation application. It helps users understand what nutrients, vitamins, minerals, herbs, and Ayurvedic plants might support their health goals — and how to use them responsibly.

⚠️ Disclaimer: This app does not diagnose or treat disease. It exists to educate and guide smarter supplement choices using scientific evidence and traditional knowledge — without replacing a doctor.

✨ Features

🎯 Intelligent Goal Analysis

Describe your health goals in natural language
App interprets and identifies relevant body systems
Smart matching to appropriate supplements

📚 Comprehensive Database (60+ Supplements)

Vitamins: A, B-Complex, C, D3, E, K2
Minerals: Magnesium, Zinc, Iron, Selenium, Calcium
Ayurvedic Herbs: Ashwagandha, Brahmi, Tulsi, Shatavari, Triphala, Guduchi, Shilajit
Western Herbs: Rhodiola, Valerian, St. John's Wort, Milk Thistle
Medicinal Mushrooms: Lion's Mane, Reishi, Cordyceps
Amino Acids: L-Theanine, Glycine, NAC, Creatine, L-Citrulline
Performance: Beta-Alanine, HMB, Beetroot Extract, BCAAs

🔬 Evidence-Based Transparency

Strong Evidence: Multiple human clinical trials
Moderate Evidence: Some clinical research
Limited/Traditional: Primarily traditional use

💊 Form Intelligence

Compare forms (e.g., Magnesium Glycinate vs Citrate vs Oxide)
Bioavailability ratings
Absorption enhancers and blockers
Best timing recommendations

🔍 Advanced Browse Engine

Smart search across all fields
Quick filter presets (Beginner Essentials, Sleep Stack, Nootropics, etc.)
Multi-dimensional filtering (type, evidence, goals, body systems)
Three view modes (List, Grid, Compact)
Personalized recommendations based on profile

🧭 Nutrient Targets & Priority Flags

Personalized nutrient targets built from NIH Dietary Reference Intakes
Priority indicators based on diet, age, and lifestyle
Food-first guidance with supplement tie-ins

🥗 Food Source Intelligence

Food-source tables with % NRV for vitamins and minerals (EU reference values)
CIQUAL + EuroFIR food composition sources
Research-based reference doses for non‑NRV compounds (e.g., melatonin, creatine, CoQ10)

🍽️ Food Lookup (USDA FoodData Central + Open Food Facts)

Search USDA FoodData Central and Open Food Facts with offline fallback caching
Quick macro snapshots (calories, protein, carbs, fat)

🧪 Stack Builder

Build custom supplement stacks
Automatic interaction/conflict detection
Timing optimization
Morning/Afternoon/Evening organization
Curated stacks for common goals with synergy notes

📈 Progress & Lab Tracking

Daily check-ins for sleep, energy, mood, focus, and recovery
Log supplements taken with notes and side-effect tracking
Lab result tracking with smart insights for common markers
Rolling summaries for adherence and average scores

👤 Personalization

Optional user profile (age, diet, training style, health conditions)
Tailored recommendations
Lifestyle-aware suggestions

⚖️ Metabolic Metrics

BMI, BMR, and TDEE estimates from profile inputs

📖 Learn Section

"Why This, Not That?" comparisons
Misinformation alerts
Form guidance
Safety education

🛡️ Safety First

Drug interaction warnings
Pregnancy/breastfeeding cautions
Condition-specific warnings
Cycling recommendations

📸 Screenshots

The application features a clean, modern interface with:

Natural language goal input
Evidence-graded supplement cards
Interactive stack builder
Advanced filtering system

📋 Prerequisites

Before running NutriCompass, ensure you have the following installed:

Required

Node.js (v18.0.0 or higher)

# Check version
node --version

# Install via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

npm (v9.0.0 or higher) or yarn (v1.22.0 or higher)

# Check npm version
npm --version

# Or install yarn
npm install -g yarn

Optional (for deployment)

Docker (for containerized deployment)
Nginx or Apache (for static file serving)
Git (for version control)

🚀 Quick Start (Local Development)

1. Clone or Download the Project

# If using git
git clone https://github.com/yourusername/nutricompass.git
cd nutricompass

# Or download and extract the ZIP file

2. Install Dependencies

# Using npm
npm install

# Or using yarn
yarn install

3. Start Development Server

# Using npm
npm run dev

# Or using yarn
yarn dev

4. Open in Browser

The app will be available at:

http://localhost:5173

The development server features:

⚡ Hot Module Replacement (HMR)
🔄 Auto-refresh on file changes
📝 TypeScript error reporting
🎨 Tailwind CSS JIT compilation

5. Run Linting & Type Checking (Optional)

# Run ESLint to check for code quality issues
npm run lint

# Run ESLint and auto-fix issues
npm run lint:fix

# TypeScript type checking
npm run typecheck

📁 Project Structure

nutricompass/
├── public/                       # Static assets
├── src/
│   ├── components/
│   │   ├── AdvancedBrowse.tsx    # Advanced browse engine
│   │   └── EducationalGuide.tsx  # Educational content
│   ├── constants/
│   │   └── taxonomy.ts           # Centralized goal/system taxonomy
│   ├── data/
│   │   ├── curatedStacks.ts       # Curated goal-based stacks
│   │   ├── nutrientRequirements.ts # Nutrient target guidance
│   │   ├── nutrientFoodSources.ts # Nutrient → food source helpers
│   │   └── supplements.ts        # Supplement database + nutrient food data
│   ├── types/
│   │   └── index.ts              # TypeScript interfaces
│   ├── utils/
│   │   ├── analyzer.ts           # NLP goal analysis with negation handling
│   │   ├── normalization.ts      # Text normalization helpers
│   │   └── cn.ts                 # Class name helper
│   ├── App.tsx                   # Main application
│   ├── main.tsx                  # Entry point
│   └── index.css                 # Global styles + Tailwind
├── index.html                    # HTML template
├── package.json                  # Dependencies & scripts
├── tsconfig.json                 # TypeScript config
├── vite.config.ts                # Vite config
├── server.js                     # Express server for production
├── Dockerfile                    # Docker configuration
├── docker-compose.yml            # Docker Compose configuration
├── nginx.conf                    # Nginx configuration
├── vercel.json                   # Vercel deployment config
├── netlify.toml                  # Netlify deployment config
└── README.md                     # This file

🏗️ Building for Production

Build the Application

# Using npm
npm run build

# Or using yarn
yarn build

This creates an optimized production build in the dist/ folder:

dist/
├── index.html
├── assets/
│   ├── index-[hash].js      # Bundled JavaScript
│   └── index-[hash].css     # Bundled CSS
└── ...

Preview Production Build Locally

# Using npm
npm run preview

# Or using yarn
yarn preview

This starts a local server at http://localhost:4173 serving the production build.

🌐 Deployment Options

Option 1: Static File Server (Nginx)

Nginx is excellent for serving static files with high performance.

Install Nginx

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo yum install nginx

# macOS
brew install nginx

Configure Nginx

Create a configuration file /etc/nginx/sites-available/nutricompass:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    
    # Root directory (adjust path as needed)
    root /var/www/nutricompass/dist;
    index index.html;
    
    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied expired no-cache no-store private auth;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml application/javascript;
    
    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # SPA fallback - serve index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}

Deploy

# Build the project
npm run build

# Copy dist to server
sudo mkdir -p /var/www/nutricompass
sudo cp -r dist/* /var/www/nutricompass/

# Enable site
sudo ln -s /etc/nginx/sites-available/nutricompass /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

Enable HTTPS with Let's Encrypt

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# Auto-renewal is configured automatically

Option 2: Apache Server

Install Apache

# Ubuntu/Debian
sudo apt update
sudo apt install apache2

# Enable required modules
sudo a2enmod rewrite
sudo a2enmod headers

Configure Apache

Create /etc/apache2/sites-available/nutricompass.conf:

<VirtualHost *:80>
    ServerName your-domain.com
    ServerAlias www.your-domain.com
    DocumentRoot /var/www/nutricompass/dist
    
    <Directory /var/www/nutricompass/dist>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
        
        # SPA fallback
        RewriteEngine On
        RewriteBase /
        RewriteRule ^index\.html$ - [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.html [L]
    </Directory>
    
    # Compression
    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript application/json
    </IfModule>
    
    # Caching
    <IfModule mod_expires.c>
        ExpiresActive On
        ExpiresByType text/css "access plus 1 year"
        ExpiresByType application/javascript "access plus 1 year"
        ExpiresByType image/png "access plus 1 year"
        ExpiresByType image/jpeg "access plus 1 year"
        ExpiresByType image/svg+xml "access plus 1 year"
    </IfModule>
    
    # Security headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
</VirtualHost>

Deploy

# Build and copy
npm run build
sudo mkdir -p /var/www/nutricompass
sudo cp -r dist/* /var/www/nutricompass/

# Enable site
sudo a2ensite nutricompass.conf
sudo systemctl restart apache2

Option 3: Node.js Express Server

For environments where you want a Node.js server.

Create Server File

Create server.js in the project root:

const express = require('express');
const path = require('path');
const compression = require('compression');

const app = express();
const PORT = process.env.PORT || 3000;

// Enable gzip compression
app.use(compression());

// Serve static files from dist folder
app.use(express.static(path.join(__dirname, 'dist'), {
  maxAge: '1y',
  etag: false
}));

// SPA fallback - serve index.html for all routes
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

app.listen(PORT, () => {
  console.log(`🌿 NutriCompass running at http://localhost:${PORT}`);
});

Install Dependencies and Run

# Install production dependencies
npm install express compression

# Build the app
npm run build

# Start the server
node server.js

# Or use PM2 for production
npm install -g pm2
pm2 start server.js --name nutricompass
pm2 save
pm2 startup

Option 4: Docker

Create Dockerfile

Create Dockerfile in the project root:

# Build stage
FROM node:18-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci

# Copy source files
COPY . .

# Build the app
RUN npm run build

# Production stage
FROM nginx:alpine

# Copy custom nginx config
COPY nginx.conf /etc/nginx/conf.d/default.conf

# Copy built assets from builder
COPY --from=builder /app/dist /usr/share/nginx/html

# Expose port
EXPOSE 80

# Start nginx
CMD ["nginx", "-g", "daemon off;"]

Create nginx.conf

Create nginx.conf in the project root:

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # Gzip
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Create docker-compose.yml (Optional)

version: '3.8'

services:
  nutricompass:
    build: .
    ports:
      - "80:80"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3

Build and Run

# Build Docker image
docker build -t nutricompass .

# Run container
docker run -d -p 80:80 --name nutricompass nutricompass

# Or use docker-compose
docker-compose up -d

# View logs
docker logs -f nutricompass

# Stop container
docker stop nutricompass

Option 5: Vercel (Recommended)

Vercel offers the easiest deployment with automatic CI/CD.

Method 1: Vercel CLI

# Install Vercel CLI
npm install -g vercel

# Login
vercel login

# Deploy (from project root)
vercel

# Deploy to production
vercel --prod

Method 2: GitHub Integration

Push your code to GitHub
Go to vercel.com
Click "New Project"
Import your GitHub repository
Vercel auto-detects Vite and configures everything
Click "Deploy"

vercel.json (Optional)

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Option 6: Netlify

Method 1: Netlify CLI

# Install Netlify CLI
npm install -g netlify-cli

# Login
netlify login

# Build the project
npm run build

# Deploy draft
netlify deploy --dir=dist

# Deploy to production
netlify deploy --dir=dist --prod

Method 2: GitHub Integration

Push code to GitHub
Go to netlify.com
Click "New site from Git"
Connect your repository
Set build command: npm run build
Set publish directory: dist
Click "Deploy site"

netlify.toml

Create netlify.toml in project root:

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

Option 7: GitHub Pages

Configure Vite for Subdirectory

Update vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/nutricompass/', // Your repo name
})

Create GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build
        env:
          VITE_USDA_FDC_API_KEY: ${{ secrets.VITE_USDA_FDC_API_KEY }}

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Add a repository secret named VITE_USDA_FDC_API_KEY (Settings → Secrets and variables → Actions). Note: any VITE_ variable is bundled into client-side code and is publicly visible.

Enable GitHub Pages

Go to your repository Settings
Navigate to Pages
Source: "GitHub Actions"
Push to main branch to trigger deployment

Option 8: AWS S3 + CloudFront

Create S3 Bucket

# Create bucket
aws s3 mb s3://nutricompass-app --region us-east-1

# Enable static website hosting
aws s3 website s3://nutricompass-app --index-document index.html --error-document index.html

# Build and sync
npm run build
aws s3 sync dist/ s3://nutricompass-app --delete

Bucket Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::nutricompass-app/*"
    }
  ]
}

CloudFront Distribution

Create CloudFront distribution
Origin: S3 bucket website endpoint
Create custom error response: 404 → /index.html (200)
Enable HTTPS with AWS Certificate Manager

Option 9: DigitalOcean App Platform

Push code to GitHub
Go to DigitalOcean App Platform
Create new app from GitHub
Select your repository
Configure:
- Type: Static Site
- Build Command: npm run build
- Output Directory: dist
Click "Deploy"

🔧 Environment Variables

NutriCompass runs fully offline by default. Cloud sync is optional and requires Firebase env vars. USDA FoodData Central search is optional. For GitHub Pages (static hosting), you can set VITE_USDA_FDC_API_KEY at build time (this makes the key public). To keep the key private, use a server proxy with USDA_FDC_API_KEY and set VITE_USDA_FDC_PROXY_URL.

Create `.env` file

VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id
VITE_USDA_FDC_API_KEY=your_usda_api_key
VITE_USDA_FDC_PROXY_URL=

You can copy from .env.example and fill in your project values.

Server Environment (USDA Proxy)

Set this on the server that runs server.js (never in client-side VITE_ vars). GitHub Pages cannot run server.js, so only use this if you deploy a separate backend/proxy.

USDA_FDC_API_KEY=your_usda_api_key

For local development, you can run server.js with that variable set and add VITE_USDA_FDC_PROXY_URL=http://localhost:3000 to your .env so the Vite app can reach the proxy.

Access in Code

const apiKey = import.meta.env.VITE_FIREBASE_API_KEY;

Production Environment

For production deployments, set these in your hosting platform's environment settings.

🔥 Firebase Setup (Optional Cloud Sync)

Cloud sync is optional and only activates when Firebase env vars are present. Local mode uses localStorage/IndexedDB and works fully offline. A “Sync to cloud” toggle appears only when Firebase is configured.

1) Create Firebase project

Enable Authentication → providers: Email/Password + Google (optional).
Enable Firestore (in production mode).

2) Authorized domains

Add your GitHub Pages domain: YOUR_USERNAME.github.io
Add local dev: localhost

3) Firestore data model

users/{uid}/profile (doc)
users/{uid}/settings (doc)
users/{uid}/stacks/{stackId} (collection)
users/{uid}/logs/{date} (collection, docId = YYYY-MM-DD)

4) Security rules

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{uid}/{document=**} {
      allow read, write: if request.auth != null && request.auth.uid == uid;
    }
  }
}

5) GitHub Pages + Firebase Auth redirect

Firebase Auth redirects must include the GitHub Pages base path.
Add https://YOUR_USERNAME.github.io/nutrient-recommendation-app/ to Authorized domains.
Firebase CLI/Firebase Hosting is not required when deploying to GitHub Pages.

🎨 Customization

Adding New Supplements

Edit src/data/supplements.ts:

export const supplements: Supplement[] = [
  // ... existing supplements
  {
    id: 'new-supplement',
    name: 'New Supplement Name',
    type: 'herb', // vitamin, mineral, herb, amino-acid, etc.
    category: 'Adaptogen',
    description: 'Description here...',
    benefits: ['Benefit 1', 'Benefit 2'],
    dosage: '500mg daily',
    timing: 'Morning with food',
    evidence: 'moderate',
    goals: ['energy', 'stress'],
    bodySystems: ['nervous', 'endocrine'],
    // ... other fields
  }
];

Updating Nutrient Food Data

Food-source data lives in src/data/supplements.ts:

nutrientFoodMapping stores NRV/AI reference values and sources
nutrientFoodSources lists foods, amounts, and % NRV/Reference

If you add a new nutrient with food data, also ensure the supplement ID maps to the nutrient ID in src/data/nutrientFoodSources.ts.

Modifying Goal Analysis

Edit src/utils/goalAnalyzer.ts to add new goal keywords and body system mappings.

Styling Changes

Global styles: src/index.css
Tailwind config: tailwind.config.js
Component-specific: Inline Tailwind classes

🔌 API Integration (Future)

The app is designed to support future API integration:

// Example API service
const SupplementAPI = {
  async getRecommendations(goals: string[], profile: UserProfile) {
    const response = await fetch(`${API_URL}/recommendations`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${API_KEY}`
      },
      body: JSON.stringify({ goals, profile })
    });
    return response.json();
  },
  
  async trackProgress(supplementId: string, metrics: TrackingData) {
    // Track user progress with a supplement
  }
};

🤝 Contributing

We welcome contributions! Here's how:

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run linting: npm run lint
Run type checking: npm run typecheck
Build to verify: npm run build
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Guidelines

Follow existing code style
Add TypeScript types for new data
Ensure evidence ratings are accurate
Include safety information for supplements
Test on multiple browsers

Areas for Contribution

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Nutritional data compiled from peer-reviewed research
Food composition references: CIQUAL and EuroFIR (for vitamins/minerals)
Ayurvedic knowledge from traditional texts and modern research
Built with React, Vite, TypeScript, and Tailwind CSS

⚠️ Important Disclaimer

NutriCompass is for educational purposes only.

This app does not provide medical advice
Always consult a healthcare professional before starting supplements
Individual results may vary
Not intended to diagnose, treat, cure, or prevent any disease
Check for drug interactions with your doctor or pharmacist

Made with 💚 for better health education

Name		Name	Last commit message	Last commit date
Latest commit History 165 Commits
.github		.github
dist		dist
docs		docs
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
README_FERTILITY_UPDATE.md		README_FERTILITY_UPDATE.md
README_IMPLEMENTATION.md		README_IMPLEMENTATION.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
index.html		index.html
netlify.toml		netlify.toml
nginx.conf		nginx.conf
nrvValues.ts		nrvValues.ts
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
supplements.ts		supplements.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🌿 NutriCompass - Smart Supplement & Nutrition Guide

📋 Table of Contents

✨ Features

🎯 Intelligent Goal Analysis

📚 Comprehensive Database (60+ Supplements)

🔬 Evidence-Based Transparency

💊 Form Intelligence

🔍 Advanced Browse Engine

🧭 Nutrient Targets & Priority Flags

🥗 Food Source Intelligence

🍽️ Food Lookup (USDA FoodData Central + Open Food Facts)

🧪 Stack Builder

📈 Progress & Lab Tracking

👤 Personalization

⚖️ Metabolic Metrics

📖 Learn Section

🛡️ Safety First

📸 Screenshots

📋 Prerequisites

Required

Optional (for deployment)

🚀 Quick Start (Local Development)

1. Clone or Download the Project

2. Install Dependencies

3. Start Development Server

4. Open in Browser

5. Run Linting & Type Checking (Optional)

📁 Project Structure

🏗️ Building for Production

Build the Application

Preview Production Build Locally

🌐 Deployment Options

Option 1: Static File Server (Nginx)

Install Nginx

Configure Nginx

Deploy

Enable HTTPS with Let's Encrypt

Option 2: Apache Server

Install Apache

Configure Apache

Deploy

Option 3: Node.js Express Server

Create Server File

Install Dependencies and Run

Option 4: Docker

Create Dockerfile

Create nginx.conf

Create docker-compose.yml (Optional)

Build and Run

Option 5: Vercel (Recommended)

Method 1: Vercel CLI

Method 2: GitHub Integration

vercel.json (Optional)

Option 6: Netlify

Method 1: Netlify CLI

Method 2: GitHub Integration

netlify.toml

Option 7: GitHub Pages

Configure Vite for Subdirectory

Create GitHub Actions Workflow

Enable GitHub Pages

Option 8: AWS S3 + CloudFront

Create S3 Bucket

Bucket Policy

CloudFront Distribution

Option 9: DigitalOcean App Platform

🔧 Environment Variables

Create .env file

Server Environment (USDA Proxy)

Access in Code

Production Environment

🔥 Firebase Setup (Optional Cloud Sync)

1) Create Firebase project

2) Authorized domains

3) Firestore data model

4) Security rules

Create `.env` file

Packages