# 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 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.