Skip to content

Development

Node 24.11 or later, pnpm 12 (corepack enable) and Docker.

  1. Install dependencies and run every check once:

    Terminal window
    pnpm install
    pnpm check # format check, lint, typecheck, tests, builds, package lint, API reports, unused code, size limits
  2. Start PostgreSQL for development (on 127.0.0.1:5432):

    Terminal window
    docker compose -f deploy/docker-compose.dev.yml up -d
  3. Create apps/collector/.env from deploy/.env.example, with DATABASE_URL=postgres://shardlens:shardlens-dev@127.0.0.1:5432/shardlens and SHARDLENS_PUBLIC_URL=http://localhost:8080.

  4. Build, start the collector and load 30 days of fictional demo data:

    Terminal window
    pnpm build
    node --env-file=apps/collector/.env apps/collector/dist/main.js
    node --env-file=apps/collector/.env apps/collector/dist/cli/seed.js

    Open http://localhost:8080 and sign in with the read key from your .env.

  • 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:

  1. The SDK never throws into, blocks or crashes the host bot.
  2. Never store or log tokens, REST paths, request headers, message content or raw user IDs.
  3. Privacy mode is the default. No per-user views.
  4. Public discord.js APIs only.
  5. Changes to collected fields, metrics, options or the HTTP API update these docs in the same pull request.
Terminal window
pnpm --filter @shardlens/docs dev

Code 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 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):

Terminal window
echo "SHARDLENS_DEMO=true" >> .env # next to docker-compose.yml
docker compose up -d
docker compose exec collector node dist/cli/seed.js

The 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.