tokamak

library0.6.1jsnpmunverified

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.

devops

npm install tokamak

github ↗package ↗

INSTALL

IMPORT

SIG · TOKAMAK

tokamak

devopsjavascriptv0.6.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import tokamak from 'tokamak'

✗ const tokamak = require('tokamak')

ESM-only import; package does not provide a CJS entry.

bundle

✓ import { bundle } from 'tokamak'

✗ const { bundle } = require('tokamak')

Named export for the main bundling function; not available via CJS require.

type BundleOptions

✓ import type { BundleOptions } from 'tokamak'

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

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

createRuntime

✓ import { createRuntime } from 'tokamak/runtime'

✗ import { createRuntime } from 'tokamak'

Separate runtime subpath export for browser-side module loading.

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);

Debug

Known issues

breakingESM circular dependencies are not supported and will cause runtime errors.

fix

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

affects: >=0.0.1

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

affects: >=0.0.1

breakingOnly Node.js >=14.17.0 is supported; earlier versions will fail.

fix

Upgrade Node.js to >=14.17.0.

affects: >=0.0.1

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

fix

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

affects: >=0.0.12

Errors

Common errors & fixes

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

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: [BABEL] unknown: You gave us a visitor for the node type "ExportDefaultDeclaration" but it's not a valid type

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.

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

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.

SyntaxError: Unexpected token 'export'

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.

Upgrade

Version history

0.6.1latest on npm

Audit

Dependencies

conclurerequiredRequired as a peer dependency for tokenization and parsing.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/dmaevsky/tokamak ↗

packagehttps://www.npmjs.com/package/tokamak ↗