documentationteamexamples

Monorepo Example: Shipping a Suite of Map, Chat, and Dashboard Components for Logistics

UUnknown

2026-02-15

9 min read

Monorepo + CI/CD playbook to ship maps, chat, and dashboards with ClickHouse for logistics teams.

Ship a suite of Maps, Chat, and Dashboards — fast, safe, and repeatable

If your team is rebuilding map widgets, incident chat, and analytics every project, you lose weeks to integration and maintenance. This guide gives a monorepo template and production-ready CI/CD playbook for logistics teams building mapping, incident chat, and ClickHouse-backed dashboards. It includes runnable examples, testing strategies, and a publisher flow so you can sell or ship licensed packages with confidence in 2026's landscape.

Executive summary — what you'll get

Monorepo layout with framework-agnostic core, React/Vue wrappers, and demo apps.
CI/CD pipeline recipes (GitHub Actions examples) for build, test, publish, and deploy demos with caching and affected-only runs.
ClickHouse integration patterns: schema design, ingestion, low-latency queries, and Node.js example code.
Pack and publish flow for commercial packages: versioning, signing, SCA, and license metadata.
Runnables: Storybook demos, Playwright E2E, and Docker-based integration tests including ClickHouse.

Why this matters in 2026

Logistics platforms are evolving into data-first, interconnected systems. In late 2025 and early 2026 we saw two clear trends: warehouse automation is now coordinated with real-time data (source: industry playbooks for 2026), and OLAP systems like ClickHouse gained major investment and adoption — ClickHouse raised a large $400M round in January 2026, accelerating OLAP for fast analytics in production. Teams need component suites that plug into telemetry and analytics platforms without per-project rewrites.

Monorepo template: recommended layout

Use a workspace-based monorepo (pnpm + Turborepo or Nx) to get top developer UX, cross-package TypeScript, and affected-only builds. Below is a minimal, production-ready tree.

// repo root
  /package.json
  /pnpm-workspace.yaml
  /turbo.json
  /packages
    /core            # framework-agnostic components (Web Components)
    /map             # map-specific UI + adapters (Mapbox / Leaflet wrappers)
    /chat            # incident chat widget + events bridge
    /dashboard       # analytics widgets (charts, KPI tiles)
    /clickhouse-sdk  # Node client helpers, ingestion helpers
  /apps
    /demo-react
    /demo-vue
    /storybook       # Storybook with all packages
  /scripts
    /ci              # helper scripts for CI
  /.github/workflows
    ci.yml
    publish.yml

Why a framework-agnostic core?

Ship one implementation as Web Components (custom elements + CSS variables). Provide lightweight wrappers for React and Vue. This reduces maintenance overhead and avoids reimplementing business logic for each framework.

Package build targets

ESM module (packaged with Rollup or tsup)
UMD (for backwards compatibility)
Types (.d.ts)
CSS vars + tokens bundle
Web Component bundle (for vanilla usage)

Example: map component contract

Keep the public API minimal and deterministic. The map component exposes an event bus, a stable props surface, and a telemetry hook that emits to a central events pipeline.

export interface LogisticsMapOptions {
  center: [number, number]
  zoom?: number
  interactive?: boolean
  styleUrl?: string
}

// emits: { type: 'vehicle:update', payload: { id, lat, lng, speed } }

Framework wrapper (React) — usage

import { LogisticsMap } from '@myrepo/map-react'

function Fleet() {
  return (
    console.log(e)} />
  )
}

ClickHouse integration patterns

Use ClickHouse for high-cardinality, time-series analytics: telemetry, routing events, incident logs. Model with date partitioning and low-cardinality keys in dimensions. Keep event tables wide and use materialized views for pre-aggregations.

Example schema

CREATE TABLE telemetry.events (
    ts DateTime64(3),
    vehicle_id String,
    event_type String,
    lat Float64,
    lng Float64,
    speed Float32,
    payload JSON
  )
  ENGINE = MergeTree()
  PARTITION BY toYYYYMM(ts)
  ORDER BY (vehicle_id, ts)
  SETTINGS index_granularity = 8192;

-- materialized view for hourly aggregates
CREATE MATERIALIZED VIEW analytics.hourly
ENGINE = SummingMergeTree()
PARTITION BY toYYYYMM(hour)
ORDER BY (vehicle_id, hour)
AS
SELECT
  toStartOfHour(ts) as hour,
  vehicle_id,
  count() as events,
  avg(speed) as avg_speed
FROM telemetry.events
GROUP BY hour, vehicle_id;

Node.js ingestion snippet (HTTP)

import fetch from 'node-fetch'

async function sendEvent(event) {
  const body = `INSERT INTO telemetry.events FORMAT JSONEachRow\n${JSON.stringify(event)}`
  await fetch(process.env.CLICKHOUSE_HTTP || 'http://localhost:8123', {
    method: 'POST',
    body,
  })
}

For 2026, the ClickHouse Node client and HTTP interface are both mature; choose the HTTP route in serverless or ephemeral CI environments. Keep credentials in vaults (HashiCorp Vault, AWS Secrets Manager).

CI/CD best practices (GitHub Actions focused)

The CI pipeline has three roles: verify (lint/test/scan), build (affected builds + artifacts), and release (publish, demo deploy). Keep secrets minimal in CI and use short-lived tokens for registry publishing.

Core principles

Affected-only runs: use Turborepo / nx to run tests and builds only for changed packages.
Cache aggressively: pnpm store, node_modules, and build caches keyed by lockfile and tool versions.
CI database for integration tests: spin up ClickHouse in CI via Docker for integration tests.
Parallelize: matrix builds for runtime targets (node/browser) and frameworks.
Security gates: SCA, license check, dependency audit, and signed releases.

Sample GitHub Actions workflow (simplified)

name: CI
on: [push, pull_request]

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      cache-key: ${{ steps.cache.outputs.key }}
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Install pnpm
        run: npm i -g pnpm
      - name: Install
        run: pnpm install --frozen-lockfile
      - name: Cache turborepo
        id: cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/turbo
          key: ${{ runner.os }}-turbo-${{ hashFiles('**/pnpm-lock.yaml') }}

  test:
    needs: setup
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run affected tests
        run: pnpm turbo run test --filter=... --concurrency=4

  integration:
    needs: test
    runs-on: ubuntu-latest
    services:
      clickhouse:
        image: yandex/clickhouse-server:latest
        ports:
          - 8123:8123
    steps:
      - uses: actions/checkout@v4
      - name: Wait for ClickHouse
        run: |
          for i in {1..30}; do
            curl -sS http://localhost:8123/ || sleep 1
          done
      - name: Run integration tests
        env:
          CLICKHOUSE_HTTP: http://localhost:8123
        run: pnpm turbo run test:integration --filter=clickhouse-sdk

Publish flow

Use conventional commits + semantic-release to determine versions and changelogs.
Publish to a private npm registry or scoped public registry depending on license.
Sign release artifacts and attach SB (storybook) static site to releases for demos.
Run post-publish smoke tests against the demo apps.

Testing and demos

Tests must cover component contract, integration with ClickHouse, and E2E flows for incident reporting and response.

Unit tests

Jest for isolated logic and snapshot testing for markup.
Vitest for Vite-based builds.

Integration tests

Spin up ClickHouse in CI and run the ingestion pipeline with a curated dataset. Use Docker with an initialization script that inserts sample telemetry and incidents.

End-to-end

Use Playwright for cross-browser E2E on demo apps. Use Storybook with Chromatic for visual regression. Automate screenshots and performance timings in CI for each component release.

Performance, scaling, and ClickHouse best practices

Partition by month with compact ORDER BY keys for efficient pruning.
Use materialized views to pre-aggregate heavy queries for dashboards.
TTL policies for raw telemetry to keep storage predictable.
Batch ingestion over HTTP where possible to reduce churn.
Indexing: prefer primary key ordering and skip indexes; avoid over-indexing.

Security, licensing, and trust

Teams purchasing components need clarity on maintenance, licenses, and risk. Include the following in every package and release:

SPDX license field in package.json
Signed release artifacts
SCA scan (Snyk/OSS Index) with policy exemptions recorded
Endpoint auth patterns for ClickHouse: use RBAC and network-level access control
Webhook signing for incident chat to validate event sources

Packaging commercial components

If you plan to sell components or offer a subscription, codify the business flows in CI/CD:

Automated license bundling and docs generation during publish.
Generate a demo token with limited capability and attach to Storybook demo as an interactive trial mode.
Ship compiled assets for CDNs and consumer-ready wrappers for major frameworks.

Sample ClickHouse query for a logistics dashboard

-- top 10 slowest routes in last 24h
SELECT
  route_id,
  count() as trips,
  avg(duration_seconds) as avg_duration
FROM telemetry.trips
WHERE ts >= now() - INTERVAL 24 hour
GROUP BY route_id
ORDER BY avg_duration DESC
LIMIT 10

Observability & benchmark strategy

Benchmarks and observability validate component SLAs. Track render latency, event publish latency to ClickHouse, and E2E failure rate. Store metrics in a metrics system (Prometheus/ClickHouse) and visualize via Grafana.

Benchmark example

import { measure } from '@myrepo/bench'

const results = await measure(async () => {
  await mountMapWith1000Vehicles()
})
console.log(results.mean)

Practical rollout plan (90-day roadmap)

Week 1–2: Seed monorepo, implement Web Component core, and set up turborrepo + pnpm. Add CI skeleton.
Week 3–4: Implement Map + Chat packages and basic demo apps. Add Storybook and unit tests.
Week 5–6: Add ClickHouse SDK, define schemas, and integration tests with ClickHouse Docker in CI.
Week 7–8: Implement wrappers (React/Vue), performance tests, and automation for releases using semantic-release.
Week 9–12: Harden CI with SCA, license checks, visual regression, and staged demo deployments. Publish first stable commercial packages.

Common pitfalls and how to avoid them

Rewriting for each framework: Avoid by keeping the core in Web Components and writing thin wrappers.
Expensive CI runs: Use affected-only runs and caching; run full suite nightly or on release branches.
Under-modeled analytics: Define your ClickHouse schema early and iterate with materialized views, not by brute-forcing ad-hoc queries.
Unclear licensing: Add a license header, SPDX tag, and a clear commercial license text in each package.

"In logistics, integration speed and data reliability are the competitive edges. A properly structured monorepo with a repeatable CI/CD playbook turns component work from a cost center into a product." — Senior Architect, Logistics Solutions

Actionable checklist before first release

All packages compile to ESM + types and pass unit tests.
Storybook publishes to preview site and includes demo tokens for buyers.
CI runs integration tests against ClickHouse and records artifacts.
Security scans and license checks return green or documented exceptions.
semantic-release configured to publish to the target registry with signed artifacts.

Final takeaways

Shipping a suite of map, chat, and dashboard components for logistics requires architecture decisions that favor reusability, observability, and repeatable CI/CD. Use a monorepo with a framework-agnostic core, automate ClickHouse-backed integration tests in CI, and adopt a release process that protects customers and you — SCA, license clarity, and signed artifacts. Following this template gets you from prototype to commercial-grade components with predictable velocity.

Call to action

Ready-to-run repo template, CI pipelines, and ClickHouse integration examples are available to clone and adapt. If you want the exact Turborepo config, GitHub Actions workflows, and Storybook demos used in our internal deploys, download the template from our repo or contact the team for a commercial starter kit and support contract.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.