Gabriel Brown
87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
```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`
|
|
- 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.
|
|
|
|
```sh
|
|
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
|
|
|
|
```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 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.
|