# First steps

Source: https://docs.nestjs.com/first-steps

This set of articles covers the **core fundamentals** of Nest. To introduce the essential building blocks of a Nest application, we'll build a basic CRUD application whose features cover a lot of ground at an introductory level.

#### Language

Nest is written in [TypeScript](https://www.typescriptlang.org/) and runs on [Node.js](https://nodejs.org/en/), and it supports both TypeScript and plain JavaScript. Because Nest relies on the latest language features, using it with plain JavaScript requires [Babel](https://babeljs.io/).

Most examples in this documentation use TypeScript, but you can **switch any code snippet** to plain JavaScript syntax with the language toggle in the upper-right corner of the snippet.

#### Prerequisites

Make sure that [Node.js](https://nodejs.org) is installed on your operating system. Running a Nest application requires **v20.19 or later** (or **v22.12+** on the 22.x line). The Nest CLI's generators (such as `nest new` and `nest generate`) require **v22.22.3+, v24.15+, or v26+**. We recommend the latest active LTS release, which satisfies both requirements.

#### Setup

The quickest way to set up a new project is with the [Nest CLI](/cli/overview). With [npm](https://www.npmjs.com/) installed, run the following commands in your terminal:

```bash
$ npm i -g @nestjs/cli
$ nest new project-name
```

The CLI asks which module system to use: ESM (the default), which uses Vitest as the test runner, or CommonJS, which uses Jest.

It also asks whether to set up [NestJS Observe](https://www.observe.nestjs.com/ 'NestJS Observe'), the official observability platform for Nest. If you answer yes, the generated project includes the `@nestjs/observe` SDK, already wired into `AppModule` and `NestFactory.create()`. In an interactive terminal, the prompt defaults to yes; in non-interactive environments, such as CI, it is skipped and Observe is not added. Pass `--observe` or `--no-observe` to skip the prompt either way. See the [Observability](/observability/overview) chapter for what Observe covers.

If you set up Observe, the CLI then offers to link the new project to it, once the dependencies are installed. Accepting prints a code to approve at [observe.nestjs.com/link](https://www.observe.nestjs.com/link 'Link a project to NestJS Observe') (signing up first if you don't have an account; the free plan needs no payment details), and the CLI then writes the app key and secret into `.env` and makes every `nest start` script (`start`, `start:dev`, and `start:debug`) load it. Requests, background jobs, errors, and distributed traces start reporting the next time you start the application. To link later, or when the CLI doesn't offer it (without a terminal, or with `--skip-install`), run `npx @nestjs/observe link` in the project directory - see [Linking from the terminal](/observability/sdk#linking-from-the-terminal).

> info **Hint** New projects are generated with TypeScript's [strict](https://www.typescriptlang.org/tsconfig#strict) mode enabled. To opt out, set `"strict": false` in the generated `tsconfig.json`.

The CLI creates a `project-name` directory, installs the dependencies, generates a few boilerplate files, and populates a `src/` directory with several core files.

<div class="file-tree">
  <div class="item">src</div>
  <div class="children">
    <div class="item">app.controller.spec.ts</div>
    <div class="item">app.controller.ts</div>
    <div class="item">app.module.ts</div>
    <div class="item">app.service.ts</div>
    <div class="item">main.ts</div>
  </div>
</div>

The following table describes these core files:

|                          |                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------- |
| `app.controller.ts`      | A basic controller with a single route.                                                         |
| `app.controller.spec.ts` | The unit tests for the controller.                                                              |
| `app.module.ts`          | The root module of the application.                                                             |
| `app.service.ts`         | A basic service with a single method.                                                           |
| `main.ts`                | The entry file of the application. It uses `NestFactory` to create a Nest application instance. |

The `main.ts` file contains an async function that **bootstraps** the application:

```typescript

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

To create a Nest application instance, use `NestFactory` from `@nestjs/core`, which exposes a few methods for this purpose. The `create()` method returns an application object that implements the `INestApplication` interface. The methods of this object are described in the following chapters. In the `main.ts` example above, the application starts an HTTP listener and waits for inbound HTTP requests.

The project structure generated by the Nest CLI encourages the convention of keeping each module in its own dedicated directory.

> info **Hint** By default, if an error occurs while the application is being created, the process exits with code `1`. To have the error thrown instead, disable the `abortOnError` option (e.g., `NestFactory.create(AppModule, { abortOnError: false })`).

#### Platform

Nest is designed to be platform-agnostic. Platform independence lets you create reusable logical parts that can be used across several different types of applications. Nest can work with any Node.js HTTP framework once an adapter is created for it. Three HTTP platforms are supported out of the box: [Express](https://expressjs.com/), [Fastify](https://www.fastify.io), and the [`node:http`](https://nodejs.org/api/http.html) module built into Node.js. Choose the one that best suits your needs (see [HTTP adapters](/http/performance)).

|                    |                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform-express` | [Express](https://expressjs.com/) is a well-known, minimalist web framework for Node.js. It is a battle-tested, production-ready library with extensive community resources. Nest uses the `@nestjs/platform-express` package by default, so no setup is required.                                                                                                                  |
| `platform-fastify` | [Fastify](https://www.fastify.io/) is a high-performance, low-overhead framework focused on efficiency and speed. To learn how to use it, see [Fastify adapter](/http/performance#fastify-adapter).                                                                                                                                                                                 |
| `platform-node`    | The `NodeAdapter` runs Nest directly on the `node:http` module of Node.js, and is the fastest of the three. Its request and response objects come with the Express-style helpers, so most Express middleware works with it. We recommend it starting with v12.3, and it will become the default in v13. To learn how to use it, see [Node adapter](/http/performance#node-adapter). |

Each platform exposes its own application interface: `NestExpressApplication`, `NestFastifyApplication`, and `NestNodeApplication`, respectively.

When you pass a type to the `NestFactory.create()` method, as in the example below, the `app` object exposes methods that are available only on that platform. You don't **need** to specify a type **unless** you want to access the underlying platform API.

```typescript
const app = await NestFactory.create<NestExpressApplication>(AppModule);
```

##### Using the Node adapter

Starting with v12.3, we recommend running new applications on the Node adapter. It is not the default yet, so install the package:

```bash
$ npm i --save @nestjs/platform-node
```

Then pass a `NodeAdapter` instance to `NestFactory.create()` in the `main.ts` file:

```typescript

import { NestFactory } from '@nestjs/core';
import { NestNodeApplication, NodeAdapter } from '@nestjs/platform-node';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create<NestNodeApplication>(
    AppModule,
    new NodeAdapter(),
  );
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();
```

Nothing else in the application changes: controllers, providers, and most Express middleware work as they are. See [Node adapter](/http/performance#node-adapter) for the few places where it differs from Express.

The end-to-end test that the CLI generated (`test/app.e2e-spec.ts`) creates its own application, which runs on Express unless you pass an adapter. Pass `new NodeAdapter()` to its `createNestApplication()` call as well, so that the test runs on the same adapter as the application.

#### Running the application

Once the installation is complete, run the following command to start the application and listen for inbound HTTP requests:

```bash
$ npm run start
```

> info **Hint** To speed up development builds, use the [SWC builder](/recipes/swc) by passing the `-b swc` flag to the `start` script: `npm run start -- -b swc`.

This command starts the HTTP server on the port defined in the `src/main.ts` file (`3000`, unless the `PORT` environment variable is set). Once the application is running, open your browser and navigate to `http://localhost:3000/`. You should see the `Hello World!` message.

To watch your files for changes, start the application with the following command instead:

```bash
$ npm run start:dev
```

This command watches your files and, whenever they change, recompiles and restarts the server.

#### Linting and formatting

The [Nest CLI](/cli/overview) aims to scaffold a reliable development workflow that scales. For a fast default workflow, generated TypeScript projects come with a code **linter** and a **formatter** preinstalled: [oxlint](https://oxc.rs/docs/guide/usage/linter.html) and [Prettier](https://prettier.io/), respectively.

> info **Hint** Not sure how formatters and linters differ? See Prettier's [comparison](https://prettier.io/docs/en/comparison.html).

For headless environments where an IDE is not involved (continuous integration, Git hooks, etc.), the project includes ready-to-use `npm` scripts that run [`oxlint`](https://www.npmjs.com/package/oxlint) and [`prettier`](https://www.npmjs.com/package/prettier):

```bash
# Lint with oxlint
$ npm run lint

# Format with prettier
$ npm run format
```