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.
heroku
✓ import heroku from 'heroku'
Default import works for ESM. CLI is primarily used via command line, not programmatic imports.
Heroku
✓ import { Heroku } from 'heroku'
✗ const Heroku = require('heroku')
ESM-only since v11; require() will throw ERR_REQUIRE_ESM.
Command
✓ import { Command } from 'heroku'
Class for building CLI plugins. Requires oclif v4 compatibility.
Shows how to create a custom CLI command plugin using the Heroku CLI v11 ESM API.
// Install globally: npm install -g heroku
// Or use without install: npx heroku
import { Command } from 'heroku';
class MyCommand extends Command {
static description = 'my custom command';
static flags = {};
async run() {
const {args, flags} = await this.parse(MyCommand);
this.log('Hello from custom command!');
}
}
export default MyCommand;
// Run: heroku my-command
heroku --version
Debug
Known issues
breakingv11 converts entire codebase to ESM. require() no longer works. Use import or dynamic import().fixReplace require('heroku') with import heroku from 'heroku'. If dynamic import needed, use import('heroku'). affects: >=11.0.0
breakingv11 removes monorepo structure. All packages consolidated into single npm package 'heroku'. No sub-packages like @heroku-cli/plugin-* are separate.fixInstall only 'heroku' package. Remove separate @heroku-cli/* dependencies.
affects: >=11.0.0
breakingv11 upgrades to oclif v4. Plugin API changes: command lifecycle, hooks, and config are different.fixUpdate plugins to use oclif v4 API. See oclif migration guide.
affects: >=11.0.0
breakingv11 replaces chalk with ansis for color output. Custom color themes may break.fixReplace chalk imports with ansis. See ansis documentation for API changes.
affects: >=11.0.0
breakingv11 drops Node.js <20 support. Minimum engine is 'node': '>=20'.fixUpgrade Node.js to version 20+.
affects: >=11.0.0
deprecatedredis:maintenance and pg:maintenance commands are deprecated in v10.17.0.fixUse alternative commands: heroku data:maintenance for Postgres, or remove usage.
affects: >=10.17.0 <11.0.0
gotchaGlobal install may conflict with npx usage. Use npx heroku for per-version usage.fixUse npx heroku to avoid version conflicts, or install globally with npm install -g heroku.
affects: >=11.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /path/to/heroku/node_modules/heroku/lib/index.js
Using require() on an ESM-only module in v11.
fixChange to import heroku from 'heroku'; or use dynamic import.
Cannot find module '@heroku-cli/plugin-*'
v11 removed monorepo. All plugins are now in the main 'heroku' package.
fixUninstall @heroku-cli/plugin-* and use 'heroku' directly.
The engine "node" is incompatible with this module. Expected version ">=20". Got "18.x"
Node.js version too old for v11.
fixUpgrade Node.js to version 20+.
Error: Command not found. Perhaps you need to install the plugin?
Trying to run a plugin command that is not available because oclif v4 changed plugin loading.
fixUpdate plugin to oclif v4 compatible version or re-install.
Audit
Dependencies
heroku-cli-utiloptionallegacy utilities, partially replaced in v11