Registry / web-framework / nestjs-console

nestjs-console

library10.0.0jsnpmunverified

nestjs-console is a NestJS module that provides a command-line interface (CLI) for NestJS applications. It enables developers to define and run console commands within the application's dependency injection context, which is particularly useful for tasks such as headless operations, cron jobs, data processing, and migrations. The module integrates with the popular `commander.js` package for robust command parsing and execution. It bootstraps a `NestApplicationContext` (headless) rather than a full `NestApplication`, ensuring that CLI commands have access to all necessary NestJS services without initiating an HTTP server. The current stable version is 10.0.0, which supports NestJS v11, Commander v12 & v13, and requires Node.js >= v20.0.0. Its release cadence is closely tied to major NestJS and Commander updates. A key differentiator is its seamless integration with NestJS's decorators and DI system, allowing command logic to reside directly within NestJS providers.

web-framework devops workflow

npm install nestjs-console

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NESTJS-CONSOLE

nestjs-console

web-frameworkjavascriptv10.0.0

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.

ConsoleModule

✓ import { ConsoleModule } from 'nestjs-console';

✗ const { ConsoleModule } = require('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

✓ import { Console } from 'nestjs-console';

✗ import { Console as NestConsole } 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

✓ import { Command } from 'nestjs-console';

✗ import { CommandDecorator } from 'nestjs-console';

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

ConsoleService

✓ import { ConsoleService } from 'nestjs-console';

✗ import ConsoleService from 'nestjs-console';

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

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

Debug

Known issues

breakingThe `@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" })`.

affects: >=5.0.1

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

affects: >=5.0.1

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

affects: >=10.0.0

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.

affects: >=6.0.0

gotchaNestJS 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).

affects: >=3.0.0

Errors

Common errors & fixes

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.

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'

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

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

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.

Upgrade

Version history

10.0.0latest on npm

Audit

Dependencies

@nestjs/commonrequiredPeer dependency required for core NestJS functionalities and decorators.

@nestjs/corerequiredPeer dependency for bootstrapping the NestJS application context.

commanderrequiredRuntime dependency for parsing and executing CLI commands.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Pop-Code/nestjs-console ↗

packagehttps://www.npmjs.com/package/nestjs-console ↗

homepagehttps://nestjs-console.com ↗