Skip to Content
Settlr

Development setup

Install the monorepo, connect a Convex deployment and run Settlr locally.

Requirements

  • Node.js 22 or newer
  • pnpm 10, the only supported package manager (the version is pinned in the root package.json)
  • A free Convex account

Set up

Install

pnpm install

This installs every workspace: apps/web, apps/mobile, apps/docs, packages/backend and packages/shared.

Create a Convex dev deployment

pnpm dev:convex

The first run asks you to sign in to Convex and creates a dev deployment. It writes CONVEX_DEPLOYMENT to packages/backend/.env.local, then keeps pushing convex/ to the deployment on every change. Leave it running.

Point the web app at it

Create apps/web/.env.local with the deployment's two URLs (both are on the Convex dashboard, under Settings → URL & deploy key):

apps/web/.env.local
NEXT_PUBLIC_CONVEX_URL=https://<deployment>.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://<deployment>.convex.site

Configure sign-in

Set the deployment's required environment variables (run these in packages/backend):

pnpm exec convex env set SITE_URL=http://localhost:3000
pnpm exec convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)

See Environment variables for the optional ones (Google sign-in, email, the assistant).

Run the web app

pnpm dev

Open http://localhost:3000.

Signing in without an inbox

Without a Resend API key, sign-in codes aren't emailed. Read them in the deployment's logs with pnpm exec convex logs (in packages/backend).

Commands

Run these from the repository root. Turborepo runs each one in the workspaces that define it.

CommandWhat it does
pnpm devThe web app on localhost:3000
pnpm dev:docsThese docs on localhost:3001
pnpm dev:convexconvex dev: pushes packages/backend/convex to your dev deployment on every change
pnpm typecheckType-checks every workspace
pnpm buildBuilds the web app and the docs
pnpm startServes the web app's production build

To run a script in one workspace, filter it: pnpm --filter web build, pnpm --filter docs dev.

Before you push

There's no test suite or linter yet. Run:

pnpm typecheck && pnpm build

The build also enforces the server/client boundaries: a server-only import reaching a client bundle, or a server component calling a function from a 'use client' module, fails it. Then try the change in the browser, in dark mode and at phone width.

Calling Convex functions as a test user

Run the Convex CLI with node (on Windows, cmd.exe mangles the JSON when it goes through pnpm exec), from packages/backend:

node node_modules/convex/bin/main.js run \
  --identity '{"tokenIdentifier":"test|u1","name":"Test"}' \
  friends:list '{}'

On this page