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

# @obinexusltd/obix-config-webpack

> Webpack 5 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 Webpack 5+.

---

## 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-webpack": "workspace:*"
  }
}
```

---

## Package Structure

```
packages/config/webpack/
├── webpack.config.js           ← Base shared config (env-switched via NODE_ENV)
├── development/
│   └── webpack.config.js       ← Dev config (fast rebuilds, eval sourcemaps, HMR-ready)
├── production/
│   └── webpack.config.js       ← Prod config (terser, UMD output, banner, tree-shaking)
├── plugins/
│   ├── obix-define.js          ← OBIX DefinePlugin constants factory
│   └── index.js                ← Barrel re-export
└── src/
    └── index.ts                ← TypeScript programmatic API (compiled to dist/)
```

---

## Programmatic API

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

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

// Development — fast rebuilds, eval source maps
const devCfg = createDevConfig(pkg);

// Production — UMD output, terser, source maps
const prodCfg = createProdConfig(pkg);

// Resolve by environment string
const cfg = resolveConfig('production', pkg);

// Add DefinePlugin using built-in helper
const withDefines = {
  ...prodCfg,
  plugins: [new webpack.DefinePlugin(buildDefines(pkg, 'production'))],
};

export default cfg;
```

### Factory Functions

| Function | Description |
|----------|-------------|
| `createBaseConfig(pkg, opts?)` | Mode `'none'`, no minification (starting point for custom configs) |
| `createDevConfig(pkg, opts?)` | Mode `development`, eval sourcemaps, `transpileOnly`, HMR-ready |
| `createProdConfig(pkg, opts?)` | Mode `production`, terser, UMD library output, full type-checking |
| `resolveConfig(env, pkg, opts?)` | Delegates to dev or prod based on `env` |
| `buildDefines(pkg, env)` | Returns a `DefinePlugin`-compatible constants object |

### `ObixWebpackOptions`

```ts
interface ObixWebpackOptions {
  entry?: string;        // default: './src/index.ts'
  outDir?: string;       // default: 'dist'
  filename?: string;     // default: 'index.js'
  tsconfig?: string;     // default: './tsconfig.json'
  target?: WebpackTarget; // default: 'web'
  sourcemap?: boolean;   // default: true
  minimize?: boolean;    // default: false (auto true in production)
  libraryName?: string;  // default: 'OBIX' (UMD global name)
}
```

### Static Config Descriptors

Three static objects are exported for obix-cli introspection:

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

---

## Using Config Files Directly

### Base config (mode-switched via `NODE_ENV`)

```bash
# Development mode
NODE_ENV=development webpack --config ./node_modules/@obinexusltd/obix-config-webpack/webpack.config.js

# Production mode
NODE_ENV=production webpack --config ./node_modules/@obinexusltd/obix-config-webpack/webpack.config.js
```

You can also pass mode explicitly via the webpack CLI:

```bash
webpack --config ./node_modules/@obinexusltd/obix-config-webpack/webpack.config.js --mode production
```

### Development config

Fast incremental builds using `ts-loader` with `transpileOnly: true`. Run `tsc --noEmit` separately for type validation.

```bash
webpack --config ./node_modules/@obinexusltd/obix-config-webpack/development/webpack.config.js
```

### Production config

Full type-checking, terser minification, UMD library bundle with banner comment.

```bash
webpack --config ./node_modules/@obinexusltd/obix-config-webpack/production/webpack.config.js
```

---

## Plugin Utilities

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

Creates a `webpack.DefinePlugin`-compatible constants map 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 webpack from 'webpack';
import { createObixDefine } from '@obinexusltd/obix-config-webpack/plugins';

plugins: [
  new webpack.DefinePlugin(createObixDefine(pkg.version, 'production')),
]
```

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

Same as `createObixDefine` but merges additional custom constants:

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

---

## Build Targets

| Target | Use case |
|--------|----------|
| `web` (default) | Browser bundles, CDN delivery |
| `node` | Node.js CLI tools, server-side packages |
| `webworker` | Service Workers, Web Workers |
| `electron-main` | Electron main process |
| `electron-renderer` | Electron renderer process |

---

## Externals Behaviour

| Target | Externalised |
|--------|-------------|
| `web` | `peerDependencies` only |
| `node` | `dependencies` + `peerDependencies` (as `commonjs <name>`) |

---

## Peer Dependencies

This package declares webpack and ts-loader as `peerDependencies`. Install them in the consuming package:

```json
{
  "devDependencies": {
    "ts-loader": "^9.0.0",
    "webpack": "^5.0.0",
    "webpack-cli": "^5.0.0",
    "terser-webpack-plugin": "^5.0.0"
  }
}
```

Optional extras:

```json
{
  "devDependencies": {
    "webpack-bundle-analyzer": "^4.0.0",
    "html-webpack-plugin": "^5.0.0",
    "mini-css-extract-plugin": "^2.0.0",
    "copy-webpack-plugin": "^12.0.0"
  }
}
```

---

## Comparison with obix-config-rollup

| Feature | `obix-config-rollup` | `obix-config-webpack` |
|---------|---------------------|----------------------|
| Primary use | Library bundling (ESM/CJS/UMD) | Application bundling + library output |
| Tree-shaking | Native (rollup) | `optimization.usedExports` |
| Code splitting | `preserveModules` | `SplitChunksPlugin` |
| Dev server | External (e.g. vite) | `webpack-dev-server` compatible |
| TypeScript | `@rollup/plugin-typescript` | `ts-loader` |
| Best for | SDK packages | Browser apps, complex projects |

---

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