Gabriel Brown
85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# 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.
|