The public website of SoilStack, an agri-tech company in the DRC: company pages, blog and product catalogue in French (default) and English, plus an admin dashboard to manage the content.
Stack: Next.js (App Router) · TypeScript (strict) · Tailwind CSS · shadcn/ui · Convex · next-intl
See CLAUDE.md for the permanent rules this codebase follows (permissions, content model, images, performance, i18n, audit logging, testing, git workflow).
- Node 22+ (the Convex CLI requires it). With nvm:
nvm use(reads.nvmrc). - pnpm 10 (
corepack enable).
Install dependencies (this also installs the Git hooks):
pnpm installConnect Convex (first time only — logs you in, links/creates a deployment,
and writes NEXT_PUBLIC_CONVEX_URL into .env.local). Leave it running in
its own terminal tab while you develop, since it also pushes function
changes live:
pnpm dlx convex devThe repo may have been bootstrapped against an anonymous local Convex backend (
CONVEX_DEPLOYMENT=anonymous:...in.env.local). Runpnpm dlx convex loginand thenpnpm dlx convex devto link it to your Convex account and a cloud project.
Then, in a second terminal, seed the reference data (permissions, the Super Admin role and the starter roles) — safe to run any number of times, and worth re-running after pulling changes:
pnpm dlx convex run seed:seedReferenceDataThen run the app:
pnpm devOpen http://localhost:3000 — it redirects to
/fr (or /en for an English browser).
The admin lives at /fr/admin (or /en/admin). There is no public
sign-up: accounts are created by an administrator.
-
Signing keys. Convex Auth needs
JWT_PRIVATE_KEY,JWKSandSITE_URLon the deployment. The simplest way ispnpm dlx @convex-dev/auth --web-server-url http://localhost:3000(it may also offer to edit files that already exist — keep the repo's versions), or follow the manual setup. Check withpnpm dlx convex env list. -
First Super Admin. Set who it is, then run the seed once:
pnpm dlx convex env set SUPER_ADMIN_NAME "Your Name" pnpm dlx convex env set SUPER_ADMIN_EMAIL you@example.com pnpm dlx convex run seed:seedSuperAdmin
The output shows a temporary password, once. Log in at
/fr/admin/loginwith it; you'll be asked to choose your own. Running it again does nothing once a Super Admin exists. -
Everyone else: the Super Admin creates their accounts in Users and shares the temporary password shown once. A forgotten password is reset there too.
Public pages are cached. When something is published in the admin, Convex tells the site to refresh it. Both sides share a secret:
# Generate one value and use it in both places.
node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))'
pnpm dlx convex env set REVALIDATE_SECRET <value> # Convex
echo "REVALIDATE_SECRET=<value>" >> .env.local # Next.js (Vercel: project env vars)Convex's SITE_URL must point to the site (http://localhost:3000 in
development, the real domain in production). Without the secret, pages
still refresh on their own within an hour.
NEXT_PUBLIC_SITE_URL (in .env.local, and in the hosting provider's
environment for production) is the public site's absolute address, used
by the sitemap, share links and structured data — e.g.
https://soilstack.cd in production, http://localhost:3000 locally.
Production runs on Vercel (website) and a Convex production
deployment (data), following the main branch. The full guide - first
setup in order, releases, domain, Search Console, backups, troubleshooting
- is in docs/deployment.md.
| Variable | Where | What for |
|---|---|---|
CONVEX_DEPLOY_KEY |
Vercel (Production) | lets the build push functions and schema to Convex prod |
REVALIDATE_SECRET |
Vercel and Convex (same value) | publishing refreshes the cached pages |
NEXT_PUBLIC_SITE_URL |
Vercel | the site's address in the sitemap, share links and structured data |
ENABLE_EXPERIMENTAL_COREPACK |
Vercel | 1: build with the pnpm version from package.json |
SITE_URL |
Convex | the site's address, for sign-in and the refresh notice |
JWT_PRIVATE_KEY, JWKS |
Convex | sign-in keys (npx @convex-dev/auth --prod) |
SUPER_ADMIN_NAME, SUPER_ADMIN_EMAIL |
Convex | who seed:seedSuperAdmin creates |
Locally, copy .env.example to .env.local (convex dev fills in the
Convex values).
| Command | What it does |
|---|---|
pnpm dev |
Next.js dev server |
pnpm build |
Production build |
pnpm lint |
ESLint |
pnpm typecheck |
TypeScript for the app and convex/ |
pnpm test |
Vitest (Convex logic via convex-test) |
- Branch from
develop, named<type>/<kebab-case-description>(types:feat,fix,refactor,chore,docs,test), e.g.feat/product-catalogue. The pre-commit hook rejects other names and runs the tests. - Open a PR into
developand fill in the PR template. Releases are a PR fromdevelopintomain. - Every Convex function ships with tests, including its permission checks.
- Every UI string goes into both
messages/fr.jsonandmessages/en.json.