Read-Eval-Print-Loop (REPL)

A REPL is an interactive environment that takes single user inputs, executes them, and returns the result to the user. The REPL feature lets you inspect your dependency graph and call methods on your providers (and controllers) directly from your terminal.

Usage#

To run your NestJS application in REPL mode, create a new repl.ts file (alongside the existing main.ts file) and add the following code:

import { repl } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  await repl(AppModule);
}
await bootstrap();

import { repl } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  await repl(AppModule);
}
await bootstrap();

Then start the REPL from your terminal with the following command:

$ npm run start -- --entryFile repl

Hint The repl() function returns a promise that resolves to a Node.js REPL server object. You can pass Node.js REPL options as its second argument.

Once it's running, you should see the following messages in your console:

LOG [NestFactory] Starting Nest application...
LOG [InstanceLoader] AppModule dependencies initialized
LOG REPL initialized

You can now interact with your dependency graph. For instance, you can retrieve the AppService instance (this example uses the starter project) and call its getHello() method:

> get(AppService).getHello()
'Hello World!'

You can execute any JavaScript code from your terminal. For example, you can assign the AppController instance to a local variable and use await to call an asynchronous method:

> appController = get(AppController)
AppController { appService: AppService {} }
> await appController.getHello()
'Hello World!'

To display all public methods available on a given provider or controller, use the methods() function, as follows:

> methods(AppController)

Methods:
 ◻ getHello

To print all registered modules as a list, together with their controllers and providers, use debug():

> debug()

AppModule:
 - controllers:
  ◻ AppController
 - providers:
  ◻ AppService

Here's a quick demo:

The following section describes the built-in native functions in more detail.

Native functions#

The built-in NestJS REPL comes with a few native functions that are globally available when you start the REPL. Call help() to list them.

If you don't remember the signature (i.e., the expected parameters and return type) of a function, use <function_name>.help. For instance:

> $.help
Retrieves an instance of either injectable or controller, otherwise, throws exception.
Interface: $(token: InjectionToken) => any

Hint These function interfaces are written in TypeScript function type expression syntax.

Watch mode#

During development, it's useful to run the REPL in watch mode so that code changes are reflected automatically:

$ npm run start -- --watch --entryFile repl

The downside is that the REPL's command history is discarded after each reload. To preserve it, modify your bootstrap() function as follows:

async function bootstrap() {
  const replServer = await repl(AppModule);
  replServer.setupHistory(".nestjs_repl_history", (err) => {
    if (err) {
      console.error(err);
    }
  });
}

The history is now preserved between runs and reloads.