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

# From monorepo root
npm install

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

{
  "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:

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

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

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

Static Config Descriptors

Three static objects are exported for obix-cli introspection:

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

Using Config Files Directly

Base config (format-switched via environment variable)

# 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

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

Production config (all formats in one pass)

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 |

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:

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:

{
  "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 <[email protected]>

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