Local development

Set up the Netstamp workspace, run each application surface, regenerate contracts, and use focused validation commands.

Netstamp is a pnpm workspace with a Go controller and probe agent, a TypeSpec API contract, a React/Vite application, a shared React UI package, and an Astro documentation site.

Prerequisites

Install:

  • Node.js 22.12 or newer;
  • pnpm 11.9;
  • Go 1.26 for controller or probe-agent work;
  • just for the repository task commands;
  • Docker when you need PostgreSQL, TimescaleDB, or the complete self-host stack.

Clone the repository and install workspace dependencies:

bash
git clone https://github.com/yorukot/netstamp.git
cd netstamp
pnpm install

The install step also configures the repository’s Git hooks.

Start PostgreSQL For Controller Development

The controller needs PostgreSQL with the TimescaleDB extension. One local option is to start only the database service from the deployment Compose file:

bash
cp deployments/docker/example.env deployments/docker/.env
docker compose --env-file deployments/docker/.env \
-f deployments/docker/compose.yaml up -d postgres

Copy the controller environment template:

bash
cp server/.env.example server/.env

Set DATABASE_PASSWORD in server/.env to the same value used by deployments/docker/.env, then apply migrations:

bash
just backend-migrate-up

Both environment files are local configuration. Do not commit populated environment files or production credentials.

Run The Controller And Web App

Start the Go controller with Air hot reload:

bash
just dev

The default controller listens on http://localhost:8080. In another terminal, start Vite:

bash
just web-dev

Vite proxies /api to http://localhost:8080 by default. Set VITE_NETSTAMP_API_PROXY_TARGET if your controller uses another origin.

The first account successfully registered on a new database becomes a system administrator. This bootstrap rule is only for an empty instance; system administrator access is separate from project membership.

Run Docs And Storybook

Start the Astro documentation site:

bash
just docs-dev

Start the shared component catalog separately when working on @netstamp/ui:

bash
pnpm dev:storybook

The production docs build generates a static Storybook site before Astro builds. Avoid committing generated preview or screenshot artifacts unless the repository explicitly treats them as source.

Build And Test By Area

Use focused commands while iterating:

bash
pnpm --filter @netstamp/web typecheck
pnpm --filter @netstamp/web lint
pnpm --filter @netstamp/web test
pnpm --filter @netstamp/web build

pnpm --filter @netstamp/docs build
pnpm --filter @netstamp/ui build

just backend-test
just backend-lint
just backend-build

Repository-wide entry points are:

bash
just lint
just test
just build

Change The API Contract

TypeSpec under api/ is the source of truth for the HTTP contract. After changing it, regenerate every checked-in consumer artifact:

bash
pnpm generate:openapi

That command refreshes the public OpenAPI document, the controller’s embedded copy, and the web app’s generated TypeScript declarations. Do not edit those generated files by hand.

Change User-Visible Text

English UI resources and English MDX are translation sources. Add semantic translation keys instead of embedding new English prose directly in React components, then run:

bash
pnpm check:i18n
pnpm test:i18n
pnpm test:web
pnpm test:docs:i18n

Read Translating Netstamp before changing localized content. It explains which files Crowdin manages and which technical tokens must remain unchanged.

Follow Area Guides

Before editing, read the closest AGENTS.md in the repository. Backend, API, web, shared UI, and docs work have different source-of-truth and validation rules. Visible UI work must also follow design.md.

For branch names, commits, pull requests, and the full review checklist, continue to Contributing.