Development Guide

Everything for developers working on Hereby: the architecture and getting-started Guide, the workspace Packages below, and the technical Reference (database schema, API routers, calculator pipeline). All packages live in the packages/ directory and are managed as pnpm workspace packages.

Package Dependency Graph

Overview

Package	npm Name	Status	Description
database	@hereby/database	Production	113 TypeORM entities, 105 migrations, 27 seeds
api	@hereby/api	Production	Fastify 5 + tRPC 11 with 57 routers, WS, and uploads
core	@hereby/core	Production	Shared types, 55 Zod schemas, 30 enum files, Pino logger
sdk	@hereby/sdk	Production	53 type-safe services with Alpine plugin and WebSocket support
cli	@hereby/cli	Production	Commander.js CLI tool
components	@hereby/components	Production	Alpine.js components (AuthGate, LoginForm, RegisterForm, ChangePasswordForm, NotificationBell)
design-system	hereby-service-web	Production	React + Storybook web app with TailwindCSS 4.1
test	@hereby/test	Production	Vitest integration + scenario tests

Build Order

Packages must be built in dependency order:

1. @hereby/core        # No dependencies
2. @hereby/database    # Depends on core
3. @hereby/api         # Depends on database, core
4. @hereby/sdk         # Depends on core, peers api types
5. @hereby/components  # Depends on sdk
6. @hereby/cli         # Depends on sdk

pnpm build handles this automatically via workspace dependency resolution and turbo.

Sub-Path Exports (@hereby/core)

Browser-safe modules built with tsup (ESM + CJS):

• @hereby/core/date — date utilities (zero deps)
• @hereby/core/constants — permission constants, insurance rates
• @hereby/core/errors — error classes

Heavy modules build with tsc (CJS only):

• @hereby/core root — everything including Zod schemas and Pino