# Convex Turbo Monorepo

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.

```sh
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`

Next and Expo run on the host. Convex uses a self-hosted data volume and does
not use Postgres by default. The commented `POSTGRES_URL` in Compose is an
opt-in example for cloned projects that explicitly choose Convex-on-Postgres.

```sh
bun db:down        # stop; preserve Convex data
bun db:down:wipe   # remove the Convex volume and generated admin key
```

Normal `bun db:up` never contacts staging and does not start Postgres. It starts
the local Convex backend and 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

```sh
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 has no
Postgres service by default. A commented `POSTGRES_URL` remains only as an
optional Convex-on-Postgres example for cloned projects. 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.