Development
Requirements
Section titled “Requirements”Node 24.11 or later, pnpm 12 (corepack enable) and Docker.
Set up
Section titled “Set up”-
Install dependencies and run every check once:
Terminal window pnpm installpnpm check # format check, lint, typecheck, tests, builds, package lint, API reports, unused code, size limits -
Start PostgreSQL for development (on
127.0.0.1:5432):Terminal window docker compose -f deploy/docker-compose.dev.yml up -d -
Create
apps/collector/.envfromdeploy/.env.example, withDATABASE_URL=postgres://shardlens:shardlens-dev@127.0.0.1:5432/shardlensandSHARDLENS_PUBLIC_URL=http://localhost:8080. -
Build, start the collector and load 30 days of fictional demo data:
Terminal window pnpm buildnode --env-file=apps/collector/.env apps/collector/dist/main.jsnode --env-file=apps/collector/.env apps/collector/dist/cli/seed.jsOpen
http://localhost:8080and sign in with the read key from your.env.
Layout
Section titled “Layout”Directorypackages/
Directoryschema/ wire format (zod), JSON Schema, metric and data-collected registers
- …
Directorycore/ zero-dependency SDK core
- …
Directorydiscordjs/ discord.js adapter, with the overhead benchmark in bench/
- …
Directoryhttp/ adapter for HTTP-interaction bots
- …
Directoryclient/ typed reader of a collector, for your own dashboard or scripts
- …
Directoryexporter-prometheus/ and exporter-otel/ metrics exporters
- …
Directorycli/ the shardlens CLI
- …
Directoryapps/
Directorycollector/ Fastify and PostgreSQL
- …
Directorydashboard/ React dashboard served by the collector
- …
Directorydocs/ this site
- …
Directoryexamples/ basic-bot, sharded-bot, hybrid-sharding, audit-mode, cloudflare-worker
- …
Directorydeploy/ Docker Compose, Caddyfile, .env.example
- …
Directorydocs/adr/ architecture decision records
- …
The rules every change follows are in
AGENTS.md, for people and coding agents alike. The most
important:
- The SDK never throws into, blocks or crashes the host bot.
- Never store or log tokens, REST paths, request headers, message content or raw user IDs.
- Privacy mode is the default. No per-user views.
- Public discord.js APIs only.
- Changes to collected fields, metrics, options or the HTTP API update these docs in the same pull request.
pnpm --filter @shardlens/docs devCode samples live in apps/docs/snippets/ and are type-checked, so they can’t drift from the API. The data-collected,
metrics, SDK options, SDK reference and HTTP API pages are generated from the code.
The public demo
Section titled “The public demo”The public demo is an ordinary collector with fictional data and SHARDLENS_DEMO=true, which lets anyone view the
dashboard read-only (settings, keys, alerts, audit data and ingest stay locked):
echo "SHARDLENS_DEMO=true" >> .env # next to docker-compose.ymldocker compose up -ddocker compose exec collector node dist/cli/seed.jsThe seeder sends 30 days of made-up traffic through the real SDK client, so salts, hashing and rollups are exercised exactly as for a real bot. It refuses to run against a database that already has interactions, so it can’t mix fictional numbers into a real bot’s analytics.