Your first NestJS 12 project with the CLI

nest new tiffintrail writes 15 files in a few seconds, and every one of them has a job: one starts the server, one wires the classes together, two answer the first request, two test it, and the other nine are the README, package.json and the settings of the CLI, TypeScript, the test runner, the linter and the formatter. Knowing which file does what is the difference between changing the starter with confidence and guessing.

This lesson creates the starter of TiffinTrail, the tiffin service this track builds, with the Nest CLI 12.0.8. You will check the two Node.js versions Nest 12 asks for, choose between the ESM and CommonJS layouts, read every generated file, build, test, lint and run the result, and preview new code with nest generate.

Check Node.js twice: once to run, once to generate

Nest 12 asks for two different minimum versions of Node.js. Running an app needs one; the CLI’s code generators need a newer one. Each package states its own floor in the engines field of its package.json, so the first command of the session below prints what this machine runs and what three installed packages ask for:

// Prints the Node.js that runs this program and the Node.js versions three installed Nest packages ask for.
import { readFileSync } from 'node:fs';

console.log(`This Node.js: ${process.version}`);
for (const name of ['@nestjs/core', '@nestjs/cli', '@nestjs/schematics']) {
  const pkg = JSON.parse(readFileSync(`../starter/node_modules/${name}/package.json`, 'utf8'));
  console.log(`${`${name} ${pkg.version}`.padEnd(28)} engines.node: ${pkg.engines?.node ?? '(none)'}`);
}

Its output is the first part of the next session, under node engines.mjs. @nestjs/core says only >= 20, but the migration guide is stricter: Nest 12’s packages are ES modules, and a CommonJS app can load them only through require(esm), which Node.js has unflagged since 20.19 and 22.12. The generators in @nestjs/schematics 12.0.6 ask for ^22.22.3 || ^24.15.0 || >=26.0.0, a floor they inherit from the Angular devkit they are built on.

nest new writes fifteen files

This session prints the versions, then runs the CLI’s new command the way you would, with four flags explained below, and finally compares the new project with the starter folder of this lesson:

import { session } from '../session.mjs';

// The CLI of the starter's own dependencies creates a new project here, without installing packages (the session
// has no network), and diff compares it with the starter folder of this lesson: no output means the same files.
session(
  `
node engines.mjs
nest --version
nest new tiffintrail --skip-install --skip-git --package-manager npm --no-observe
diff -r -x README.md -x package-lock.json -x node_modules -x first-request.mjs tiffintrail ../starter
`,
  { packages: '../starter' },
);

$ node engines.mjs
This Node.js: v24.21.0
@nestjs/core 12.1.2          engines.node: >= 20
@nestjs/cli 12.0.8           engines.node: >= 20.11
@nestjs/schematics 12.0.6    engines.node: ^22.22.3 || ^24.15.0 || >=26.0.0
$ nest --version
12.0.8
$ nest new tiffintrail --skip-install --skip-git --package-manager npm --no-observe
✨  We will scaffold your app in a few seconds..

CREATE tiffintrail/.oxlintrc.json (206 bytes)
CREATE tiffintrail/.prettierrc (52 bytes)
CREATE tiffintrail/README.md (6981 bytes)
CREATE tiffintrail/nest-cli.json (171 bytes)
CREATE tiffintrail/package.json (1430 bytes)
CREATE tiffintrail/tsconfig.build.json (170 bytes)
CREATE tiffintrail/tsconfig.json (601 bytes)
CREATE tiffintrail/vitest.config.e2e.ts (245 bytes)
CREATE tiffintrail/vitest.config.ts (350 bytes)
CREATE tiffintrail/src/app.controller.ts (277 bytes)
CREATE tiffintrail/src/app.module.ts (255 bytes)
CREATE tiffintrail/src/app.service.ts (142 bytes)
CREATE tiffintrail/src/main.ts (237 bytes)
CREATE tiffintrail/src/app.controller.spec.ts (623 bytes)
CREATE tiffintrail/test/app.e2e-spec.ts (731 bytes)


                          Thanks for installing Nest 🙏
                 Please consider donating to our open collective
                        to help us maintain this package.


                   🍷  Donate: https://opencollective.com/nest
$ diff -r -x README.md -x package-lock.json -x node_modules -x first-request.mjs tiffintrail ../starter

The flags: --skip-install because this recorded session has no network (on your machine, leave it out and let the CLI install the packages), --skip-git to skip git init, --package-manager npm to skip the question about npm, Yarn, pnpm or Bun, and --no-observe to skip the question about the Nest team’s hosted monitoring SDK, which this track does not use. In a terminal, nest new also asks which module system to use; without a terminal it takes the default, ESM.

diff printed nothing, so the starter folder below is exactly what the CLI wrote, apart from the README, the lock file this lesson adds to pin every package version, and first-request.mjs, the one file of the lesson. Here is what each generated file is for:

main.ts starts one module, and the module wires the rest

Four files make the app. Read them in the order Nest uses them:

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

import { Module } from '@nestjs/common';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service.js';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

main.ts hands AppModule to NestFactory.create(). The module’s @Module() decorator lists one controller and one provider. The controller’s constructor asks for an AppService, and the service is marked @Injectable(), so Nest can create it and pass it in. Step through what happens when main.ts runs, and the first request after it:

Two details of the ESM layout show in these files. Relative imports end in .js, as in './app.module.js', even though the source file is app.module.ts, because the import names the file the compiler will write. And main.ts ends with await bootstrap(); at the top level of the file, which only an ES moduleES module: A JavaScript file that uses import and export, the module format of the language standard. In Node.js a .js file is one when the nearest package.json says "type": "module". may do.

Build, test, lint and run the starter

The starter’s package.json defines the scripts you will use every day. This session runs five of them in the starter folder, then starts the built app once with first-request.mjs and sends it one request:

import { session } from '../session.mjs';

// The starter's own scripts, then one request to the built app. --reporter=verbose makes Vitest list every test.
session(
  `
cd ../starter
npm run build
ls dist
npm test -- --reporter=verbose
npm run test:e2e -- --reporter=verbose
npm run lint
node first-request.mjs
`,
  { packages: '../starter' },
);

$ cd ../starter
$ npm run build

> tiffintrail@0.0.1 build
> nest build
$ ls dist
app.controller.d.ts
app.controller.js
app.controller.js.map
app.module.d.ts
app.module.js
app.module.js.map
app.service.d.ts
app.service.js
app.service.js.map
main.d.ts
main.js
main.js.map
$ npm test -- --reporter=verbose

> tiffintrail@0.0.1 test
> vitest run --reporter=verbose

The plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. You can remove the plugin and set resolve.tsconfigPaths: true in your Vite config instead.

 RUN  v4.1.11 .

 ✓ src/app.controller.spec.ts > AppController > root > should return "Hello World!"

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  <time>
   Duration  <time>
$ npm run test:e2e -- --reporter=verbose

> tiffintrail@0.0.1 test:e2e
> vitest run --config ./vitest.config.e2e.ts --reporter=verbose

The plugin "vite-tsconfig-paths" is detected. Vite now supports tsconfig paths resolution natively via the resolve.tsconfigPaths option. You can remove the plugin and set resolve.tsconfigPaths: true in your Vite config instead.

 RUN  v4.1.11 .

 ✓ test/app.e2e-spec.ts > AppController (e2e) > / (GET)

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  <time>
   Duration  <time>
$ npm run lint

> tiffintrail@0.0.1 lint
> oxlint --type-aware src/ test/

Found 0 warnings and 0 errors.
Finished in <time> on 6 files with 111 rules using <n> threads.
$ node first-request.mjs
[Nest] <pid>  - <time>     LOG [NestFactory] Starting Nest application...
[Nest] <pid>  - <time>     LOG [InstanceLoader] AppModule dependencies initialized +<n>ms
[Nest] <pid>  - <time>     LOG [RoutesResolver] AppController {/}: +<n>ms
[Nest] <pid>  - <time>     LOG [RouterExplorer] Mapped {/, GET} route +<n>ms
[Nest] <pid>  - <time>     LOG [NestApplication] Nest application successfully started +<n>ms
GET / -> 200 Hello World!
  content-type: text/html; charset=utf-8
  x-powered-by: Express
  etag: W/"c-Lve95gjOVATpfV8EL5X4nxwjKHE"

// Starts the built starter on a port the system picks, sends GET / as a browser would, prints the answer and stops.
// Run it after npm run build: it imports the compiled module from dist/.
import { NestFactory } from '@nestjs/core';
import { AppModule } from './dist/app.module.js';

const app = await NestFactory.create(AppModule);
await app.listen(0, '127.0.0.1');

const res = await fetch(`${await app.getUrl()}/`);
console.log(`GET / -> ${res.status} ${await res.text()}`);
for (const name of ['content-type', 'x-powered-by', 'etag']) console.log(`  ${name}: ${res.headers.get(name)}`);

await app.close();

What each command did:

A few lines of that output are worth reading closely. The boot log is the figure above in words: AppModule dependencies initialized, then Mapped {/, GET} route. The answer arrived as text/html, because Express sends a string as HTML, with X-Powered-By: Express and an ETag. And Vite, which Vitest runs on, notes that the vite-tsconfig-paths plugin of the generated config is no longer needed; it is a notice, and the tests still pass.

The two scripts that keep running are not in the session: npm run start builds and starts the app on port 3000, and npm run start:dev also watches src/ and restarts on every change.

ESM or CommonJS: what the question changes

When nest new asks for a module system, it chooses between two templates that @nestjs/schematics ships: one for ES modules with Vitest, which is the default, and one for CommonJSCommonJS: Node.js's older module format, with require() and module.exports. A .js file is CommonJS unless the nearest package.json says "type": "module". with Jest. This program reads both templates from the installed package and prints how they differ:

// Compares the two project templates that nest new chooses between when it asks for a module system:
// ts-esm (ES modules, Vitest) and ts (CommonJS, Jest), as @nestjs/schematics ships them.
import { readFileSync } from 'node:fs';

const root = '../starter/node_modules/@nestjs/schematics/dist/lib/application/files';
const read = (template, file) => readFileSync(`${root}/${template}/${file}`, 'utf8');
// The templates hold EJS tags; fill them in as nest new does for a TypeScript project without the monitoring SDK.
const render = (text) => text.replace(/<% if \(observe\) \{ %>[\s\S]*?<% \} %>/g, '').replace(/<%= strict %>/g, 'true').replace(/<%=[^%]*%>/g, '');
const json = (template, file) => JSON.parse(render(read(template, file)));

const pkg = { esm: json('ts-esm', 'package.json'), cjs: json('ts', 'package.json') };
const tsconfig = { esm: json('ts-esm', 'tsconfig.json'), cjs: json('ts', 'tsconfig.json') };
const main = { esm: render(read('ts-esm', 'src/main.ts')), cjs: render(read('ts', 'src/main.ts')) };

console.log(`package.json "type":  ESM ${pkg.esm.type ?? '(not set)'}  |  CommonJS ${pkg.cjs.type ?? '(not set)'}`);
console.log('test script:');
console.log(`  ESM       ${pkg.esm.scripts.test}`);
console.log(`  CommonJS  ${pkg.cjs.scripts.test}`);
const only = (a, b) => Object.keys(pkg[a].devDependencies).filter((d) => !(d in pkg[b].devDependencies)).sort().join(', ');
console.log(`dev dependencies only in ESM:       ${only('esm', 'cjs')}`);
console.log(`dev dependencies only in CommonJS:  ${only('cjs', 'esm')}`);
console.log(`tsconfig types:  ESM ${tsconfig.esm.compilerOptions.types.join(', ')}  |  CommonJS ${tsconfig.cjs.compilerOptions.types.join(', ')}`);
const importOf = (text) => /from '(\.\/app\.module[^']*)'/.exec(text)[1];
const lastLine = (text) => text.trim().split('\n').at(-1);
console.log(`main.ts imports the module from:  ESM '${importOf(main.esm)}'  |  CommonJS '${importOf(main.cjs)}'`);
console.log(`main.ts ends with:  ESM ${lastLine(main.esm)}  |  CommonJS ${lastLine(main.cjs)}`);

import { session } from '../session.mjs';

session(
  `
node templates.mjs
`,
  { packages: '../starter' },
);

$ node templates.mjs
package.json "type":  ESM module  |  CommonJS (not set)
test script:
  ESM       vitest run
  CommonJS  node --experimental-vm-modules ./node_modules/jest/bin/jest.js
dev dependencies only in ESM:       @vitest/coverage-v8, vite-tsconfig-paths, vitest
dev dependencies only in CommonJS:  @types/jest, jest, ts-jest, ts-loader, ts-node, tsconfig-paths
tsconfig types:  ESM vitest/globals, node  |  CommonJS node, jest
main.ts imports the module from:  ESM './app.module.js'  |  CommonJS './app.module'
main.ts ends with:  ESM await bootstrap();  |  CommonJS void bootstrap();

The differences follow from one setting. "type": "module" in package.json makes Node.js treat every .js file of the project as an ES module, so imports need their .js extension and main.ts may await at the top level. Without it, the project is CommonJS, imports stay extension-less and main.ts ends with void bootstrap();. The test runner follows: Vitest loads ES modules natively, while Jest runs through node --experimental-vm-modules so that it can load Nest 12’s packages, which are ES modules even in a CommonJS project. The migration guide adds that Jest can load them only on Node.js 24.9 or later.

For a new service, take the default, ESM with Vitest, unless your team’s tooling needs Jest. An existing CommonJS app does not have to change: Nest 12 runs it as it is.

nest generate adds a feature, and a dry run shows it first

nest generate, or nest g, runs a schematicschematic: A code generator that the Nest CLI runs to create or change files, such as the application, controller and resource schematics of @nestjs/schematics. that writes the files of a new piece and registers it in a module. --dry-run prints what it would do and writes nothing, which is the safe way to learn what each schematic produces:

import { session } from '../session.mjs';

// What nest generate would write for a new "orders" feature, without writing it (--dry-run).
session(
  `
cd ../starter
nest generate resource orders --dry-run
nest generate controller menus --dry-run
`,
  { packages: '../starter' },
);

$ cd ../starter
$ nest generate resource orders --dry-run
CREATE src/orders/orders.controller.spec.ts (582 bytes)
CREATE src/orders/orders.controller.ts (924 bytes)
CREATE src/orders/orders.module.ts (261 bytes)
CREATE src/orders/orders.service.spec.ts (463 bytes)
CREATE src/orders/orders.service.ts (629 bytes)
CREATE src/orders/dto/create-order.dto.ts (31 bytes)
CREATE src/orders/dto/update-order.dto.ts (176 bytes)
CREATE src/orders/entities/order.entity.ts (22 bytes)
UPDATE package.json (1463 bytes)
UPDATE src/app.module.ts (325 bytes)
Dry run enabled. No files written to disk.
$ nest generate controller menus --dry-run
CREATE src/menus/menus.controller.spec.ts (488 bytes)
CREATE src/menus/menus.controller.ts (99 bytes)
UPDATE src/app.module.ts (335 bytes)
Dry run enabled. No files written to disk.

resource orders would create 8 files: a module, a controller and a service with their tests, two DTO classes and an entity class, all under src/orders/. It would also update src/app.module.ts, to import the new OrdersModule, and package.json. Run without --dry-run, it adds @nestjs/mapped-types to the dependencies, because the generated UpdateOrderDto extends PartialType() from it, and installs it. controller menus writes less: the controller and its test, and one update to AppModule. In a terminal, nest g resource also asks which transport to use and whether to generate the CRUD methods; this recording took the defaults, a REST API with CRUD methods.

Practise: build the starter yourself

Do this on your own computer with Node.js 24.15 or later:

The questions mix the starter’s files, its scripts and the CLI; a wrong answer brings back a question on the same idea later in the session:

Interview questions

Key takeaways

• Running a Nest 12 app needs Node.js 20.19+ (22.12+ on the 22 line); the CLI’s generators need 22.22.3+, 24.15+ or 26+, so pin a version that meets both for the whole team.
• nest new writes 15 files: main.ts starts the app, AppModule lists the controller and the provider, and the rest configure TypeScript, Vitest, oxlint and Prettier.
• At start-up Nest creates AppService, passes it to AppController’s constructor and maps GET /; a request only calls methods on objects that already exist.
• npm run build compiles to dist/, npm test and npm run test:e2e run Vitest, npm run lint runs oxlint, and a string answer goes out as text/html with X-Powered-By: Express.
• ESM projects use .js in imports, top-level await and Vitest; CommonJS projects use extension-less imports and Jest through --experimental-vm-modules.
• nest generate writes a feature and registers it in a module; --dry-run shows the plan first.