npm package: @obinexusltd/obix-config-babel
Description: OBIX Babel configuration for OBIX CLI and SDK packages
Author: Nnamdi Michael Okpala
Latest version: 0.1.0

# @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:

```bash
# From monorepo root
npm install
```

To add it as a dependency in a consumer package:

```json
{
  "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

```ts
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`

```ts
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

```ts
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`:

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

Or reference inline:

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

### Development only

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

### Production only

```bash
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

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

Or via preset options:

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

### Wire the OBIX preset manually

```js
// 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`:

```js
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:

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

Optional:

```json
{
  "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 &lt;okpalan@protonmail.com&gt;

Part of the [OBIX Heart/Soul UI/UX SDK](https://github.com/OBINexusComputing/obix-sdk) monorepo.