Beamform Inbox

Development

Prerequisites:

• Install just - brew install just (macOS), cargo install just (Linux/Windows)
• Uses pnpm for package management (inside Docker container)

Quick Start:

just up    # Start dev server
just open  # Open http://localhost:6006

Commands:

Uses Docker and justfile. Run just to see all commands.

| Task | Command | | ------------------- | ----------------------- | | Development | | | Start server | just up | | View logs | just logs | | Open Storybook | just open | | Stop server | just down | | Start Storybook | just storybook | | Testing | | | Lint | just lint | | Format | just format | | Unit tests | just test | | Test watch | just test-watch | | Building | | | Build components | just build-components | | Build widget | just build-widget | | Build both | just build-all | | Build Storybook | just build-storybook | | Analysis | | | Analyze components | just analyze | | Analyze widget | just analyze-widget | | Environment | | | Reset environment | just reset | | Update dependencies | just build |

Note: Do not run git or gh commands in the container.

Node.js Support

This package supports Node.js versions following our 2 LTS + Future LTS policy:

• ✅ Two most recent LTS versions: Currently Node.js 20.x (Active LTS) and 22.x (Active LTS)
• ✅ Current even releases that will become LTS: Currently 24.x (will become LTS in 2025)
• ❌ Odd releases: Not supported (19.x, 21.x, 23.x) as they are short-lived and never become LTS
• ❌ EOL or older LTS versions: Not supported after we add newer LTS support

Current support matrix: Node.js 20.x, 22.x, 24.x

We test against all supported versions in CI to ensure compatibility. The engines field in package.json reflects the minimum supported version.

Lifecycle

The project supports two distribution channels with different development workflows:

NPM Package (React Components) - Hot Reload ✅

• Files: src/core/components/, src/core/primitives/, src/core/services/, src/stories/
• Workflow: Make changes → Storybook updates automatically
• No manual build required

CDN Distribution (Drop-in Widget) - Manual Build ❌

• Files: src/packaging/widget.ts, src/widget/, CDN-related components
• Workflow: Make changes → just build-widget → Refresh Storybook
• Manual build required because CDN widget is built as IIFE bundle

When Manual Build is Required

# After changes to CDN widget files:
just build-widget
# Then refresh Storybook "Widget/CDN Drop-in Widget" story

File Change Impact

| File/Directory | NPM Hot Reload | CDN Manual Build | | ------------------------- | -------------- | ---------------- | | src/core/components/ | ✅ | ❌ Required | | src/packaging/widget.ts | N/A | ❌ Required | | src/widget/ | N/A | ❌ Required | | src/stories/ | ✅ | N/A |

Why CDN requires manual build: The drop-in widget is built as a self-contained IIFE bundle with React/SWR included, served as static files in Storybook. Hot reload can't watch/rebuild this automatically.