jitsu icon indicating copy to clipboard operation
jitsu copied to clipboard

Migrate build system to esbuild and add environment validation

Open vklimontovich opened this issue 4 weeks ago • 0 comments

This PR modernizes the build tooling for client libraries and adds runtime environment variable validation to the console webapp. The changes improve build performance, reduce bundle sizes, and provide type-safe environment configuration with clear error messages.

The existing build setup had several issues affecting development experience and reliability:

  1. Rollup configuration was complex and required significant maintenance across multiple packages
  2. No runtime validation of environment variables meant configuration errors only appeared as cryptic runtime failures
  3. TypeScript configurations mixed test and build concerns, complicating the setup
  4. Deprecated React example app was still present despite not being actively maintained

Build System Migration

Replaced rollup with esbuild bundler across all client libraries (jitsu-js, jitsu-react, functions). esbuild provides significantly faster builds with minimal configuration. Created bundle.mts files that handle multiple output formats: ESM, CJS, and browser IIFE bundles with proper tree-shaking and sourcemaps.

Updated TypeScript configurations to use modern settings with proper module resolution and removed test-specific tsconfig files. Cleaned up package.json files to align with new build approach.

Environment Validation

Introduced Zod-based validation for console webapp environment variables with two separate schemas:

  • serverEnv.ts - comprehensive schema for all server-side config (database, ClickHouse, Redis, auth providers, etc.) with detailed comments explaining each variable
  • clientEnv.ts - minimal schema for browser-safe NEXT_PUBLIC_* variables

Both schemas provide startup validation with clear error messages indicating exactly which variables are missing or misconfigured. The client schema explicitly accesses each env var to ensure Next.js can properly inline them at build time (passing process.env object directly won't work in browser).

Cleanup

Removed deprecated react-app example that was no longer maintained and removed test-specific TypeScript configs that are no longer needed with improved build setup.

Breaking Changes

Environment variables are now validated at startup. If your deployment has missing or misconfigured variables, the application will fail to start with a clear error message instead of failing silently at runtime.

vklimontovich avatar Dec 01 '25 02:12 vklimontovich