Restful APIs has become a standard today to centralize all data management and complicated business logic that MVC monolith applications are struggling to handle. The separation between frontend (client code) and backend (Database, hard logic) facilitates a lot to operate with different components at same time, one backend to different client apps like iOS, android, web and others. Supposing and increase of interoperability for development team. Many languages and framework community are implemented their own version of restful APIs, the today’s turn is node.js.

Node.js has been the one of the top languages for many years leading the board of StackOverflow survey 2024. Has been adopted for many companies as their primary language.

But what make it special?

The node.js event loop implemented with the v8 engine, facilitate a lot of work when real-time applications need to be developed. Even many languages are being “node.js-fy” by implementing similar features in their engine to handling asynchronous process. Here a few uses cases where node.js has working excellent:

• Streaming
• Chat applications
• Real-time reports
• Dashboards

At the time of writing this article, node.js is used with Typescript with the finality of solve some paint issues that node.js has been arising, but they are solving with each version launched. In the today world of development, we constantly use 3rd party libraries, frameworks and some other tools that facilitate the RestAPIs development, the open source market for are immense and sometimes overwhelming.

Why not use node.js HTTP server directly

We definitely work with the HTTP module directly to attend a request and send a response. For a few endpoints are ok, problems happens when the application becomes bigger even with AdaptNotes application.

The criteria I recommend choosing a Framework can be divided in 2 categories:

• High level details:
  • Active community
  • Addressing Security issues path
• Tools that make you live easier:
  • Comprehensive documentation
  • Easy configuration
  • Good integration with OpenAPI spec (aka swagger): A way to expose interactive documentation of RestAPIs

I choose Nest.js Framework because it is widely used and matches the expectations of the series. In subsequent articles I demonstrate that changing between frameworks cannot be dramatic.

Installing necessary tools

The node.js ecosystem is bigger including their own package manager, today exists npm, yarn, pnpm. We will choose npm and LTS version of node. Installation page

Having node.js installed at your computer next thing is to open a terminal window, if your IDE has integrated it, nice!

All code will be uploaded in a Github repository.

Using typescript as First Citizen

In this series we implement the First Citizen approach with typescript to minimize the external frictions with external libraries and make typescript and Node.js the protagonism of the backend.

Our first command will be to create a new folder.

1
mkdir -p adaptable-backend-node

Go to the directory:

1
 cd adaptable-backend-node

Start and project

1
npm init

The terminal prompt will ask four a few inputs text, fill with the data that you want, typing the text and press enter.

1
This utility will walk you through creating a package.json file.
2
It only covers the most common items, and tries to guess sensible defaults.
3

4
See `npm help init` for definitive documentation on these fields
5
and exactly what they do.
6

7
Use `npm install <pkg>` afterwards to install a package and
8
save it as a dependency in the package.json file.
9

10
Press ^C at any time to quit.
11
package name: (adaptable-backend-node) adaptable-backend-node
12
version: (1.0.0) 0.0.1
13
description: An adaptable backend
14
entry point: (index.js)
15
test command:
16
git repository:
17
keywords:
18
author:
19
license: (ISC)
20
About to write to /adaptable-backend-node/package.json:
21

22
{
23
  "name": "adaptable-backend-node",
24
  "version": "0.0.1",
25
  "description": "An adaptable backend",
26
  "main": "index.js",
27
  "scripts": {
28
    "test": "echo \"Error: no test specified\" && exit 1"
29
  },
30
  "author": "",
31
  "license": "ISC"
32
}
33

34

35
Is this OK? (yes) yes

Configure node.js version

This step is crucial to maintain a consistent version to avoid bug and failures between node.js version. Add engines in package.json

1
{
2
  "name": "adaptable-backend-node",
3
  "version": "0.0.1",
4
  "description": "An adaptable backend",
5
  "main": "index.js",
6
  "engines": {
7
    "node": ">=23.x"
8
  },
9
  "scripts": {
10
    "test": "echo \"Error: no test specified\" && exit 1"
11
  },
12
  "author": "",
13
  "license": "ISC"
14
}

Assuming you install node.js 23, add the 23.x version number.

Configuring typescript file tsconfig.json

There are many options where you can follow up that match with your requirements, here an example of the typescript config will be set in the project:

1
{
2
  "compilerOptions": {
3
    "baseUrl": ".",
4
    "outDir": "./dist",
5
    "target": "es2023",
6
    "lib": [
7
      "es2023",
8
      "dom"
9
    ],
10
    "typeRoots": [
11
      "./node_modules/@types"
12
    ],
13
    "types": [
14
      "node"
15
    ],
16
    "module": "commonjs",
17
    "moduleResolution": "node",
18
    "experimentalDecorators": true,
19
    "emitDecoratorMetadata": true,
20
    "sourceMap": true,
21
    "declaration": false,
22
    "allowSyntheticDefaultImports": true,
23
    "paths": {
24
      "src/*": ["src/*"]
25
    }
26
  },
27
  "include": [
28
    "src/**/*.ts"
29
  ],
30
  "exclude": [
31
    "node_modules",
32
    "./public",
33
    "dist",
34
    "test"
35
  ]
36
}

Installing libraries

In the npm ecosystem exists 2 dependency types:

1. Development dependencies: Used for local development environment
2. Production dependencies: Used to generate the artifact executable.

Installing development dependencies:

1
npm install --save-dev @nestjs/cli @types/node tsconfig-paths typescript ts-node

A few production dependencies

1
npm install @nestjs/core @nestjs/platform-express @nestjs/swagger reflect-metadata

Now we have a few tools to start creating the rest API, despite the boilerplate code that nest.js documentation provides and some yeoman, cursor generators, the idea is to follow up incremental process to create every piece of the backend, let’s continue with nest-cli.json config:

Create a new file with name nest-cli.json or copy the content of the file:

1
{
2
    "language": "ts", // typescript ts, for brevity
3
    "collection": "@nestjs/schematics", // make reference to the previously package installed
4
    "sourceRoot": "src", // our code will reside on src folder
5
    "monorepo": true, // All structure on nest.js modules are monorepo
6
    "compilerOptions": {
7
        "plugins": [
8
            {
9
                "name": "@nestjs/swagger/plugin",
10
                "options": {
11
                    "dtoFileNameSuffix": [
12
                        ".dto.ts" // This step are important to show models on swagger
13
                    ],
14
                    "classValidatorShim": false
15
                }
16
            }
17
        ]
18
    },
19
    "projects": {
20
        "restAPI": { // We call restAPI, because in the future we can have [Technology-name]API
21
            "type": "application",
22
            "entryFile": "main",
23
            "sourceRoot": "src/apps/restAPI"
24
        }
25
    }
26
}

Creating the folder structure

Having the CLI runner specification that nest.js requires, let’s create this folder structure:

1
mkdir -p src/apps/restAPI/frameworks/nestjs/restControllers
2
mkdir -p src/core

Nest.js and other frameworks are based in MVC pattern to separate concerns, but they call Controllers for every endpoint router, in this series we will refer them as RestControllers because is a good practice and remind us the Rest technology can change to another.

Let’s create our first DTO (note.dto.ts) inside restController, the suffix .dto.ts is because on the nest-cli.json will find all files with that suffix to render them in swagger docs.

1
export class NoteDto {
2
  id: number;
3
  content: string;
4
};

In the folder src/apps/restAPI/frameworks/nestjs/restControllers, create a new file noteRestController.ts with this content:

1
import { Controller, Get } from "@nestjs/common";
2
import { ApiOkResponse } from "@nestjs/swagger";
3

4
import { NoteDto } from "./note.dto.ts";
5

6
@Controller("notes")
7
export class NoteRestcontroller {
8

9
  @Get()
10
  @ApiOkResponse({
11
    type: [NoteDto],
12
    description: "Get all notes",
13
  })
14
  public getNotes(): NoteDto[] {
15
    return [
16
        {
17
            id: 1,
18
            content: "Hello 1"
19
        },
20
        {
21
            id: 2,
22
            content: "Hello 2"
23
        },
24
    ];
25
  }
26
}

We are importing the Decorators from @nestjs/common for these purposes:

• Controller: Help us to identity the class NoteRestController will contain all method implementations and will redirect the incoming requests, the parameter string “notes” facilitates the routing.
• Get: Tell to nest.js framework the route and method will be a Restful Get verb.

For @nestjs/swagger we are importing the ApiOkResponse to tell swagger doc generation the type of the response, defined previously on NoteDto class, which normally receive the type and description to express the intention of the endpoint we are building.

Finally, there is a getNotes() method implementation using sample data. Having our first controller we can proceed to create the server instance provided by nest.js to start creating our first endpoint.

Creating the Route that will contain all RestControllers grouped, it depends on the approach or how much larger the app is. You can create many Routes as needed, which the nest.js team calls Module. To guarantee separation of concerns is good practice, split your components (previously explained in the introduction article). In this opportunity I created one Route, and we’ll see in the next articles how we can improve modularization.

1
import { Module } from "@nestjs/common";
2

3
import { NoteRestController } from "./restControllers/noteRestController";
4

5
@Module({
6
  controllers: [ NoteRestController ],
7
})
8
export class Route {}

In this opportunity we only import the Module from @nestjs/common to group the list of RestControllers. Next, we’ll create the server factory and swagger configurations in the nest.js folder to make the correct render possible according to nest.js guidelines:

1
import { NestFactory } from "@nestjs/core";
2
import { INestApplication } from "@nestjs/common";
3
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
4

5
import { Route } from "./route";
6

7
export class NestServerFactory {
8
  static async create(): Promise<INestApplication> {
9
    const app = await NestFactory.create(Route);
10

11
    this.setupSwagger(app);
12

13
    return app;
14
  }
15

16
  private static setupSwagger(app: INestApplication): void {
17
    const config = new DocumentBuilder()
18
      .setTitle("AdaptNotes API")
19
      .setDescription("The AdaptNotes API documentation")
20
      .setVersion("1.0")
21
      .build();
22

23
    const document = SwaggerModule.createDocument(app, config);
24
    SwaggerModule.setup("docs", app, document);
25
  }
26
}

• NestFactory: Helps to create the application server given the Routes or other middleware configurations that will contain the server initialization.
• INestApplication: The interface declaration of nest.js to keep everything typed as much as possible.
• SwaggerModule: The swagger helper module that will generate the swagger docs, given the parameters “docs”, the application server (app), and the setup and configuration made by the DocumentBuilder class.
• DocumentBuilder: This is a programmatic way to set up all configurations of swagger (openapi) documentation.

Having the minimal setup of the application, the next step is to make it runnable in the context of the restAPI application. Creating the Server instance will take care of this:

1
import { NestServerFactory } from "./frameworks/nestjs/nestServerFactory";
2

3
export class Server {
4
  private static servers = {
5
    nestjs: NestServerFactory,
6
  };
7

8
  private server;
9

10
  async run({ port }: { port: number }) {
11
    const framework = "nestjs";
12
    this.server = await Server.servers[framework].create();
13
    await this.server.listen(port);
14
    console.info(`Server running on ${await this.getUrl()}`);
15
  }
16

17
  async getUrl() {
18
    return this.server.getUrl()
19
  }
20

21
  async close() {
22
    await this.server.close();
23
    console.warn("Server closed");
24
  }
25
}

The server class will encapsulate all the logic behind the scenes of backend framework operations like run(), getUrl(), and close(). I implemented a strategy pattern to choose (add links, wiki and refactoring guru) between frameworks. The servers attribute serves that purpose.

When we want to incorporate another framework or switch to another, you can add them in the servers object. Inside the run() function it receives an object as parameter configuration that allows us to change a port. The framework variable can be passed as configuration, so that flexibility can be performed by separating each framework as factory servers. With process.on(“SIGINT”) we are capturing any external call to close the server. This will be useful to detect any failure and send a notification in case something unexpected happens.

We need an entry point that defined in the nest-cli.json file called main which will run server.

1
import { Server } from "./server";
2

3
const server = new Server();
4
server.run({ port: 3000 });
5

6
process.on("SIGINT", async () => {
7
  console.warn("Closing server");
8
  await server.close();
9
});

One step more to have the initial rest API running, add a new command inside the scripts’ folder of package.json to run the restAPI in development mode which means, every change a live-reload server can perform the updates.

1
"scripts": {
2
  "start:restAPI:dev": "npx nest start restAPI --watch"
3
}

Now, in a terminal window, run:

1
npm run start:restAPI:dev

you should see an output like this:

1
[1:48:39 PM] Starting compilation in watch mode...
2
[1:48:42 PM] Found 0 errors. Watching for file changes.
3
[Nest] 76467  - 07/14/2025, 1:48:42 PM     LOG [NestFactory] Starting Nest application...
4
[Nest] 76467  - 07/14/2025, 1:48:42 PM     LOG [InstanceLoader] Route dependencies initialized +9ms
5
[Nest] 76467  - 07/14/2025, 1:48:42 PM     LOG [RoutesResolver] NoteRestController {/notes}: +16ms
6
[Nest] 76467  - 07/14/2025, 1:48:42 PM     LOG [RouterExplorer] Mapped {/notes, GET} route +3ms
7
[Nest] 76467  - 07/14/2025, 1:48:42 PM     LOG [NestApplication] Nest application successfully started +1ms
8
Server running on http://[::1]:3000

Congrats, you have the restAPI up and running. The nest logs tell us line by line the following:

• LOG [NestFactory] Starting Nest application: The framework is running without errors.
• LOG [InstanceLoader] Route dependencies initialized: Our Route.ts file was loaded fine.
• LOG [RoutesResolver] NoteRestController /notes: The NoteRestController was loaded and the notes/ route is available to receive calls.
• Server running on http://[::1]:3000: This is the custom message we use when the server is running inside ServerFactory framework.

According to the nestServerFactory.ts file we specify in the SwaggerModule.setup(“docs”) line, “docs” as an entry point to see the swagger document. Open a new browser window and go to http://[::1]:3000/docs. You will see a page like this:

We can confirm all notes controller and routes are rendering well according to the previous setup for RestControllers.

Try the method get Notes by pressing the button “try it out” and then execute the response:

It’s responding with the sample data as we configured.

At this point we have a very basic but flexible config that allows us to add features quickly using the framework.

Configuration: Environment variables

Continuing with the code, we are hard-coding a lot of values like port, swagger description, and other strings that can change in the near future, which can be tedious to change when requested. We can divide it into constants that rarely change and environment variables that are convenient to keep in the context of exportable variables. In our example, the swagger description. But the port is a number value that can be changed by the server, deployment, and orchestrator service that brings the restAPI to production environment. In the Node.js ecosystem there are many alternatives to handle environment variables, validate and more. In our case I intend to implement our Configuration that will be adapted to incoming needs, minimize the requested changes by using external libraries, and last but not least, node.js API for environment variables is good enough that it doesn’t require an external lib.

Responsibilities of configuration

• Load environment variables from .env file in the root folder which facilitates the development cycle to load config and test locally.
• Define which variables are required or not. Believe me when I say I spent 2-3 hours debugging a cold start error, when I only had a missing env-var that was required.
• Required env-vars should kill the server

Creating the configuration class

The Configuration class will load environment variables from a configuration file .env used in several conventions to declare and load env-vars in development mode. This can be extended to load a .env.test when unit tests will run. In any case, it’s better to set it up in the early stages. The Configuration class will be a singleton pattern that contains, in execution time, all environments loaded and centralized. This avoids referring to process.env.NAME_VAR every time and enforces the types in typescript, which is desirable. Now we’ll create the .env file with the necessary key=value.

1
# This is a comment will be ignore, you can describe your env
2
PORT=3001
3
NODE_ENV=development

Now we’ll create the configuration.ts file that will handle these responsibilities, creating some interfaces and types to keep everything typed.

1
import { readFileSync, existsSync } from "fs";
2
import * as path from "path";
3

4
interface EnvConfig {
5
  NODE_ENV: "development" | "production" | "test";
6
  PORT: number;
7
}
8

9
type EnvVarConfig = {
10
  required: boolean;
11
  type: "string" | "number" | "boolean";
12
  default?: string | number | boolean;
13
};

The readFileSync and existsSync functions are imported from FileSystem node module to read the file and check if the file exists. Remember, the restAPI cannot start if these minimal dependencies are not completed.

The interface EnvConfig helps us to give the name and type of each variable we want to control. The type EnvVarConfig allows us to give a schema to each environment.

1
export class Configuration {
2
  private static instance: Configuration;
3
  private readonly config: Map<keyof EnvConfig, string | number | boolean> = new Map();
4

5
  private readonly envSchema: Record<keyof EnvConfig, EnvVarConfig> = {
6
    NODE_ENV: { required: true, type: "string" },
7
    PORT: { required: true, type: "number" },
8
  };
9

10
  private constructor() {
11
    this.loadEnvFile();
12
    this.validateConfig();
13
  }
14

15
  private loadEnvFile(): void {
16
    const envFile = process.env.NODE_ENV === "test" ? ".env.test" : ".env";
17
    const envPath = path.resolve(process.cwd(), envFile);
18

19
    if (!existsSync(envPath)) {
20
      console.warn(`Warning: ${envFile} file not found at ${envPath}`);
21
      return;
22
    }
23

24
    try {
25
      const content = readFileSync(envPath, "utf8");
26
      this.parseEnvContent(content);
27
    } catch (error) {
28
      console.error(`Error reading ${envFile}:`, error);
29
    }
30
  }
31
} // Short for brevity

We are declaring the typical singleton instance of the same class, create a config map (for performance improvement) that will have any keys defined in EnvConfig. The envSchema variable object serves the purpose of defining the type of the schema, types, and if they are required or not.

In the constructor we have the calls loadEnvFile() and validateConfig(). Analysis for loadEnvFile():

• Load file depends on NODE_ENV setup when we will run the start command.
• Loading the complete path of the file.
• Load the content of the .env files as string.
• Checking if the file exists then call parseEnvContent().

1
private parseEnvContent(content: string): void {
2
  const lines = content.split("\n");
3
  const envVars = new Map<string, string>();
4

5
  for (const line of lines) {
6
    const trimmed = line.trim();
7

8
    if (!trimmed || trimmed.startsWith("#")) continue;
9

10
    const equalIndex = trimmed.indexOf("=");
11
    if (equalIndex === -1) continue;
12

13
    const key = trimmed.slice(0, equalIndex).trim();
14
    let value = trimmed.slice(equalIndex + 1).trim();
15

16
    value = value.replace(/^(['"])(.*)\1$/, "$2");
17

18
    envVars.set(key, value);
19
  }
20

21
  for (const [key, value] of envVars) {
22
    if (!(key in process.env)) {
23
      process.env[key] = value;
24
    }
25
  }
26
}

• Receive the string content
• Split the content of the files into lines.
• Iterate on lines and check if there’s a comment ’#’
• Check the equality character to get the key and the value separated.
• Replace any char ’ or ” to clean the values.
• Finally, check if the env-vars already exist, so process.env takes precedence.

After loading env-vars from the file, the remaining step is to verify if the loaded envs into process.env match with the schema we defined.

1
private validateConfig(): void {
2
  const missingRequired: string[] = [];
3

4
  for (const [key, schema] of Object.entries(this.envSchema)) {
5
    const envKey = key as keyof EnvConfig;
6
    const rawValue = process.env[envKey];
7

8
    if (!rawValue) {
9
      if (schema.required) {
10
        missingRequired.push(envKey);
11
        continue;
12
      }
13
      if (schema.defaultValue !== undefined) {
14
        this.config.set(envKey, schema.defaultValue);
15
        continue;
16
      }
17
    }
18

19
    const parsedValue = this.parseValue(rawValue!, schema.type);
20
    this.config.set(envKey, parsedValue);
21
  }
22

23
  if (missingRequired.length > 0) {
24
    throw new Error(`Missing required environment variables: ${missingRequired.join(", ")}`);
25
  }
26
}
27

28
private parseValue(value: string, type: "string" | "number"): string | number {
29
  if (type === "number") {
30
    const parsed = Number(value);
31
    if (isNaN(parsed)) {
32
      throw new Error(`Invalid number value: ${value}`);
33
    }
34
    return parsed;
35
  }
36
  return value;
37
}

• Iterate over envSchema
• Get key, and compare if it matches with the schema
• Check for default values, then ignore them
• parseValue() utility function to check if a value declared as number can be parsed to number.

Finally, the traditional getInstance() method from Singleton pattern and get(k) to get one value given a key

1
  public static getInstance(): Configuration {
2
    return Configuration.instance ??= new Configuration();
3
  }
4

5
  // Getter methods with type safety
6
  public get<K extends keyof EnvConfig>(key: K): EnvConfig[K] {
7
    return this.config.get(key) as EnvConfig[K];
8
  }

Applying config

After implementing the load, validation and typed environment variables, it’s time to use it in the existing code.

In the main entry point of restAPI app, we’ll import the config and get the port number to avoid hard-coding.

1
import { Server } from "./server";
2
import { config } from "src/core/configuration/configuration";
3

4
const server = new Server();
5
server.run({ port: 3000 });
6
server.run({ port: config.get("PORT") });
7

8
process.on("SIGINT", async () => {
9
  console.warn("Closing server");
10
  await server.close();
11
});

Now we’ll run the server again. The port should change to 3001

1
npm run start:restAPI:dev

Now you’ve implemented your own dotenv like library that serves your purpose and validates if some of them are required or not.

Final adjustments

Assuming you will use a git system as I am using Github repo to upload the code, it’s required to ignore some dependencies and binary files generated in the development process by adding an official .gitignore to the project. There are other hard-coded things you can fix on your own. I upload all the code on this Github Repository branch of the article to work as next steps in coming articles.

Conclusion

In this series we explore an alternative way to use backend frameworks, since changing the structure of folder, conventions and learn how something simpler like load & validate environment variables can give you the flexibility to add interesting features without fall in the libraries fanatic installation that will incur in long-time refactoring and unfinishable maintenance.

In the next article we will start creating a separated way to use dependency injection that does not depend on frameworks, giving you all control.

• Have you tried this approach before?
• What do you think of the separation of concerns apply?
• Are you using the boilerplate that frameworks page provide?

Let me know in the comments.