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

# @obinexusltd/obix-config-rollup

> Rollup bundler configuration for OBIX SDK packages — part of the `@obinexusltd/obix-monorepo`.

Provides a typed programmatic API, ready-to-use config files, and OBIX-specific plugin utilities for building OBIX SDK packages with Rollup v4+.

---

## Installation

This package is consumed as an npm workspace package. It is registered automatically when you run `npm install` from the monorepo root:

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

To add it as a dependency in a consumer package inside the monorepo:

```json
{
  "devDependencies": {
    "@obinexusltd/obix-config-rollup": "workspace:*"
  }
}
```

---

## Package Structure

```
packages/config/rollup/
├── rollup.config.js          ← Base shared config (ESM, FORMAT env var switches output)
├── development/
│   └── rollup.config.js      ← Dev config (ESM only, sourcemaps, no minification)
├── production/
│   └── rollup.config.js      ← Prod config (ESM + CJS + UMD, terser, DTS bundle)
├── plugins/
│   ├── obix-replace.js       ← OBIX replace plugin factory
│   └── index.js              ← Barrel re-export
└── src/
    └── index.ts              ← TypeScript programmatic API (compiled to dist/)
```

---

## Programmatic API

Import factory functions from `@obinexusltd/obix-config-rollup` to build rollup configs in TypeScript or JavaScript:

```ts
import { createDevConfig, createProdConfig, resolveConfig } from '@obinexusltd/obix-config-rollup';
import pkg from './package.json' with { type: 'json' };

// Development — ESM only, sourcemaps
const devConfigs = createDevConfig(pkg);

// Production — ESM + CJS + UMD, minified
const prodConfigs = createProdConfig(pkg, { formats: ['esm', 'cjs', 'umd'] });

// Resolve by environment string
const configs = resolveConfig('production', pkg);
export default configs;
```

### Factory Functions

| Function | Description |
|----------|-------------|
| `createBaseConfig(pkg, opts?)` | ESM only, no minification (starting point for custom configs) |
| `createDevConfig(pkg, opts?)` | ESM only, sourcemaps, inline sources, no minification |
| `createProdConfig(pkg, opts?)` | ESM + CJS + UMD, sourcemaps, terser |
| `resolveConfig(env, pkg, opts?)` | Delegates to `createDevConfig` or `createProdConfig` based on `env` |

### `ObixRollupOptions`

```ts
interface ObixRollupOptions {
  input?: string;          // default: 'src/index.ts'
  outDir?: string;         // default: 'dist'
  formats?: RollupFormat[]; // default: ['esm']
  libraryName?: string;    // default: 'OBIX'  (UMD global name)
  tsconfig?: string;       // default: './tsconfig.json'
  sourcemap?: boolean;     // default: true
  minify?: boolean;        // default: false (auto true in prod)
}
```

### `PackageMeta`

```ts
interface PackageMeta {
  version: string;
  dependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
}
```

### Static Config Descriptors

Three static objects are exported for obix-cli introspection:

```ts
import { baseConfig, developmentConfig, productionConfig } from '@obinexusltd/obix-config-rollup';
```

---

## Using Config Files Directly

### Base config (format-switched via environment variable)

```bash
# ESM output
FORMAT=esm NODE_ENV=development rollup -c ./node_modules/@obinexusltd/obix-config-rollup/rollup.config.js

# CJS output
FORMAT=cjs NODE_ENV=production rollup -c ./node_modules/@obinexusltd/obix-config-rollup/rollup.config.js

# UMD output
FORMAT=umd NODE_ENV=production rollup -c ./node_modules/@obinexusltd/obix-config-rollup/rollup.config.js

# DTS declaration bundle
FORMAT=dts rollup -c ./node_modules/@obinexusltd/obix-config-rollup/rollup.config.js
```

### Development config

```bash
NODE_ENV=development rollup -c ./node_modules/@obinexusltd/obix-config-rollup/development/rollup.config.js
```

### Production config (all formats in one pass)

```bash
NODE_ENV=production rollup -c ./node_modules/@obinexusltd/obix-config-rollup/production/rollup.config.js
```

---

## Plugin Utilities

### `createObixReplace(version, env?)`

Creates a `@rollup/plugin-replace`-compatible options object with OBIX standard substitutions:

| Token | Replaced with |
|-------|--------------|
| `process.env.NODE_ENV` | `"development"` or `"production"` |
| `__OBIX_VERSION__` | Package version string |
| `__DEV__` | `true` in development, `false` in production |

```js
import replace from '@rollup/plugin-replace';
import { createObixReplace } from '@obinexusltd/obix-config-rollup/plugins';

plugins: [
  replace(createObixReplace(pkg.version, 'production')),
]
```

### `createObixReplaceWith(version, env?, extra?)`

Same as `createObixReplace` but merges additional custom substitutions:

```js
plugins: [
  replace(createObixReplaceWith(pkg.version, 'production', {
    '__API_URL__': JSON.stringify('https://api.obix.io'),
  })),
]
```

---

## Supported Output Formats

| Format | Output | Use case |
|--------|--------|----------|
| `esm` | `dist/esm/` | Modern bundlers, tree-shaking |
| `cjs` | `dist/cjs/` | Node.js, Jest, CommonJS consumers |
| `umd` | `dist/umd/index.js` | Browser `<script>` tags, CDNs |
| `iife` | `dist/iife/index.js` | Self-executing browser bundles |
| `dts` | `dist/index.d.ts` | Bundled TypeScript declarations |

---

## Peer Dependencies

This package does not install rollup or its plugins — they are declared as `peerDependencies` and must be installed by the consuming package:

```json
{
  "devDependencies": {
    "@rollup/plugin-commonjs": "^25.0.0",
    "@rollup/plugin-node-resolve": "^15.0.0",
    "@rollup/plugin-replace": "^5.0.0",
    "@rollup/plugin-terser": "^0.4.0",
    "@rollup/plugin-typescript": "^11.0.0",
    "rollup": "^4.0.0",
    "rollup-plugin-dts": "^6.0.0"
  }
}
```

---

## 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.