Tokamak

0.0.15 verified Sat Apr 25 auth: no javascript

Tokamak is an isomorphic self-bundling bundler (version 0.0.15) aimed at Node.js and browser environments. It converts all modules to CommonJS (CJS) format, deliberately deviating from the ESM trend. Key differentiators include support for CJS-only npm modules and easier automatic HMR isolation. Drawbacks include lack of ESM circular dependency support and export-by-value semantics (e.g., `export let` modifications are not propagated). The bundler runs a static analysis to build a require graph, then generates a dynamic require function for the browser. Actively maintained with irregular releases.

Common errors

error TypeError: Cannot read properties of undefined (reading 'resolve') ↓

cause Missing external module resolution when `external` option includes a module not installed.

fix

Install the missing module as a dependency or remove it from the external array.

error Error: [BABEL] unknown: You gave us a visitor for the node type "ExportDefaultDeclaration" but it's not a valid type ↓

cause Using an incompatible babel plugin or preset (e.g., @babel/preset-env) that conflicts with Tokamak's internal parser.

fix

Ensure all babel transforms are disabled or use Tokamak's default transform pipeline by not providing custom babel config.

error Module not found: Error: Can't resolve 'lodash' in '/path/to/project' ↓

cause Missing external dependency that is not marked in `external` but is not bundled (e.g., due to incorrect resolution).

fix

Either install the dependency or add it to the external array and ensure it's available at runtime.

error SyntaxError: Unexpected token 'export' ↓

cause Input file uses ESM syntax (e.g., export) but the bundler is configured to output CJS without proper transpilation.

fix

Set target to a suitable ECMAScript version (e.g., 'es2015') or ensure the input files are already in CJS format.

Warnings

breaking ESM circular dependencies are not supported and will cause runtime errors. ↓

fix Refactor circular dependencies to use CJS-compatible patterns or avoid cycles.

gotcha Exports are by value: `export let foo = 'bar'` cannot be mutated by other modules. ↓

fix Use object-style exports (e.g., export const obj = { foo: 'bar' }) if mutation is needed.

breaking Only Node.js >=14.17.0 is supported; earlier versions will fail. ↓

fix Upgrade Node.js to >=14.17.0.

deprecated The `preserveModules` option has been deprecated in favor of `outDir` since version 0.0.12. ↓

fix Replace `preserveModules: true` with `outDir: './dist'`.

Install

npm install tokamak

yarn add tokamak

pnpm add tokamak

Imports

default
wrong
```
const tokamak = require('tokamak')
```
correct
```
import tokamak from 'tokamak'
```
ESM-only import; package does not provide a CJS entry.
bundle
wrong
```
const { bundle } = require('tokamak')
```
correct
```
import { bundle } from 'tokamak'
```
Named export for the main bundling function; not available via CJS require.

type BundleOptions

wrong

import { BundleOptions } from 'tokamak' // runtime error

correct

import type { BundleOptions } from 'tokamak'

TypeScript-only type export; do not import at runtime.

createRuntime

wrong

import { createRuntime } from 'tokamak'

correct

import { createRuntime } from 'tokamak/runtime'

Separate runtime subpath export for browser-side module loading.

Quickstart

Shows the bundle function being called with common options like entry, outDir, minify, and sourceMap.

import { bundle } from 'tokamak';

const result = await bundle({
  entry: './src/index.js',
  format: 'cjs',
  outDir: './dist',
  minify: true,
  sourceMap: true,
  target: 'es2015',
  external: ['lodash'],
});

console.log('Output files:', result.files);
console.log('Metadata:', result.meta);