CheckList

Shared Checklists - built with rowboat and BetterAuth.

Features

• Real-time sync across all devices
• Offline-first (works without internet)
• Local-first data sync, self-hosted (rowboat)
• Multi-provider OAuth (Google + Apple)
• Hierarchical template organization
• Session-based shopping tracking
• Folder sharing and collaboration
• Freemium subscription tiers with Stripe billing
• White-label branding support (CheckList, kjekit)
• Mobile apps via Capacitor (Android/iOS)

Getting Started

Prerequisites

• Node.js 24 (nvm use reads .nvmrc) and npm 12 (npm install -g npm@12, once per Node install)
• Google and/or Apple OAuth credentials

Each npm major writes different lockfile metadata (optional platform binaries, dev and devOptional flags), so an install under another npm rewrites the lockfiles. The engines field in the root, backend/ and migration/jazz-export/ package.json, each of which has its own lockfile, pins the majors only (node ^24.0.0, npm ^12.0.0), since a minor version changes no lockfile and the CI host runs an older Node 24 than the laptops. Each directory's .npmrc sets engine-strict, so npm install under another major stops with EBADENGINE before it touches a lockfile. scripts/toolchain.ts checks the running Node and npm against engines; scripts/pre-land runs it, so the shared land command refuses a mismatched toolchain, and scripts/toolchain.test.ts fails if the three engines fields differ or .nvmrc names another Node major. To move to a new major, change all four in one commit and regenerate the lockfiles in the next.

npm 12 runs a dependency's install scripts only when allowScripts in that package.json approves them: esbuild and lefthook at the root, better-sqlite3 and esbuild in backend/. sharp (used only by the icon and asset scripts) stays blocked. Approve a new one with npm install-scripts approve <pkg> after reading what its script does.

Installation

npm install
cd backend && npm install && cd ..
cp .env.example .env
cp backend/.env.example backend/.env
# Edit both .env files with your OAuth credentials
npm run dev  # Runs both frontend and backend

Visit http://localhost:5173

Available dev commands:

• npm run dev - Run both frontend (port 5173) and backend (port 3001)
• npm run dev:frontend - Run only frontend
• npm run dev:backend - Run only backend

OAuth Setup

Google OAuth: https://console.cloud.google.com/ Apple OAuth: https://developer.apple.com/

Add redirect URIs:

• Development: http://localhost:5173/api/auth/callback/{provider}
• Production: https://yourdomain.com/api/auth/callback/{provider}

Environment Variables

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
APPLE_CLIENT_ID=your_apple_client_id
APPLE_CLIENT_SECRET=your_apple_client_secret
VITE_API_URL=http://localhost:3001
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

How It Works

Templates are reusable checklists organized in folders.

Sessions are created when you "use" a template - they track what's in your cart and what you've purchased without modifying the template. A session is labeled by its date until you give it a name with Rename in its row menu.

Keyboard shortcuts in a session:

• ↓ / ↑: move between items
• Space / Enter: check or uncheck the focused item
• N: open the add/edit form
• Esc: leave the session

rowboat provides:

• Real-time sync
• Offline support
• Conflict resolution (per-column, HLC-ordered last-write-wins)

BetterAuth provides:

• OAuth authentication
• Session management
• Account key storage

Stripe provides:

• Subscription billing
• Customer portal
• Webhook event handling

Subscription Tiers

• Starter (Free): Up to 3 lists, 7-day session history
• Plus ($9.99/yr): Up to 30 lists, 30-day session history
• Premium ($19.99/yr): Unlimited lists, unlimited history

Development

npm run dev          # Start dev server (frontend + backend)
npm run build        # Build for production
npm run lint         # Run linter
npm run type-check   # Check TypeScript
npm run test:run     # Run unit tests
npm run test:e2e     # Run E2E tests
npm run check        # Run type-check + lint + tests

Project Structure

See ARCHITECTURE.md for system overview and code locations.

Documentation

Getting Started:

• QUICKSTART.md - Get started in 5 minutes
• README.md - This file

Architecture & Development:

• ARCHITECTURE.md - System architecture and code organization
• CLAUDE.md - Development guide and rowboat patterns
• docs/DESIGN_SYSTEM.md - UI/UX design patterns
• docs/INDENTED_LIST_FORMAT.md - Hierarchical text import/export format

Deployment:

• DEPLOY.md - Deployment instructions

Product:

• docs/BACKLOG.md - Single project backlog (outstanding features + engineering)
• docs/ROADMAP.md - Product positioning and market analysis
• docs/MARKET_COMPARISON.md - Competitive analysis
• docs/GooglePlayStore.md - App store submission checklist

White-Label Branding

The app supports multiple brands via runtime domain detection:

• CheckList (default): checklist-app.rkroll.com
• kjekit: app.kjekit.com

Brand configuration is in src/lib/brand.ts. Set VITE_BRAND env var to override.

Deployment

See DEPLOY.md for detailed deployment instructions.

Quick start:

./deploy-full.sh init    # Initial deployment (frontend + backend)
./deploy-full.sh update  # Subsequent updates

The app deploys in two parts:

• Frontend: React SPA served by Apache (static files + SSL)
• Backend: Express/BetterAuth API service (systemd service on port 3001)

Tech Stack

• React 18 + TypeScript + Vite
• rowboat (self-hosted sync engine)
• BetterAuth (authentication)
• Stripe (billing)
• Tailwind CSS + Radix UI
• Framer Motion
• Capacitor (mobile apps)

License

PolyForm Noncommercial 1.0.0 - Free for non-commercial use.

Resources

• BetterAuth: https://better-auth.com/
• Stripe: https://stripe.com/