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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bundle
✓ import { bundle } from 'rocket-bundler'
✗ const rocket = require('rocket-bundler')
ESM named export only; CommonJS require will fail.
Server
✓ import { Server } from 'rocket-bundler'
✗ import Server from 'rocket-bundler'
Server class is a named export, not default.
loadConfig
✓ import { loadConfig } from 'rocket-bundler'
✗ const { loadConfig } = require('rocket-bundler')
ESM only; the package does not provide a CommonJS entry point.
Shows how to load configuration and bundle a React Native app using the rocket-bundler API.
import { bundle } from 'rocket-bundler';
import { loadConfig } from 'rocket-bundler';
const config = await loadConfig({
projectRoot: './',
transformer: {
babelTransformerPath: require.resolve('metro-react-native-babel-transformer'),
},
serializer: {
// custom serializer options
},
});
const result = await bundle({
config,
entryFile: 'index.js',
platform: 'android',
dev: false,
bundleOutput: './output.js',
sourceMapOutput: './output.map',
});
console.log('Bundle size:', result.stats.files['bundle'].size);
rocket-bundler --version
Debug
Known issues
breakingrocket-bundler v0.14.0 removed the CommonJS entry point. Require('rocket-bundler') will throw 'ERR_REQUIRE_ESM'.fixSwitch to import syntax and ensure your Node.js version supports ESM (>=14.8.0).
affects: >=0.14.0
deprecatedThe CLI interface (src/cli.js) is deprecated since v0.13.0 and will be removed in v1.0. Use the programmatic API instead.fixMigrate to using the { bundle } and { Server } imports directly. affects: >=0.13.0
gotchaThe base-file and base-output options (for incremental builds) are not stable across cache clears. Don't rely on them for production caching.fixSet cacheVersion or manually clear caches instead.
affects: <0.15.0
gotchaRocket Bundler uses a custom resolution algorithm similar to Metro. Node module resolution (require.resolve) may fail in some edge cases with symlinks.fixUse 'require.resolve' with absolute paths or configure resolver.nodeModulesPaths.
affects: all
breakingPlatform-specific extensions (e.g., .ios.js, .android.js) are resolved with lower priority than in Metro. This is intentional but may break some existing projects.fixExplicitly set resolver.resolveRequest to a function that reorders platform-specific extensions.
affects: >=0.12.0 <0.14.0
Errors
Common errors & fixes
Error: Cannot find module 'rocket-bundler'
Package not installed or used in a Node.js version that doesn't support ESM.
fixnpm install rocket-bundler@latest. Ensure Node.js >=14.8.0 and that the project's package.json has 'type': 'module' or use .mjs files.
TypeError: (0 , rocket_bundler.bundle) is not a function
Attempting to import named exports as default or using CommonJS require.
fixUse import { bundle } from 'rocket-bundler'. Do not use const rocket = require('rocket-bundler') as it returns undefined. Error: Bundle output path not specified
Missing bundleOutput option in the bundle() call.
fixAdd bundleOutput: './path/to/output.js' to the options object.
Error: getPlatformExtension is not a function
Custom resolveRequest function not returning a proper extension.
fixImplement resolveRequest according to the documentation: it must call getPlatformExtension on the request.
Audit
Dependencies
metrorequiredCore bundling engine (forked upstream dependencies)
metro-configrequiredConfiguration handling for Metro bundler
metro-source-maprequiredSource map generation