iMod Bundler

1.5.0 · active · verified Tue Apr 21

iMod is a command-line interface (CLI) and programmatic JavaScript API-based bundler specifically designed for creating small, efficient modules. It is powered by Rollup, abstracting much of its complexity to provide a streamlined experience. Currently at version 1.5.0, iMod offers integrated TypeScript type declaration generation and simplifies the setup for common module formats including ES Modules (ESM), CommonJS (CJS), and UMD. While a specific release cadence isn't detailed, it generally follows semantic versioning. Its key differentiators include an opinionated yet configurable build pipeline, a focus on ease of use for 'tiny modules,' and support for multiple configuration methods via `package.json` or dedicated configuration files like `imod.config.js`.

Common errors

```
Error: Could not resolve entry module (./src/index.{ts,tsx,js,jsx,es6,es,mjs})
```
cause iMod could not find an entry file that matches its default search patterns (`src/index.*`) in the project's 'src/' directory.

fix Ensure an entry file (e.g., `src/index.ts`) exists at the default location, or specify a custom input file in your iMod configuration (e.g., add `input: 'path/to/my-entry.js'` to `imod.config.js`).
```
Cannot find module 'imod' or its corresponding type declarations.
```
cause The 'imod' package is not installed in the project, or the TypeScript compiler cannot locate its type definitions.

fix Install the package by running `npm install imod` or `yarn add imod`. If using TypeScript, ensure `allowSyntheticDefaultImports` is enabled in your `tsconfig.json` if you are using `import Imod from 'imod'`.
```
ReferenceError: require is not defined
```
cause This error typically occurs when an ES Module (ESM) bundle generated by iMod attempts to execute CommonJS `require()` syntax in an environment that expects pure ESM.

fix Review your source code to eliminate CommonJS-specific `require()` calls and `module.exports` when targeting ESM output. If you must use CommonJS modules, ensure iMod is configured to transpile them correctly (e.g., via a Rollup CJS plugin if exposed by iMod) or generate a CommonJS output format for that specific bundle.

Warnings

gotcha When initializing a new project, running `imod init` without the `--lite` flag will automatically attempt to install `node_modules`. This can be unexpected and time-consuming for users who prefer manual dependency management.
Fix: Use `imod init ./my-project --lite=true` to skip the automatic installation of `node_modules` during project creation.
gotcha iMod resolves its configuration files in a specific order: `./imod.config.js` > `./imod.config.json` > `imodconfig.js` > `imodconfig.json` > `${package.json}.config.imod`. Be aware that configurations found earlier in this sequence will override those found later.
Fix: To avoid unexpected configuration overrides, consolidate your iMod configuration into a single, high-priority file (e.g., `./imod.config.js`) or explicitly manage your configuration across files.
gotcha By default, iMod's `compilerOptions` for the CommonJS (CJS) format targets `es5`, which may not be optimal for modern Node.js environments that support newer ECMAScript features.
Fix: Modify your iMod configuration (e.g., in `imod.config.js`) to set `target: 'esnext'` or a specific modern ES version within the `compilerOptions` array for the CJS format, if you are targeting modern Node.js environments.

Install

npm install imod npm
yarn add imod yarn
pnpm add imod pnpm

Imports

Imod
wrong:
```
const Imod = require('imod')
```
correct:
```
import Imod from 'imod'
```
Primary way to import the main class for programmatic usage in ESM contexts. While a CommonJS require might work in older Node.js, the project is TypeScript-first.
Imod
wrong:
```
import Imod from 'imod'
```
correct:
```
const Imod = require('imod')
```
Correct CommonJS import for use in Node.js environments that do not support ES modules natively, or in scripts that explicitly use require. Using `import` here would result in a syntax error.
ImodConfig
```
import type { ImodConfig } from 'imod'
```
Import for TypeScript type definitions, useful when defining custom iMod configurations in a `.ts` file.

Quickstart

Demonstrates programmatic initialization of iMod and execution of a build operation, logging success or failure.

import Imod from 'imod';
import path from 'path';

// Initialize iMod with the current working directory as the project root.
// Adjust 'cwd' if your project root is different from where this script runs.
const iModInstance = new Imod({
  cwd: path.resolve(__dirname, '..', '..') // Assumes script is in 'scripts/build.ts' and project root is two levels up
});

console.log('Starting iMod build process...');

iModInstance.build()
  .then(() => {
    console.log('iMod build completed successfully!');
    console.log('Check the ' + (iModInstance.config.outDir || './dist') + ' directory for compiled output.');
  })
  .catch((error: any) => {
    console.error('iMod build failed:', error);
    process.exit(1);
  });

// To run in development/watch mode:
// iModInstance.dev().then(() => {
//   console.log('iMod is now watching for changes...');
// });

view raw JSON →