Meow CLI Helper

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/meow/index.js from ... not supported.

  cause Attempting to import `meow` using CommonJS `require()` syntax in an ES Module context, or in a CommonJS project that doesn't correctly handle ESM imports.
  fix Refactor your application to use ES Modules (`import meow from 'meow';`) and ensure your `package.json` has `"type": "module"`. If using TypeScript, set `"module": "node16"` or `"nodenext"` and `"moduleResolution": "node16"` or `"nodenext"` in `tsconfig.json`.

• Error: The `importMeta` option is required.

  cause The `importMeta: import.meta` option was omitted from the `meow` constructor call.
  fix Add `{ importMeta: import.meta }` to the `meow` constructor. This property is crucial for `meow` to correctly resolve paths to your `package.json` for displaying help and version information.

• Error [ERR_OS_NOT_SUPPORTED]: Your current Node.js version is X.Y.Z, but meow requires >=20. The latest Node.js LTS version is recommended.

  cause The installed Node.js version does not meet the minimum requirement specified by `meow`.
  fix Upgrade your Node.js environment to version 20 or higher. You can use tools like `nvm install 20` or `volta install node@20`.

• TypeError: 'alias' is not a valid flag option. Did you mean 'shortFlag'?

  cause An older `meow` configuration or code attempting to use the `alias` property within flag definitions after `meow` v12, where it was renamed.
  fix Replace the `alias` property with `shortFlag` in your flag definitions (e.g., `shortFlag: 'r'` instead of `alias: 'r'`). If you need multiple aliases, use the new `aliases` option.

• Error: Input required.

  cause The `input.isRequired` option is set to `true` in the `meow` configuration, but no non-flag arguments were provided when running the CLI.
  fix Ensure that the necessary input arguments are always provided to the CLI. If the input is not strictly mandatory in all scenarios, consider setting `input.isRequired: false` or making it a function that dynamically determines requirement.

Warnings

• breaking Meow v14 and later require Node.js 20 or newer. Earlier versions of Node.js are no longer supported.
  Fix: Upgrade your Node.js environment to version 20 or higher. Consider using a Node.js version manager (e.g., `nvm` or `volta`) to manage different project requirements.
• breaking Meow is an ECMAScript Module (ESM) only package since v12. Attempting to use `require()` will result in a runtime error (`ERR_REQUIRE_ESM`).
  Fix: Migrate your project to use ESM syntax (`import`/`export`) and ensure your `package.json` includes `"type": "module"`. For TypeScript, configure `"module": "node16"` or `"nodenext"` in `tsconfig.json`.
• breaking The `alias` flag option was renamed to `shortFlag` in v12 to provide more precise terminology. A separate `aliases` option is now available for actual multi-character aliases.
  Fix: Update flag definitions from `alias: 'x'` to `shortFlag: 'x'` in your `meow` configuration. If you intended to have multiple aliases, use the new `aliases` option.
• breaking The `importMeta` option is now a required configuration property for the `meow` constructor (since v12). It is used to correctly locate the `package.json` for version and help information.
  Fix: Always pass `{ importMeta: import.meta }` to the `meow` constructor when initializing your CLI application.
• gotcha The `hardRejection` option was removed in v13.1.0 because its functionality became the default behavior for unhandled promise rejections in Node.js 16 and later.
  Fix: Remove the `hardRejection` option from your `meow` configuration. No functional changes are expected if your Node.js version is 16 or newer.

Install

• npm install meow npm
• yarn add meow yarn
• pnpm add meow pnpm

Imports

• meow
  wrong:

  const meow = require('meow');

  correct:

  import meow from 'meow';

  `meow` is an ESM-only package since v12. Using `require()` will result in an `ERR_REQUIRE_ESM` error. Your project must be configured for ESM.
• AnyFlag

  import type { AnyFlag } from 'meow';

  Imports the TypeScript type for a single flag definition. Often used with generics for stricter type checking.
• AnyFlags

  import type { AnyFlags } from 'meow';

  Imports the TypeScript type for the entire flags object. Useful for type-checking the `cli.flags` return value.

Quickstart

This example demonstrates basic CLI setup with `meow`, parsing a main input argument and a boolean flag, and printing a message. It includes the mandatory `import.meta` option.

#!/usr/bin/env node
import meow from 'meow';

const cli = meow(`
	Usage
	  $ foo <input>

	Options
	  --rainbow, -r  Include a rainbow

	Examples
	  $ foo unicorns --rainbow
	  🌈 unicorns 🌈
`, {
	importMeta: import.meta, // This is required for meow to find package.json
	flags: {
		rainbow: {
			type: 'boolean',
			shortFlag: 'r'
		}
	}
});

// Example usage with parsed input and flags
const inputArgument = cli.input.at(0);
const enableRainbow = cli.flags.rainbow;

if (inputArgument) {
  const message = enableRainbow ? `🌈 ${inputArgument} 🌈` : inputArgument;
  console.log(message);
} else {
  console.log('No input provided. Try: foo unicorns --rainbow');
  cli.showHelp();
}