@obinexusltd/obix-config-babel

Babel 7 configuration for OBIX SDK packages — part of the @obinexusltd/obix-monorepo.

Provides typed factory functions, ready-to-use config files, environment-specific presets, and the OBIX-specific plugin preset (obix-plugins.js) for transforming OBIX SDK source code with Babel 7+.

Installation

Registered automatically as an npm workspace package:

# From monorepo root
npm install

To add it as a dependency in a consumer package:

{
  "devDependencies": {
    "@obinexusltd/obix-config-babel": "workspace:*"
  }
}

Package Structure

packages/config/babel/
├── babel.config.js          ← Base config (env-switched: development/production/test)
├── obix-plugins.js          ← OBIX-specific Babel preset (component syntax, state optimisation)
├── development/
│   └── babel.config.js      ← Dev config (ESM, sourcemaps, verbose)
├── production/
│   └── babel.config.js      ← Prod config (ESM, compact, no comments)
├── presets/
│   └── index.js             ← Named preset exports (obixPreset, obixTestPreset, etc.)
└── src/
    └── index.ts             ← TypeScript programmatic API (compiled to dist/)

Programmatic API

import {
  createBaseConfig,
  createDevConfig,
  createProdConfig,
  createTestConfig,
  resolveConfig,
} from '@obinexusltd/obix-config-babel';

// Development — ESM, sourcemaps, verbose
export default createDevConfig();

// Production — ESM, compact, runtime helpers
export default createProdConfig({ runtime: true });

// Test — CommonJS for Jest
export default createTestConfig();

// Resolve by environment string
export default resolveConfig('production', { react: true });

Factory Functions

| Function | Description | |----------|-------------| | createBaseConfig(opts?) | Base config, ESM modules, TypeScript | | createDevConfig(opts?) | Dev: sourcemaps, verbose, no compact | | createProdConfig(opts?) | Prod: sourcemaps, compact, comments stripped | | createTestConfig(opts?) | Test: CommonJS modules, inline sourcemaps | | resolveConfig(env, opts?) | Delegates by 'development'|'production'|'test' |

ObixBabelOptions

interface ObixBabelOptions {
  targets?:        BabelTargets;  // default: '> 0.5%, last 2 versions, not dead, node >= 18'
  modules?:        false | 'commonjs' | 'auto' | ...;  // default: false (ESM)
  react?:          boolean;       // default: false
  typescript?:     boolean;       // default: true
  decorators?:     boolean;       // default: false
  runtime?:        boolean;       // default: false
  obixPlugins?:    boolean;       // default: false
  obixValidation?: boolean;       // default: false
}

Static Descriptors

import { baseConfig, developmentConfig, productionConfig, testConfig } from '@obinexusltd/obix-config-babel';

Using Config Files Directly

Base config (env-switched)

Reference from your project's babel.config.js:

// babel.config.js — extend the OBIX base config
export { default } from '@obinexusltd/obix-config-babel/base';

Or reference inline:

{
  "babel": {
    "extends": "@obinexusltd/obix-config-babel/base"
  }
}

Development only

BABEL_ENV=development babel src --out-dir dist \
  --config-file ./node_modules/@obinexusltd/obix-config-babel/development/babel.config.js

Production only

BABEL_ENV=production babel src --out-dir dist \
  --config-file ./node_modules/@obinexusltd/obix-config-babel/production/babel.config.js

OBIX Plugin Preset

obix-plugins.js is a Babel preset that wires the OBIX-specific transform plugins. The plugins are optional — the preset degrades gracefully if they are not installed.

| Plugin | Purpose | Required? | |--------|---------|-----------| | babel-plugin-obix-component-syntax | OBIX component definition transforms | No | | babel-plugin-obix-state-optimization | DFA/NFA state machine code optimisation | No | | babel-plugin-obix-validation | Schema validation injection | No (env-gated) |

Enable the validation plugin

# Via environment variable
OBIX_ENABLE_VALIDATION=1 babel src --out-dir dist

Or via preset options:

export default {
  presets: [
    ['@obinexusltd/obix-config-babel/plugins', { validation: true }],
  ],
};

Wire the OBIX preset manually

// babel.config.js
import obixPlugins from '@obinexusltd/obix-config-babel/plugins';

export default {
  presets: [
    '@babel/preset-env',
    '@babel/preset-typescript',
    obixPlugins,
  ],
};

Preset Utilities

Import named presets from @obinexusltd/obix-config-babel/presets:

import {
  obixPreset,           // @babel/preset-env with OBIX defaults
  obixTypeScriptPreset, // @babel/preset-typescript with OBIX defaults
  obixReactPreset,      // @babel/preset-react (automatic runtime)
  obixTestPreset,       // @babel/preset-env with CommonJS modules (for Jest)
  obixLibraryPresets,   // [obixPreset, obixTypeScriptPreset]
  obixTestPresets,      // [obixTestPreset, obixTypeScriptPreset]
} from '@obinexusltd/obix-config-babel/presets';

export default { presets: obixLibraryPresets };

Environment Reference

| Environment | modules | sourcemaps | compact | Use case | |-------------|-----------|------------|---------|----------| | development | false (ESM) | true | false | Bundler dev build | | production | false (ESM) | true | true | Bundler prod build | | test | 'commonjs' | 'inline' | false | Jest test runs |

Peer Dependencies

Required:

{
  "devDependencies": {
    "@babel/core": "^7.0.0",
    "@babel/preset-env": "^7.0.0",
    "@babel/preset-typescript": "^7.0.0"
  }
}

Optional:

{
  "devDependencies": {
    "@babel/preset-react": "^7.0.0",
    "@babel/plugin-transform-runtime": "^7.0.0",
    "@babel/plugin-proposal-decorators": "^7.0.0",
    "@babel/runtime": "^7.0.0",
    "core-js": "^3.0.0"
  }
}

Comparison with obix-config-rollup / obix-config-webpack

| Feature | Babel | Rollup | Webpack | |---------|-------|--------|---------| | Primary role | Syntax transforms | Library bundling | App bundling | | TypeScript | @babel/preset-typescript | @rollup/plugin-typescript | ts-loader | | Type checking | None (transform only) | Full tsc | Full tsc | | Tree-shaking | Preserves ESM for bundlers | Native | usedExports | | Best for | Polyfills, JSX, decorators | SDK packages | Browser apps |

Use Babel alongside Rollup or Webpack — not instead of them.

Author

Nnamdi Michael Okpala — OBINexus <[email protected]>

Part of the OBIX Heart/Soul UI/UX SDK monorepo.