spoon/README.md

Spoon

A reusable Bun/Turborepo template with Next.js 16, Expo, self-hosted Convex, shared UI/config packages, Vitest, and Docker deployment.

Local setup

Requirements: Bun 1.3.10, Docker or Podman, Node 22, and the Infisical CLI.

bun install --frozen-lockfile
infisical login
infisical init
bun db:up
bun dev:next

The committed .infisical.json links this repository to its own Infisical project. Local commands read dev by default and never fall back to .env files. Select staging with INFISICAL_ENV=staging bun dev:next.

Local services:

• Next.js: http://localhost:3000
• Convex API: http://localhost:3210
• Convex dashboard: http://localhost:6791
• Convex Postgres: localhost:5432

Next and Expo run on the host. Spoon runs local Convex with Postgres storage by default. Local Compose creates the database named by LOCAL_INSTANCE_NAME because the Convex backend opens that database inside the Postgres cluster. Convex receives a database-cluster URL without a path.

bun db:down        # stop; preserve local data
bun db:down:wipe   # remove local data volumes and generated admin key

Normal bun db:up never contacts staging. It starts local Postgres, Convex, and the dashboard, generates a machine-local Convex admin key in .local/dev.generated.env when needed, deploys functions/schema, and configures local Convex Auth keys.

Physical devices cannot resolve their own localhost; override the public Convex URL with the development host's LAN address when testing Expo on-device.

Environment model

• Local dev and staging: Infisical.
• Generated local state: .local/<environment>.generated.env.
• CI/CD: Gitea DOTENV_PROD, materialized only as a temporary runner file.
• Docker compilation: explicit Compose build args; .env* stays outside the image context.

Run sh scripts/with-env dev -- <command> for an environment-aware command or sh scripts/export-env dev to materialize a temporary merged dotenv stream. Do not commit or maintain root .env files.

Development and quality

bun dev:next
bun dev:expo
bun lint:ws
bun format
bun lint
bun typecheck
bun test:unit
bun test:integration
bun test:component
SKIP_E2E=1 bun run ci:check

bun test:e2e starts the isolated local stack and currently performs generic stack smoke checks. It stops the stack afterward only when the stack was not already running. It skips in CI and when SKIP_E2E=1 is set.

Shared dependency versions belong in root catalogs. Edit the root catalog, run bun install, then bun lint:ws; do not run bun update inside a workspace.

Deployment

Production Compose retains the self-hosted Convex backend/dashboard and expects POSTGRES_URL to be a database-cluster URL without a database path. Gitea runs the quality gate first, builds the Next image from a temporary Gitea-secret env file, then pushes SHA and latest tags. CI never installs or invokes Infisical.