Snap your food, track calories and macros, and build healthier eating habits — offline-first, with optional cloud sync.
Live demo: https://nutriscan-nine-omega.vercel.app
NutriScan is a mobile-friendly web app: snap a photo of a meal, get AI-powered nutrition analysis, and track your daily intake across a dashboard, food diary, and insights views. It works fully offline out of the box — sign in with Google to back up and sync your diary across devices.
- Features
- How it works
- Cloud sync
- Tech stack
- Getting started
- Environment variables
- API routes
- Deployment
- Project structure
- Roadmap
- FAQ
- Contributing
- License
- AI food scanner — live camera viewfinder with capture, upload/drag-and-drop fallback, or plain-text description. Photos are downscaled client-side, then analyzed (calories, protein, carbs, fat, fiber, sugar, sodium) via Google Gemini. Rename items, adjust portions in grams, pick the meal, and add them one by one. Automatic retries on rate limits and model overload.
- Dashboard — daily calorie budget, macro rings, water tracker, and meal summaries at a glance.
- Food diary — breakfast, lunch, dinner, and snacks, with manual entry and per-item delete.
- Insights — charts and trends over time (built with Recharts), plus a weekly report with week-over-week deltas, low-protein and over-goal flags, and one-tap copy to share
- Weight tracking — log weigh-ins in Profile, see the trend chart with change-per-week stats; keeps profile weight, BMI, and goals in sync.
- Onboarding — guided setup with personalized calorie and macro goals (metric + imperial units).
- Profile — Google sign-in with Firestore cloud sync, BMI overview, editable goals, JSON backup export/import.
- PWA — installable on mobile (192/512 px + maskable icons), works offline via service worker with cached fonts.
- Onboard — set your goal (lose, maintain, or gain), activity level, and units to get daily calorie and macro targets.
- Scan — take a photo of your meal. It is downscaled in the browser and sent to
POST /api/analyze-food, where Gemini identifies the foods and estimates calories, protein, carbs, fat, and fiber per item. - Review — check the detected items, rename them, choose the meal, and confirm.
- Track — the meal lands in your diary and counts toward your daily rings on the dashboard.
- Improve — open Insights to spot trends (late-night snacking, low-protein days) and adjust.
- Sync (optional) — sign in with Google to back up your diary to Firestore and keep every device in sync.
Cloud sync is optional. Without Firebase keys the app runs 100% locally (localStorage) and the Profile tab explains how to enable sync.
When signed in:
- Your diary lives in one Firestore document per user:
users/{uid}(profile, goals, entries, water,updatedAt). - Entries merge by id across devices — logging lunch on your phone and dinner on your desktop keeps both.
- Profile, goals, and water follow last-write-wins using the document timestamp.
- The first sign-in keeps the current device's values and pushes them up, so setup is never overwritten by an empty cloud doc.
- Changes auto-push after ~2.5 s, other devices update live, and a Sync Now button forces a round-trip.
- The Firebase SDK is dynamically imported, so offline users never download it (~7 KB of sync plumbing in the main bundle instead of ~400 KB).
Firestore rules (owner-only access) are documented in .env.example.
| Layer | Technology |
|---|---|
| UI | React 19, Tailwind CSS v4, Vite 8, TypeScript 5 |
| Charts | Recharts (lazy-loaded) |
| AI analysis | Google Gemini (/api/analyze-food) |
| Auth + database | Firebase Auth (Google), Firestore (both lazy-loaded) |
| Rate limiting | Upstash Redis (optional, graceful fallback to in-memory) |
| Error tracking | Sentry (optional) |
| PWA | vite-plugin-pwa (Workbox precache + Google Fonts caching) |
| Hosting | Vercel (serverless api/ functions) |
| Tests | Vitest (unit), Playwright (e2e, mobile viewport) |
Prerequisites: Node.js 22+, pnpm 10+ (see .mise.toml)
# Install dependencies
pnpm install
# Configure environment
cp .env.example .env
# then fill in your keys (see "Environment variables" below)
# Start the dev server (http://localhost:8443)
pnpm devThe dev server emulates the Vercel
api/functions locally (seedevApiPlugininvite.config.ts), so food scanning works without deploying.
Other scripts:
pnpm build # production build into dist/
pnpm preview # serve the production build locally
pnpm typecheck # tsc --noEmit
pnpm test # unit tests (vitest)
pnpm test:e2e # end-to-end tests (playwright, mobile viewport)
pnpm verify # typecheck + test + build
pnpm format # format with oxfmtFirst e2e run needs the browser binary:
pnpm exec playwright install chromium.
See .env.example for the full list with setup instructions.
| Variable | Required | Description |
|---|---|---|
GEMINI_API_KEY |
Yes (for food scan) | Free key from Google AI Studio |
GEMINI_MODEL |
No | Model override (default: gemini-3.6-flash) |
UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN |
No | Global API rate limiting (Vercel Marketplace → Upstash Redis; per-instance memory limits apply without it) |
VITE_SENTRY_DSN |
No | Production error tracking |
VITE_FIREBASE_API_KEY et al. |
Yes (for login/sync) | Firebase web app config |
- Create a project at console.firebase.google.com (Analytics optional).
- Build → Authentication → Sign-in method → Google → Enable, pick a support email, save.
- Build → Firestore Database → Create database (production mode) and publish the owner-only rules from
.env.example. - Project overview → Add app → Web, copy the config values into
.env(and into Vercel's env vars for production). - Authentication → Settings → Authorized domains: add
localhostand your production domain.
Served natively by Vercel in production, and emulated under vite dev locally:
| Route | Method | Description |
|---|---|---|
/api/analyze-food |
POST | Accepts a food photo (base64 data URL in { "image" }), returns { "foods": [...] } with calories and macros per item |
/api/health |
GET | Health check ({ "ok": true }) |
analyze-food details:
- Rate-limited to 20 requests/min per IP (Upstash sliding window, in-memory fallback).
- Rejects bodies over ~6 MB (
413); the client downscales photos to stay well under that. - 30 s upstream timeout; client aborts at 60 s with retries on
429/502/503/504. - Error codes:
400missing/invalid image ·405wrong method ·413too large ·429rate-limited ·500key missing/server error ·502/504vision API failure/timeout.
Two supported paths:
- Full app (recommended): connect the repo to Vercel (import project → set env vars → deploy). Pushes to
mainauto-deploy usingvercel.json. SetGEMINI_API_KEYand (optionally) Firebase + Upstash vars in the project settings. - Static demo: serve the prebuilt
dist/as a static site — e.g.vercel ./dist --prod --yes --name nutriscan. Note this serves the UI only;/api/*and login-backed sync require the full deployment.
vercel.jsonsetsmaxDuration: 60on the scan function (needs a Pro plan) so long Gemini calls aren't cut off on Hobby's shorter limit.
├── api/ # Vercel serverless functions (analyze-food, health)
├── e2e/ # Playwright specs (mobile viewport, mocked scan API)
├── public/ # icon.svg + PWA raster icons (192/512, maskable)
├── src/
│ ├── App.tsx # shell + routing + cloud-sync wiring
│ ├── Scanner / Dashboard / Diary / Insights / Onboarding / Profile
│ ├── report.ts # weekly report builder (deltas, flags, share text)
│ ├── weight.ts # weigh-in log, merge, trend stats
│ ├── firebase.ts # lazy Firebase init (null when unconfigured)
│ ├── sync.ts # merge strategy (entries union, last-write-wins)
│ ├── useCloudSync.ts # sign-in, auto-push, live updates
│ ├── storage.ts # localStorage layer + backup export/import
│ ├── *.test.ts # unit tests (storage, utils, sync)
│ └── index.css # Tailwind v4 theme + global styles
├── dist/ # production build output (gitignored)
├── index.html # Vite HTML shell (Figma Make slots)
├── vite.config.ts # Vite + Tailwind + PWA + dev API emulation
├── vercel.json # function config + security headers
├── playwright.config.ts # e2e test config (cross-platform env)
└── vitest.config.ts # unit test config
Local data lives under localStorage keys prefixed ns_ (ns_profile, ns_goals, ns_entries, ns_water, …); entries older than 90 days are trimmed automatically.
- AI food scanning with Gemini
- Dashboard, diary, insights, onboarding, profile
- Water intake tracking
- Google sign-in + Firestore cloud sync
- PWA offline support
- Live demo deployment
- Weekly nutrition reports with highlights and low-protein flags
- Weight progress tracking with trend chart
- Micronutrient detail per item (fiber, sugar, sodium surfaced from scan results)
- Text-based meal logging (describe a dish, no photo needed)
- Per-item portion editor (adjust grams after scanning)
- Barcode lookup for packaged foods (Open Food Facts)
- Favorite meals and one-tap re-logging
- Meal-reminder notifications (wiring up the Profile toggle via Notification API + service worker)
- Custom foods and saved recipes
- Streaks and goal celebrations
- Dark mode
- Multi-language support
- Apple Health / Health Connect import
- Shareable progress cards and PDF export
- CI checks on pull requests (verify + e2e)
- Choose an open-source license (MIT)
- Prune leftover Figma scaffold duplicates (
imports/,src/imports/Component1)
Which package manager should I use?
pnpm (there's a pnpm-lock.yaml). npm works in a pinch, but don't commit a package-lock.json.
Do I need Firebase to run the app? No. Without Firebase keys everything works locally in your browser. Sign-in and cross-device sync light up once the keys are set (see Cloud sync).
Sign-in popup was blocked / closed instantly. Allow popups for the site and try again. In private windows, use the upload flow — popups are often restricted there.
"This domain is not authorized" on sign-in.
Add the exact domain (e.g. localhost, your Vercel URL) under Firebase console → Authentication → Settings → Authorized domains.
Where is my data stored?
Locally under localStorage keys starting with ns_. When signed in, a copy syncs to Firestore at users/{your-uid}. Export a JSON backup from Profile → Your Data any time.
The dev server port is already in use.
The port comes from $PORT (default 8443). Free it or start with another one (PowerShell: $env:PORT="8444"; pnpm dev).
Food scan fails locally.
Make sure GEMINI_API_KEY is set in .env and restart the dev server — API handlers read env at startup.
Images are large — any limits? Client-side photos are downscaled to max 1024 px and rejected client-side over ~5 MB base64; the API rejects bodies over ~6 MB.
- Fork the repo and create a feature branch (
git checkout -b feat/my-change). - Run
pnpm verifybefore pushing (typecheck + tests + build); runpnpm test:e2efor UI changes (needspnpm exec playwright install chromiumonce). - Format with
pnpm format. - Open a pull request against
mainwith a short description and screenshots for UI changes.
MIT — see LICENSE.