Nollup: Rollup-compatible Dev Bundler

Common errors

• Something imported is undefined.

  cause Nollup disables ESM live-bindings by default for performance reasons, which can lead to `undefined` values for mutable exports.
  fix Enable live-bindings in your Nollup configuration: `output: { ..., liveBindings: true }`.

• Error: Cannot find module '<module-id>' (usually with a numeric ID)

  cause This error typically occurs when a CommonJS module is used without the `@rollup/plugin-commonjs` being correctly configured or if the plugin fails to transform an unusually structured CommonJS module.
  fix Ensure `@rollup/plugin-node-resolve` and `@rollup/plugin-commonjs` are installed and correctly configured in your Nollup plugins array. Verify that the CommonJS plugin is applied before other plugins that might process the code.

• Sourcemaps are incorrect or not generated for TypeScript files.

  cause A bug in Nollup versions prior to 0.18.7 prevented proper sourcemap generation and display for plugins like `@rollup/plugin-typescript`.
  fix Update Nollup to version 0.18.7 or later to resolve sourcemap issues. Also, ensure your TypeScript plugin is up-to-date and correctly configured.

• Dynamic imports break when emitting assets or cause runtime errors.

  cause A specific bug in Nollup versions prior to 0.18.4 caused dynamic imports to malfunction when combined with asset emission, leading to broken imports or runtime failures.
  fix Upgrade Nollup to version 0.18.4 or later to fix issues related to dynamic imports and asset emission.

Warnings

• gotcha Nollup is strictly for development and does not perform production-level optimizations like Rollup (e.g., tree-shaking, scope-hoisting). Bundles generated by Nollup are not suitable for production deployment due to their larger size and lack of optimizations.
  Fix: Use Rollup itself for production builds, maintaining separate configurations for Nollup (dev) and Rollup (prod).
• gotcha ESM live-bindings are disabled by default for performance. If your application relies on mutable exports (e.g., `export let count = 0;` and then `count++` in another module), you might encounter `undefined` values or unexpected behavior.
  Fix: Enable live-bindings explicitly in your Nollup configuration by setting `liveBindings: true` in your output options or Nollup-specific configuration. Refer to the 'Live Bindings' documentation.
• gotcha Nollup only implements Rollup configuration options that are relevant for development. Options primarily focused on production optimizations or niche scenarios may be ignored without warning, leading to discrepancies with your production Rollup build.
  Fix: Consult Nollup's 'Supported Rollup Config Options' documentation to ensure your development configuration aligns with Nollup's capabilities. Always test your production build with actual Rollup.
• gotcha Older versions of Nollup (pre-0.18.5) had issues with Hot Module Replacement (`module.hot.accept()`) when used without a callback function, preventing HMR from functioning correctly in those scenarios.
  Fix: Upgrade Nollup to version 0.18.5 or newer to resolve this HMR compatibility issue. Ensure your HMR setup aligns with `module.hot` conventions.
• gotcha The behavior for IIFE external imports changed in version 0.20.1, specifically how global variables are searched when a default import is assigned to a variable. This might affect applications relying on specific global variable remapping in IIFE bundles.
  Fix: Review your IIFE external import configurations and global variable mappings if upgrading from older versions. Test your application thoroughly if relying on IIFE format and external dependencies.
• gotcha TypeScript sourcemaps generated by plugins were not correctly displayed in some setups due to a bug in Nollup.
  Fix: Upgrade Nollup to version 0.18.7 or newer to ensure correct sourcemap generation and display when using TypeScript plugins.

Install

• npm install nollup npm
• yarn add nollup yarn
• pnpm add nollup pnpm

Imports

• createServer
  wrong:

  const { createServer } = require('nollup');

  correct:

  import { createServer } from 'nollup';

  Preferred for starting a development server programmatically. ESM import is recommended for modern Node.js projects.
• createCompiler
  wrong:

  const { createCompiler } = require('nollup');

  correct:

  import { createCompiler } from 'nollup';

  Used for programmatic compilation without the dev server, typically when integrating with custom server setups. Follows Rollup's `rollup()` API pattern.
• nollupCLI
  wrong:

  import { runCLI } from 'nollup';

  correct:

  npx nollup

  While internal CLI logic exists, direct programmatic import of the CLI runner is not a primary or recommended public API. Use `npx nollup` for CLI execution.

Quickstart

Demonstrates how to programmatically set up and start a Nollup development server using its `createServer` API, along with a minimal Rollup configuration and sample client-side files for a web application. It includes HMR and content serving from a public directory.

import { createServer } from 'nollup';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Minimal rollup config (e.g., rollup.config.js)
const rollupConfig = {
  input: path.resolve(__dirname, 'src/main.js'),
  output: {
    file: 'dist/bundle.js',
    format: 'esm',
    sourcemap: true,
  },
  plugins: [], // Add your Rollup plugins here, e.g., @rollup/plugin-node-resolve(), @rollup/plugin-commonjs()
};

// Create a basic server.js file to start Nollup
async function startDevServer() {
  const server = await createServer({
    config: rollupConfig,
    port: process.env.PORT ?? 9000,
    contentBase: path.resolve(__dirname, 'public'),
    hot: true, // Enable Hot Module Replacement
  });

  server.listen();
  console.log(`Nollup dev server listening on http://localhost:${server.port}`);
}

startDevServer().catch(console.error);

// --- src/main.js ---
// console.log('Hello from Nollup!');
// document.body.innerHTML = '<h1>Hello Nollup Dev!</h1>';

// --- public/index.html ---
// <!DOCTYPE html>
// <html lang="en">
// <head>
//     <meta charset="UTF-8">
//     <meta name="viewport" content="width=device-width, initial-scale=1.0">
//     <title>Nollup App</title>
// </head>
// <body>
//     <script src="/dist/bundle.js"></script>
// </body>
// </html>

// To run:
// 1. Create files: server.js, src/main.js, public/index.html as above.
// 2. Add "type": "module" to your package.json.
// 3. Install: npm install nollup
// 4. Run: node server.js