pnpm dev, and what the dev stack script does behind that command.
Requirements
- Node 22, the version CI runs
- pnpm
- A Hugeicons Pro registry token, needed to install the icon package. pnpm ignores tokens in a project
.npmrc, so write it to your user config withpnpm config set //npm.hugeicons.com/:_authToken "$HUGEICONS_TOKEN" - The Vercel CLI linked to the site’s Vercel project, for pulling env
Install and run
1
Install dependencies
2
Pull environment variables
vercel env pull .env.development.local, which pulls the Development environment. The local scripts (pnpm db:info, the API dev server, migrations) read .env, .env.local and .env.development.local in that order, later files overriding earlier ones, then .env.<site>.local when SITE or VITE_SITE is set on the command line. A variable already set in your shell beats every file. .env.example documents the variables and where each one is set.3
Check which database you are on
4
Start a site
dallas-images on http://localhost:3006.vercel env pull defaults to the Development environment. When you need a production connection string, for example to migrate a site, pass --environment=production. See Databases.Checking the database
pnpm db:info connects with DATABASE_URL (falling back to POSTGRES_URL, then POSTGRES_PRISMA_URL) and prints the host, database name, user, and the Postgres system_identifier, followed by row counts for photos, site_settings and users and the site keys present in site_settings.
The system_identifier comes from the Postgres control file and is unique per instance. Two connection strings that report the same identifier are the same database, however different the URLs look. To check a specific string, pass it inline:
Choosing a site key
Each command setsVITE_SITE to one site key:
resolveSite() matches the key exactly, after trimming whitespace. An unmatched key does not error: it falls back to the default site, addison, and serves that site’s branding. A typo in the key looks like a styling bug, so check it first when a local site shows the wrong theme. Each site also has its own database, so pull env from the matching Vercel project.
What the dev stack script does
pnpm dev runs scripts/dev-stack.mjs, which:
- Frees the ports the stack owns:
PORT(default 3006), the vector bridge port (default 4123), and 5173 to 5175. It also freesAPI_PORT(default 3007) in the default mode. - Prints the database host it is about to use, or a hint to run
pnpm db:infowhen the URL comes from env files. - Copies
VITE_SITEintoSITEifSITEis not set. The browser bundle readsVITE_SITE; the serverless functions readSITE. Without this,/apiwould resolve to the default site. - Starts Vite on
PORTandscripts/api-dev.tsonAPI_PORTundertsx watch.api-dev.tsimitates Vercel’s file routing and loads each handler once, so an/apicall skips the per-request bundlingvercel devdoes. Vite proxies/apito it throughVITE_API_PROXY_TARGET. Editing a file underapi/restarts the API process. - Starts the vector-editor bridge (
scripts/affinity-bridge.mjs), which the canvas uses to open SVGs in a desktop editor. A bridge crash does not stop the app.
- Default stack
- vercel dev
api-dev.ts, as described above.Giving local development its own database
Until you do this,pnpm dev writes to the live site.
1
Create a Neon branch
In the Neon console, open the site’s project, go to Branches, and create a branch from
main named dev. Branches are copy-on-write, so it is created instantly and starts with a full copy of the real data.2
Copy its connection string
Copy the
dev branch’s pooled connection string.3
Set it for Development only
In Vercel, open the project, go to Settings, then Environment Variables, and set
DATABASE_URL for Development only to that string. Then run pnpm vercel:env:pull again.4
Confirm the split
Run
pnpm db:info. The system_identifier must now differ from production’s.Next steps
Databases
Schema, patches, and migrating each site’s database.
Testing
Run Vitest in real Chromium and the Node project.