NestJS Console Module

Common errors

• Error: Nest can't resolve dependencies of the [YourConsoleClass] (?). Please make sure that the argument [dependency] at index [index] is available in the [YourModule] context.

  cause A dependency required by your `@Console` decorated class (or one of its injected services) is not properly provided within the module where `AppConsole` is listed as a provider, or within its imported modules.
  fix Ensure all services, modules, or providers that `YourConsoleClass` depends on are correctly imported into `AppModule` (or any module that provides `YourConsoleClass`). Verify `providers` and `imports` arrays in your `@Module` decorator.

• unknown command 'myCommand'

  cause The command you are trying to execute is not recognized by `nestjs-console`. This typically means the `AppConsole` class or its methods are not correctly decorated or registered.
  fix Check that your console class has the `@Console` decorator, your command methods have the `@Command` decorator, and that your console class is listed in the `providers` array of your `AppModule` or an imported module.

• ReferenceError: require is not defined in ES module scope

  cause You are attempting to use a CommonJS `require()` call in an ES module context. This often happens in Node.js >= 14 projects configured for ESM, or when mixing CJS and ESM modules incorrectly.
  fix Refactor your imports to use ES module `import` syntax. If you need to import a CommonJS module in an ESM context, Node.js typically handles it, but for ESM-only modules in a CommonJS context, you might need dynamic `import()`.

• TypeError: (0 , nestjs_console_1.Console) is not a function

  cause This error usually indicates an incorrect import statement for the `Console` decorator or that the module was loaded incorrectly (e.g., using `require` for a module primarily designed for ES imports and decorators).
  fix Ensure you are using `import { Console } from 'nestjs-console';` and that your `tsconfig.json` correctly processes decorators and modules. Verify your Node.js version meets the package requirements.

Warnings

• breaking The `@Console` decorator's `name` property was renamed to `command`. Update your command definitions to use `command` instead of `name`.
  Fix: Change `@Console({ name: "myCommand" })` to `@Console({ command: "myCommand" })`.
• breaking The signature of command handler methods changed in v5.0.1. Options are now passed directly as the second argument to the handler method, rather than being accessed implicitly.
  Fix: Adjust command handler methods to accept an `options` object as their second parameter. Refer to the updated documentation or examples for the new signature.
• breaking Version 10.0.0 of `nestjs-console` requires Node.js version 20.0.0 or higher. Previous versions required Node.js v16+ for NestJS v10. Ensure your Node.js environment meets this minimum requirement.
  Fix: Upgrade your Node.js installation to version 20.0.0 or later. Use a tool like `nvm` for managing multiple Node.js versions if needed.
• breaking `nestjs-console`'s major versions are coupled with NestJS and `commander` major versions. For example, v10 supports NestJS v11 and Commander v12/13, while v9 supported NestJS v10 and Commander v11. Mismatching versions can lead to peer dependency conflicts and runtime errors.
  Fix: Always install `nestjs-console` version that explicitly supports your installed NestJS and `commander` versions. Check the `nestjs-console` changelog or `package.json` peer dependencies for compatibility. Use `npm install` or `yarn add` to automatically resolve compatible versions where possible.
• gotcha NestJS typically compiles to CommonJS modules, even when using ESM syntax. While Node.js v20+ has better ESM support, dynamic `import()` might be needed for ESM-only packages in some NestJS setups. Directly `require()`ing ESM-only modules in a CJS context will cause errors.
  Fix: Ensure your `tsconfig.json` `module` and `moduleResolution` settings (e.g., `NodeNext` or `Node16`) are appropriate for your project's module system. If using ESM-only dependencies, consider dynamic `import()` or configuring your NestJS project to build as ESM (though not officially supported by NestJS core).

Install

• npm install nestjs-console npm
• yarn add nestjs-console yarn
• pnpm add nestjs-console pnpm

Imports

• ConsoleModule
  wrong:

  const { ConsoleModule } = require('nestjs-console');

  correct:

  import { ConsoleModule } from 'nestjs-console';

  Used to register the console module in your NestJS application's root or feature module. All NestJS packages generally compile to CommonJS, but the source uses ESM syntax. Node.js v20+ is required by v10+ of this package, which leans towards ESM.
• Console
  wrong:

  import { Console as NestConsole } from 'nestjs-console';

  correct:

  import { Console } from 'nestjs-console';

  Decorator used to mark a class as a console command group. Its `name` property was renamed to `command` in v5.0.1.
• Command
  wrong:

  import { CommandDecorator } from 'nestjs-console';

  correct:

  import { Command } from 'nestjs-console';

  Decorator used to mark a method within a `@Console` class as a specific CLI command.
• ConsoleService
  wrong:

  import ConsoleService from 'nestjs-console';

  correct:

  import { ConsoleService } from 'nestjs-console';

  Injectable service for programmatic interaction with the console commands. It's a named export, not a default one.

Quickstart

Demonstrates setting up a basic NestJS console application, defining a command class using `@Console`, and command methods using `@Command` and `@Option` decorators. It shows how to pass arguments and options, including type parsing, and how to bootstrap the application context for CLI execution.

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { ConsoleModule, Console, Command, Option, createCommanderAction } from 'nestjs-console';

interface MyCommandOptions {
  name: string;
  count: number;
}

@Console({
  command: 'app',
  description: 'Application commands'
})
export class AppConsole {
  @Command({
    command: 'hello <message>',
    description: 'Says hello with a message',
    options: [
      { flags: '-n, --name <name>', description: 'Your name', required: true },
      { flags: '-c, --count <count>', description: 'Number of times to say hello', defaultValue: 1, parser: (val) => parseInt(val, 10) }
    ]
  })
  async hello(message: string, options: MyCommandOptions) {
    for (let i = 0; i < options.count; i++) {
      console.log(`Hello ${options.name || 'Stranger'}! You said: "${message}"`);
    }
    console.log(`
Environment: ${process.env.NODE_ENV || 'development'}`);
  }

  @Command({
    command: 'greet [recipient]',
    description: 'Greets a recipient or the world'
  })
  async greet(recipient?: string) {
    console.log(`Greetings, ${recipient || 'world'}!`);
  }
}

@Module({
  imports: [ConsoleModule.forRoot({
    handleExceptions: true,
    commander: createCommanderAction()
  })],
  providers: [AppConsole]
})
export class AppModule {}

async function bootstrap() {
  try {
    const app = await NestFactory.createApplicationContext(AppModule, {
      logger: ['error', 'warn'], // Only log errors and warnings for console app
    });
    await app.select(ConsoleModule).get(ConsoleService).init();
    await app.close();
  } catch (e) {
    console.error('Console application failed to bootstrap:', e);
    process.exit(1);
  }
}

// To run: 
// 1. Compile: `npm run build` or `tsc`
// 2. Execute: `node dist/console.js app hello "How are you?" --name Alice -c 3`
//    or `node dist/console.js app greet Bob`
//    or `node dist/console.js --help`
//    Make sure 'console.ts' is set as the entry point in your tsconfig/build process.
bootstrap();