yushen 4dba1cfdf0 refactor: unify API URL env var to MULTICA_API_URL

Replace scattered API_URL, MAIN_VITE_API_URL, and RENDERER_VITE_API_URL
with a single MULTICA_API_URL across all apps and packages.

- Desktop: use envPrefix to expose MULTICA_* to main process, rename
  RENDERER_VITE_API_URL → RENDERER_VITE_MULTICA_API_URL, remove
  MAIN_VITE_API_URL (now read directly via MULTICA_API_URL)
- Web: add .env.development with MULTICA_API_URL, enforce required check
  in next.config.ts, update .gitignore to allow .env.development
- Core: make MULTICA_API_URL required in api-client (no silent fallback)
- Scripts: pass MULTICA_API_URL in dev-local.sh for web process
- Turbo: update globalEnv from API_URL to MULTICA_API_URL
- Docs: update references to the new env var name

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-15 06:31:00 +08:00

2.5 KiB

Raw Blame History

Development Guide

Dev Commands

pnpm dev              # Desktop app (recommended)
pnpm dev:desktop      # Same as above
pnpm dev:gateway      # Gateway only
pnpm dev:web          # Web app only
pnpm dev:all          # Gateway + Web

pnpm build            # Production build (turbo-orchestrated)
pnpm typecheck        # Type check all packages
pnpm test             # Run tests
pnpm test:watch       # Watch mode
pnpm test:coverage    # With v8 coverage

Local Full-Stack Development

pnpm dev:local starts Gateway + Desktop + Web together with isolated data directories.

Setup:

Copy .env.example to .env at the repo root
Fill in TELEGRAM_BOT_TOKEN (get from @BotFather)
Run pnpm dev:local

Service	Address	Notes
Gateway	`http://localhost:4000`	Telegram long-polling mode
Web	`http://localhost:3000`	OAuth login flow
Desktop	—	Connects to local Gateway + Web

Data is stored in ~/.super-multica-dev and ~/Documents/Multica-dev, isolated from production.

pnpm dev:local:archive    # Archive dev data and start fresh

Environment Configuration

Desktop (apps/desktop/.env.*):

Variable	Description
`MAIN_VITE_GATEWAY_URL`	WebSocket Gateway URL for remote device pairing
`MAIN_VITE_WEB_URL`	Web app URL for OAuth login redirect

Web (apps/web/next.config.ts):

Variable	Description
`MULTICA_API_URL`	Backend API URL (required, no default)

Build for different environments:

# Desktop
pnpm --filter @multica/desktop build              # Production (.env.production)
pnpm --filter @multica/desktop build:staging      # Staging (.env.staging)

# Web (Vercel)
# Set MULTICA_API_URL in Vercel Dashboard → Settings → Environment Variables

See apps/desktop/.env.example for the full variable reference.

Monorepo Workflow

Command	Purpose
`pnpm dev`	Full dev mode — watches `core`, `types`, `utils` packages
`pnpm dev:desktop`	Desktop only — skip package watching

When modifying packages:

Edit code in packages/core, packages/types, or packages/utils
Terminal shows [core] ESM ⚡️ Build success (~100ms)
Restart Desktop to apply changes (Ctrl+C, then pnpm dev)

Why restart? Electron main process does not support hot reload — this is an Electron limitation, not ours.

2.5 KiB Raw Blame History