Javascript

Introduction to RESTful APIs with NestJS

Sep 15, 2021

13 min read

Welcome to an introduction to RESTful APIs with NestJS. Understanding JavaScript and TypeScript will make it easier to follow the directions in this article, but you don't necessarily need to be proficient.

NestJS is one of the most rapidly growing frameworks for building Node.js server-side applications. Companies such as Roche, Adidas, and Autodesk, all trust NestJS when it comes to building efficient and scalable server-side applications.

NestJS is based heavily on Angular, and uses Angular-like modules, services, controllers, pipes, and decorators. This allows NestJS to help developers create scalable, testable, loosely coupled, and easily maintainable applications. NestJS was built with TypeScript, but it can also support pure JavaScript development.

NestJS offers a level of abstraction above two very popular Node.js frameworks, either Express.js or Fastify. This means that all of the great middleware that are available for Express.js and Fastify can also be used with NestJS.

The best way to get familiar with NestJS is to build a basic RESTful API with CRUD (Create, Read, Update, and Delete) functionality. This is exactly what we'll be doing together in this article. We'll be building a simple RESTful API for a Blog, with endpoints to handle CRUD operations on blog posts.

Getting Started

Code editor

Using Visual Studio Code as a code editor can help speed up NestJS development because of its smart IntelliSense and great TypeScript support.

In Visual Studio Code, make sure that you have the following user setting by going to File / Preferences / Settings, and searching for the user setting named typescript.preferences.importModuleSpecifier. Make sure to set it to relative as seen below.

"typescript.preferences.importModuleSpecifier": "relative"

This will allow Visual Studio Code to use relative paths rather than absolute paths when auto-importing. Using absolute path imports in our application can lead to problems if and when our code ends up in a different directory.

Insomnia

Insomnia is a useful API testing tool that we will use to test the NestJS API that we will be building.

The NestJS CLI

To get started with NestJS, let's install the Nest CLI. The Nest CLI is a command-line interface tool that makes it easy to develop, and maintain NestJS applications. It allows us to run our application in development mode, and to build and bundle it for a production-ready release.

npm i -g @nestjs/cli

Creating a new NestJS project

With the Nest CLI now installed, we can use it to create a new project.

nest new rest-api

This command will create a new project directory called rest-api. It will create a base structure for our project, and add in the following core Nest files:

app.controller.ts: A controller with a single route.
app.controller.spec.ts: The controller's unit tests.
app.module.ts: The root module of our application.
app.service.ts: A service for the AppModule's business logic.
main.ts: The entry file of our application.

The initial project structure created by the Nest CLI encourages us to follow the common convention of keeping each module in its own directory.

Testing the sample endpoint

The installation of NestJS comes with a sample API endpoint that we can test by making a request to it. If we open app.controller.ts, we can see that there is a GET endpoint that was created for us with the @Get() decorator. It returns a 'Hello World!' string.

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

Let's run npm run start:dev from our project folder. This will run our NestJS app in watch mode, which provides live-reload support when application files are changed.

Once NestJS is running, let's open http://localhost:3000 in our web browser. We should see a blank page with the Hello World! greeting.

We can also use API testing tools such as Insomnia to make a GET request to http://localhost:3000. We should get the same Hello World! greeting as our result.

Let's remove this endpoint since it was only added by the Nest CLI for demo purposes. Go ahead and delete app.controller.ts, app.service.ts, and app.controller.spec.ts. Also, delete all references to AppController and AppService in app.module.ts.

Creating a feature module

The architectural design of NestJS encourages feature modules. This feature-based design groups the functionality of a single feature in one folder, registered in one module. This design simplifies the codebase and makes code-splitting very easy.

Module

We create modules in NestJS by decorating a class with the @Module decorator. Modules are needed to register controllers, services, and any other imported sub-modules. Imported sub-modules can have their own controllers, and services, registered.

Let's use the Nest CLI to create the module for our blog posts.

nest generate module posts

This gives us an empty PostsModule class in the posts.module.ts file.

Interface

We will use a TypeScript interface to define the structure of our JSON object that will represent a blog post.

An interface is a virtual or abstract structure that only exists in TypeScript. Interfaces are used only for type-checking purposes by the TypeScript compiler. TypeScript interfaces do not produce any JavaScript code during the transpilation of TypeScript to JavaScript.

Let's use the Nest CLI to create our interface.

cd src/posts 
nest generate interface posts

These commands allow us to create a posts.interface.ts file in the feature-based folder for our blog posts, which is /src/posts.

The TypeScript interface keyword is used to define our interface. Let's make sure to prefix it with export to allow this interface to be used throughout our application

export interface PostModel {
  id?: number;
  date: Date;
  title: string;
  body: string;
  category: string;
}

From the command-line prompt, let's reset our current working directory back to the root folder of our project by using the following command.

cd ../..

Service

Services are classes that handle business logic. The PostsService that we will be creating will handle the business logic needed to manage our blog posts.

Let's use the Nest CLI to create the service for our blog posts.

nest generate service posts

This will give us an empty PostsService class in the posts.service.ts file.

The @Injectable() decorator marks the PostsService class as a provider that we can register in the providers array of our PostsModule, and then inject into our controller class. More on this later.

Controller

Controllers are classes that handle incoming requests and return responses to the client. A controller can have more than one route or endpoint. Each route or endpoint can implement its own set of actions. The NestJS routing mechanism handles the routing of requests to the right controller.

Let's use the Nest CLI to create the controller for our blog posts.

nest generate controller posts

This will give us an empty PostsController class in the posts.controller.ts file.

Let's inject our PostsService into the constructor of the PostsController class.

import { Controller } from '@nestjs/common';
import { PostsService } from './posts.service';

@Controller('posts')
export class PostsController {
  constructor(private readonly postsService: PostsService) {}
}

NestJS uses dependency injection to set up a reference to PostsService from within our controller. We can now use the methods provided by PostsService by referencing this.postsService from within our controller class.

Registering our controller and service

Let's make sure that our PostsModule registers our PostsController and PostsService. The nest generate service post and nest generate controller post commands that we ran earlier have automatically registered the PostsService and PostsController classes in the PostsModule for us.

@Module({
  controllers: [PostsController],
  providers: [PostsService],
})
export class PostsModule {}

NestJS uses the term providers to refer to service classes, middleware, guards, and more.

If the PostsService class needs to be made available to other modules within our application, we can export it from PostsModule by using the exports array. This way, any module importing the PostsModule will be able to use the PostsService.

@Module({
  controllers: [PostsController],
  providers: [PostsService],
  exports: [PostsService],
})
export class PostsModule {}

Importing PostsModule into AppModule

We now have one cohesive and well-organized module for all the functionality related to our blog posts. However, all the functionality that will be provided by our PostsModule is not available to our application unless the AppModule imports it.

If we revisit the AppModule, we can see that the PostsModule has been automatically added to the imports array by the nest generate module post command that we ran earlier.

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

Adding Service and Controller logic

Our PostsService and PostsController have no functionality implemented at the moment. Let's now implement our CRUD endpoints and their corresponding logic while adhering to RESTful standards.

NestJS makes it easy to use MongoDB (using the @nestjs/mongoose package), or PostgreSQL (using Prisma or TypeORM) to persist and manage our application's data. However, for the sake of simplicity, let's create a local array in our service to mock a database.

import { Injectable } from '@nestjs/common';
import { PostModel } from './posts.interface';

@Injectable()
export class PostsService {
  private posts: Array<PostModel> = [];
}

A service, or provider, as NestJS refers to them, can have its scope configured. By default, a service has a singleton scope. This means that a single instance of a service is shared across our entire application. The initialization of our service will occur only once during the startup of our application. The default singleton scope of services means that any class that injects the PostsService will share the same posts array data in memory.

Get all posts

Let's add a method to our PostsService that will return all of our blog posts.

public findAll(): Array<PostModel> {
  return this.posts;
}

Let's add a method to our PostsController that will make the logic of the service's findAll() method available to client requests.

@Get()
public findAll(): Array<PostModel> {
  return this.postsService.findAll();
}

The @Get decorator is used to create a GET /posts endpoint. The /posts path of the request comes from the @Controller('posts') decorator that was used in order to define our controller.

Get one post

Let's add a method to our PostsService that will return a specific blog post that a client may be looking for. If the id of the requested post is not found in our list of posts, let's return an appropriate 404 NOT FOUND HTTP error.

public findOne(id: number): PostModel {
  const post: PostModel = this.posts.find(post => post.id === id);

  if (!post) {
    throw new NotFoundException('Post not found.');
  }

  return post;
}

Let's add a method to our PostsController that will make the logic of the service's findOne() method available to client requests.

@Get(':id')
public findOne(@Param('id', ParseIntPipe) id: number): PostModel {
  return this.postsService.findOne(id);
}

The @Get decorator is used with a parameter as @Get(':id') here to create a GET /post/[id] endpoint, where [id] is an identification number for a blog post.

@Param, from the @nestjs/common package, is a decorator that makes route parameters available to us as properties in our method.

@Param values are always of type string. Since we defined id to be of type number in TypeScript, we need to do a string to number conversion. NestJS provides a number of pipes that allow us to transform request parameters. Let's use the NestJS ParseIntPipe to convert the id to a number.

Create a post

Let's add a method to our PostsService that will create a new blog post, assign the next sequential id to it, and return it. If the title is already being used by an existing blog post, we will throw a 422 UNPROCESSABLE ENTITY HTTP error.

public create(post: PostModel): PostModel {
  // if the title is already in use by another post
  const titleExists: boolean = this.posts.some(
    (item) => item.title === post.title,
  );
  if (titleExists) {
    throw new UnprocessableEntityException('Post title already exists.');
  }

  // find the next id for a new blog post
  const maxId: number = Math.max(...this.posts.map((post) => post.id), 0);
  const id: number = maxId + 1;

  const blogPost: PostModel = {
    ...post,
    id,
  };

  this.posts.push(blogPost);

  return blogPost;
}

Let's add a method to our PostsController that will make the logic of the service's create method available to client requests.

@Post()
public create(@Body() post: PostModel): PostModel {
  return this.postsService.create(post);
}

The @Post decorator is used to create a POST /post endpoint.

When we use the NestJS decorators for the POST, PUT, and PATCH HTTP verbs, the HTTP body is used to transfer data to the API, typically in JSON format.

We can use the @Body decorator to parse the HTTP body. When this decorator is used, NestJS will run JSON.parse() on the HTTP body and provide us with a JSON object for our controller method. Within this decorator, we declare post to be of type Post because this is the data structure that we are expecting the client to provide for this request.

Delete a post

Let's add a method to our PostsService that will delete a blog post from our in-memory list of posts using the JavaScript splice() function. A 404 NOT FOUND HTTP error will be returned if the id of the requested post is not found in our list of posts.

public delete(id: number): void {
  const index: number = this.posts.findIndex(post => post.id === id);

  // -1 is returned when no findIndex() match is found
  if (index === -1) {
    throw new NotFoundException('Post not found.');      
  }

  this.posts.splice(index, 1);
}

Let's add a method to our PostsController that will make the logic of the service's delete method available to client requests.

@Delete(':id')
public delete(@Param('id', ParseIntPipe) id: number): void {  
  this.postsService.delete(id);
}

Update a post

Let's add a method to our PostsService that will find a blog post by id, update it with newly submitted data, and return the updated post. A 404 NOT FOUND HTTP error will be returned if the id of the requested post is not found in our list of posts. A 422 UNPROCESSABLE ENTITY HTTP error will be returned if the title is being used for another blog post.

public update(id: number, post: PostModel): PostModel {
  this.logger.log(`Updating post with id: ${id}`);

  const index: number = this.posts.findIndex((post) => post.id === id);

  // -1 is returned when no findIndex() match is found
  if (index === -1) {
    throw new NotFoundException('Post not found.');
  }

  // if the title is already in use by another post
  const titleExists: boolean = this.posts.some(
    (item) => item.title === post.title && item.id !== id,
  );
  if (titleExists) {
    throw new UnprocessableEntityException('Post title already exists.');
  }

  const blogPost: PostModel = {
    ...post,
    id,
  };

  this.posts[index] = blogPost;

  return blogPost;
}

Let's add a method to our PostsController that will make the logic of the service's update method available to client requests.

@Put(':id')
public update(@Param('id', ParseIntPipe) id: number, @Body() post: PostModel): PostModel {
  return this.postsService.update(id, post);
}

We use the @Put decorator to make use of the HTTP PUT request method. PUT can be used to both create and update the state of a resource on the server. If we know that a resource already exists, PUT will replace the state of that resource on the server.

Testing our feature module

Let's start our development server using npm run start:dev. Then, let's open the Insomnia application to test the API endpoints that we created for the PostsModule.

Get all posts

Let's make a GET request to http://localhost:3000/posts. The result should be a 200 OK success code with an empty array.

Create a post

Let's make a POST request to http://localhost:3000/posts using the following as our JSON body.

{
  "date": "2021-08-16",
  "title": "Intro to NestJS",
  "body": "This blog post is about NestJS",
  "category": "NestJS"
}

We should get a successful 201 Created response code, along with a JSON representation of the post that was created, including the id field that has been automatically generated.

Get a post

Let's make a GET request to http://localhost:3000/posts/1. The result should be a successful 200 OK response code, along with the data for the post with an id of 1.

Update a post

Let's make a PUT request to http://localhost:3000/posts/1 using the following as our JSON body.

{
  "date": "2021-08-16",
  "title": "Intro to TypeScript",
  "body": "An intro to TypeScript",
  "category": "TypeScript"
}

The result should be a successful 200 OK response code, along with a JSON representation of the post that was updated.

Delete a post

Let's make a DELETE request to http://localhost:3000/posts/1. The result should be a successful 200 OK response code with no JSON object returned.

Logging

NestJS makes it easy to add logging to our application. Rather than using console.log() statements, we should use the Logger class provided by NestJS. This will provide us with nicely formatted log messages in the Terminal.

Let's add logging to our API. The first step is to define the logger in our service class.

import { Injectable, Logger, NotFoundException } from '@nestjs/common';
import { PostModel } from './posts.interface';

@Injectable()
export class PostsService {
  private posts: Array<PostModel> = [];
  private readonly logger = new Logger(PostsService.name);

  // ...
}

With the logger now defined, we can add log statements in our service class. Here is an example of a log statement that we can add as the first line of the findAll() method in the PostsService class.

this.logger.log('Returning all posts');

Such statements provide us with a convenient log message in the Terminal every time a service method is called during a client's request to our API.

When a GET /posts request is sent, we should see the following message in the Terminal.

[PostsService] Returning all posts.

Swagger

NestJS makes it easy to add the OpenAPI specification to our API using the NestJS Swagger package. The OpenAPI specification is used to describe RESTful APIs for documentation and reference purposes.

Swagger setup

Let's install Swagger for NestJS.

npm install --save @nestjs/swagger swagger-ui-express

Swagger configuration

Let's update the main.ts file that bootstraps our NestJS application by adding Swagger configuration to it.

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Blog API')
    .setDescription('Blog API')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

With our NestJS app running, we can now go to http://localhost:3000/api to view the Swagger documentation for our API. Notice that default is displayed above the routes for our posts.

Let's change that by adding @ApiTags('posts') right below @Controller('posts') in our PostsController class. This will replace default with posts to indicate that this set of endpoints belongs to the posts feature model.

@Controller('posts')
@ApiTags('posts')

ApiProperty

Let's make the properties of our PostModel interface visible to Swagger. We do so by annotating fields with the ApiProperty() decorator, or the ApiPropertyOptional() decorator for optional fields.

To use these decorators, we must first change our interface to a class in the posts.interface.ts file.

export class PostModel {
  @ApiPropertyOptional({ type: Number })
  id?: number;
  @ApiProperty({ type: String, format: 'date-time' })
  date: Date;
  @ApiProperty({ type: String })
  title: string;
  @ApiProperty({ type: String })
  body: string;
  @ApiProperty({ type: String })
  category: string;
}

Within the ApiProperty() decorator applied to each field, we describe the field type. The id field is optional since we don't know of a new blog post's id when creating it. A date-time string format is used for the date field.

These changes allow the PostModel structure to be documented within Swagger. With our NestJS app running, we can now go to http://localhost:3000/api to view the documentation of the PostModel.

ApiResponse

Let's use the @ApiResponse() decorator for Swagger to document all the possible responses from our API's endpoints. This will be helpful for informing users of our API what responses they can expect to receive by calling a given endpoint. We will be making these changes in the PostsController class.

For the findAll method, let's use the @ApiOkResponse() decorator to document a 200 OK success response.

@Get()
@ApiOkResponse({ description: 'Posts retrieved successfully.'})
public findAll(): Array<PostModel> {
  return this.postsService.findAll();
}

For the findOne method, let's use the @ApiOkResponse() decorator to document a 200 OK response when the post is found. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when a post is not found.

@Get(':id')
@ApiOkResponse({ description: 'Post retrieved successfully.'})
@ApiNotFoundResponse({ description: 'Post not found.' })
public findOne(@Param('id', ParseIntPipe) id: number): PostModel {
  return this.postsService.findOne(id);
}

For the create method, let's use the @ApiCreatedResponse() decorator to document a 201 CREATED response when a post is created. Let's use the @ApiUnprocessableEntityResponse() decorator to document a 422 UNPROCESSABLE ENTITY HTTP error when a duplicate post title is found.

@Post()
@ApiCreatedResponse({ description: 'Post created successfully.' })
@ApiUnprocessableEntityResponse({ description: 'Post title already exists.' })
public create(@Body() post: PostModel): void {
  return this.postsService.create(post);
}

For the delete method, let's use the @ApiOkResponse() decorator to document a 200 OK response when a post is deleted. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when the post to be deleted is not found.

@Delete(':id')
@ApiOkResponse({ description: 'Post deleted successfully.'})
@ApiNotFoundResponse({ description: 'Post not found.' })
public delete(@Param('id', ParseIntPipe) id: number): void {
  return this.postsService.delete(id);
}

For the update method, let's use the @ApiOkResponse() decorator to document a 200 OK response when a post is updated. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when the post to be updated is not found. Let's use the @ApiUnprocessableEntityResponse() decorator to document a 422 UNPROCESSABLE ENTITY HTTP error when a duplicate post title is found.

@Put(':id')
@ApiOkResponse({ description: 'Post updated successfully.'})
@ApiNotFoundResponse({ description: 'Post not found.' })
@ApiUnprocessableEntityResponse({ description: 'Post title already exists.' })
public update(@Param('id', ParseIntPipe) id: number, @Body() post: PostModel): void {
  return this.postsService.update(id, post);
}

After saving these changes, all response codes and their related descriptions should now be listed for each endpoint on the Swagger web page at http://localhost:3000/api.

We could also use Swagger instead of Insomnia to test our API. By clicking on the "Try it out" button that appears under each endpoint on the Swagger web page, we can see if they are working as expected.

Exception filter

Exception filters give us full control over the exceptions layer of NestJS. We can use an exception filter to add custom fields to a HTTP exception response body or to print out logs of every HTTP exception that occurs to the Terminal.

Let's create a new filters folder in the /src folder, as well as a new file called http-exception.filter.ts within it. Let's add the following class in this file.

import { ExceptionFilter, Catch, ArgumentsHost, HttpException, Logger } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HttpExceptionFilter.name);

  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const statusCode = exception.getStatus();
    const message = exception.message || null;

    const body = {
      statusCode,
      message,      
      timestamp: new Date().toISOString(),
      endpoint: request.url,
    };

    this.logger.warn(`${statusCode} ${message}`);

    response
      .status(statusCode)
      .json(body);
  }
}

This class makes use of the NestJS logger to print a warning message to the Terminal whenever a HTTP exception occurs. It also returns two custom fields within the response body whenever a HTTP exception occurs. The timestamp field reports when the exception occurred, and the endpoint field reports which route triggered the exception.

In order to apply this filter, we need to decorate the PostsController with @UseFilters(new HttpExceptionFilter()).

@Controller('posts')
@UseFilters(new HttpExceptionFilter())
export class PostsController {
  constructor(private readonly postsService: PostsService) {}
}

After saving these changes, NestJS will reload our application for us. If we use Insomnia to send a PUT /posts/1 request to our API, it should trigger a 404 NOT FOUND HTTP error, since no blog posts exist for updating in our application when it starts. The HTTP exception response body that is returned to Insomnia should now contain the timestamp and endpoint fields.

{
  "statusCode": 404,
  "message": "Post not found.",
  "timestamp": "2021-08-23T21:05:29.497Z",
  "endpoint": "/posts/1"
}

We should also see the following line printed out to the Terminal.

WARN [HttpExceptionFilter] 404 Post not found.

Summary

In this article, we saw how NestJS makes back-end API development fast, simple, and effective. The NestJS application structure has helped us build a very well-organized project.

We covered a lot, so let's recap what we learned:

How to use the NestJS CLI.
How to build feature modules in NestJS.
How to use services and controllers.
How to test an API with Insomnia.
How to add logging to NestJS apps.
How to use Swagger for documenting and previewing NestJS APIs.
How to get full control of HTTP exceptions in NestJS.

Happy developing with NestJS!

Code

Visit the following GitHub repository in order to access the code featured in this article.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Steven Spadotto

@stevenspads @stevenspads

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes Introduction: Next.js, a powerful React framework, offers two essential features - Parallel Routes and Intercepting Routes - that enable developers to create highly dynamic and seamless user experiences in their applications. In this blog post, we will explore both Parallel Routes and Intercepting Routes, highlighting their functionalities, use cases, and how they can be combined to enhance application routing. What are Parallel Routes? Parallel Routes in Next.js allow the rendering of multiple pages within a shared layout. Rather than navigating to a completely separate page, Parallel Routes enable the simultaneous rendering of different pages based on certain conditions such as user roles or tab navigation. By leveraging named slots, defined using the @folder convention, multiple pages can be seamlessly integrated into a single layout, enhancing user experience and reducing code duplication. How to Use Parallel Routes: To utilize Parallel Routes in Next.js, you must define named slots for the desired pages within your application's folder structure. These slots are then passed as props to a shared parent layout component. For example, consider a social networking application where two pages, feed and notifications, must be rendered within a common layout. You can define Parallel Routes using the following structure: ` The layout component in app/layout.js will accept the @feed and @notifications slots as props and render them alongside the children prop. Here's an example of the layout component: ` It's important to note that slots do not affect the URL structure and are not considered route segments. This means the URL would be /mypage/@feed/views for a route like /mypage/views since @feed is a slot. Also, to prevent the application from rendering nothing or throwing an error, we could use the default.tsx file: ` In this example, the default.tsx file specifies the default content (or fallback) to render when none of the named slots match the current route. It acts as a catch-all for routes without a corresponding slot. Some Use Cases: *Conditional Routes:* Parallel Routes can conditionally render routes based on certain conditions, such as user roles. For example, you can render a different dashboard page for admins and users. This can be achieved by creating a layout component specific to the dashboard and checking the user role to determine which slot to render. *Tab Groups:* You can utilize Parallel Routes to create tabbed navigation within a section. This is especially useful for analytics or multi-page views. Adding a layout inside a slot allows users to navigate between different pages within that slot independently. *Loading and Error UI:* Parallel Routes can be independently streamed, allowing you to define custom error and loading states for each route. This enables better control over the user experience by providing distinct feedback for different app sections. *Modals:* Parallel Routes can be combined with Intercepting Routes to create modals with shareable URLs, preserved context on refresh, and customized navigation behavior. By intercepting certain routes and rendering them within a modal component, you can create a seamless modal experience. Understanding Intercepting Routes: Intercepting Routes in Next.js allows you to load content from another route within the current layout without changing the URL or refreshing the page. Using the (..) Convention: Intercepting routes are defined using the (..) convention, which is similar to the relative path convention ../ but for route segments. The convention allows for matching segments on the same level (.), one level above (..), two levels above (..)(..), or from the root app directory (...). For example, to intercept the photo segment from within the feed segment, you can create a (..)photo directory. Integrating Intercepting Routes with Parallel Routes - Modals: One powerful use case for Intercepting Routes is creating modals, which can be combined with Parallel Routes to solve common challenges such as making the modal content shareable through a URL, preserving context on page refresh, and handling backward and forward navigation. Let's make an example: ` Our folder structure will be: In this example, when a user clicks on a photo within the /gallery page, the route /photo/:photoId will be intercepted and rendered within the (..)photo directory, overlaying the gallery content. This means that the photo route is only one segment level higher despite being two file-system levels higher. In the example above, the path to the photo segment can use the (..) matcher since @modal is a slot and not a segment. Common Use Cases - Beyond Modals: Intercepting Routes can also be utilized in other scenarios. Some examples include opening a login modal in a top navbar while having a dedicated /login page, or opening a shopping cart in a side modal for better accessibility or creating wizards or multi-step forms within a single page. The possibilities are endless. Conclusion Next.js Parallel and Intercepting Routes offer powerful methods for enhancing the routing capabilities of your applications. With Parallel Routes, multiple pages can be seamlessly integrated within a shared layout, simplifying navigation and enhancing user experience. By incorporating Intercepting Routes, you can create dynamic overlays like modals, enabling content from different routes to be displayed within the current layout. By leveraging these features, you can unlock exciting possibilities and take your Next.js applications to new heights of user engagement....

Apr 5, 2024

3 mins

NextJSJavaScript

Overview of the New Signal APIs in Angular

Overview of the New Signal APIs in Angular Google's Minko Gechev and Jeremy Elbourn announced many exciting things at NG Conf 2024. Among them is the addition of several new signal-based APIs. They are already in developer preview, so we can play around with them. Let's dig into it, starting with signal-based inputs and the new matching outputs API. Signal Based Inputs Discussions about signal-based inputs have been taking place in the Angular community for some time now, and they are finally here. Until now, you used the @Input() decorator to define inputs. This is what you'd have to write in your component to declare an optional and a required input: ` With the new signal-based inputs, you can write much less boilerplate code. Here is how you can define the same inputs using the new syntax: ` It's not only less boilerplate, but because the values are signals, you can also use them directly in computed signals and effects. That, effectively, means you get to avoid computing combined values in ngOnChanges or using setters for your inputs to be able to compute derived values. In addition, input signals are read-only. The New Output I intentionally avoid calling them signal-based outputs because they are not. They still work the same way as the old outputs. The Angular team has just introduced a new output API that is more consistent with the latest inputs API and allows you to write less boilerplate, similar to the new input API. Here is how you would define an output until now: ` Here is how you can define the same output using the new syntax: ` The thing I like about the new output API is that sometimes it happens to me that I forget to instantiate the EventEmitter because I do this instead: ` You won't forget to instantiate the output with the new syntax because the output function does it for you. Signal Queries I am sure most readers know the @ViewChild, @ViewChildren, @ContentChild, and @ContentChildren decorators very well and have experienced the pain of triggering the infamous ExpressionChangedAfterItHasBeenCheckedError or having the values unavailable when needed. Here is a refresher on how you would use these decorators until now: ` With the new signal queries, similar to the new input API, the values are signals, and you can use them directly in computed signals and effects. You can define the same queries using the new syntax: ` Jeremy Elbourn mentioned that the new signal queries have better type inference and are more consistent with the new input and output APIs. He also showcased a brand new feature not available with the old queries. You can now define a query as required, and the Angular compiler will throw an error if the query has no result, guaranteeing that the value won't be undefined. Here is how you can define a required query: ` Model Inputs Jeremy and Minko announced the last new feature is the model inputs. The name is vague, but the feature is cool—it simplifies the definition of two-way bindings. Until now, to achieve two-way binding, you would have to define an input and an output following a given naming convention. @Input and @Output had to be defined with the same name (followed by "Change" in the case of the output). Then, you could use the template's [()] syntax. ` ` That way, you could keep the value in sync between the parent and the child component. With the new model inputs, you can define a two-way binding with a single line of code. Here is how you can define the same two-way binding using the new syntax: ` The html template stays the same: ` The model function returns a writable signal that can be updated directly. The value will be propagated back to any two-way bindings. Conclusion The new signal-based APIs are a great addition to Angular. They allow you to write less boilerplate code and make your components more reactive. The new APIs are already in developer preview, so you can start playing around with them today. I look forward to seeing how the community will adopt these new features and what other exciting things the Angular team has in store for us, such as zoneless apps by default....

Apr 3, 2024

3 mins

AngularJavaScript

Next.js Conf 2021 Highlights

Given how well-presented it was, it's hard to believe that Next.js Conf 2021 was only the second edition of Vercel's Next.js Conf. Vercel is the creator of the industry-leading React and JavaScript framework for full-stack web development called Next.js. This year also marked a milestone birthday celebration for Next.js as it turned 5 years old. Guillermo Rauch, CEO of Vercel and co-creator of Next.js, started off the conference with a keynote talk. Guillermo announced Next.js version 12, the biggest release ever. Guillermo highlighted the following features of Next.js 12. A new Rust-based compiler Next.js 12 uses a Rust compiler built with SWC, which stands for Speedy Web Compiler. It's an open platform for fast tooling. This compiler improves both local and production environments. This new Rust-based compiler achieves around 5 times faster builds and around 3 times faster Hot Module Replacement (or HMR). Zero code updates are required to benefit from these improvements. Simply update your Next.js app to version 12 to begin enjoying the benefits of this new compiler. ES Modules Next.js 11.1 added experimental support for ES modules. In Next.js 12, ES modules are now the default. ES modules are the official, standardized module system for JavaScript. They are supported by all major browsers and Node.js. This standardized module system allows for smaller package sizes. URL Imports Next.js 12 includes experimental support for URL Imports. This allows developers to use any package directly via a URL. There is no install or build step required. Remote resources can be processed exactly like local dependencies. Middleware & Edge Functions Over the past few years, Next.js has provided tremendous support for serverless deployments, thereby eliminating the DevOps burden for developers. Next.js continued on this mission by introducing *middleware* and *edge functions* on Vercel serverless deployments. Middleware Next.js middleware allow developers to run code before a request is completed. The response to an incoming request can be modified by rewriting, redirecting, adding headers, or streaming HTML. This allows middleware to be used for things like authentication, feature flags, A/B testing, logging, server-side analytics, and more. Next.js middleware provide the same flexibility on serverless platforms that is available with traditional web servers. Next.js middleware support Web APIs like fetch and they work out of the box in Next.js 12, or deployed as edge functions on Vercel. Edge functions Edge functions allow developers to run code close to their users. Vercel now supports edge functions for all users on their platform. It's important to note that other hosting providers can also be configured to support middleware at the edge, and not just Vercel. Multi-region deployment is often avoided due to cost and complexity. With edge functions, server-side logic can now be moved to the Edge, close to the geographic location of the website visitor. This results in improved loading times for visitors, no matter where they visit from. As developers, we typically serve dynamic content for visitor personalization reasons and serve static content for faster load times. However, with a Next.js middleware deployed as an edge function, dynamic content can be served at the speed of static content. Edge functions help to solve the common issues with serverless deployments because they boot up instantly, deploy globally, and support streaming data. The future of React Next.js 12 brings the future of React to Next.js. It includes experimental support for React 18 and React server components. It was reassuring to hear how closely Next.js is working with the React team to prepare Next.js for React 18, server-side streaming, and React server components. React server components React server components allow individual components to be rendered on the server-side. It's different from *Server-Side Rendering (SSR)*, which pre-generates the HTML of an entire web page on the server. Server-Side Rendering renders all the HTML on the page or nothing at all. With React server components, a web page can progressively update at the component level as data comes in. With React server components, data fetching can be done at the component level. This simplifies things, because getServerSideProps and getStaticProps will no longer be needed. This aligns more closely to the React hooks model, which advocates for combining data fetching with components. Using server components React server components can be used in Next.js 12 with an experimental flag. To try out React server components, we can simply give any page a .server.js or .server.ts suffix. Client-side rendered components can be used within the server component. These client components will hydrate and become interactive when the server component is rendered. This can be useful for adding client-side functionality to a page, like upvoting and downvoting behaviors. Benefits of server components React server components require no client-side JavaScript and they improve page rendering speeds, as well as the user experience. React server components provide greater flexibility, allowing the developer to choose where a component renders, either on the client or on the server. Granular component caching The Next.js team showcased a new exploration that is currently underway using a new Data component that works like a React suspense boundary. This new component supports granular component caching. It's similar to *Incremental Static Regeneration (ISR)*. Next.js Analytics Last year, Next.js announced Next.js Analytics to help monitor web vitals. Since then, it has seen amazing adoption, processing over 7 billion data points. This year, Next.js announced Checks, automated performance checks that start automatically and report results when a deployment finishes. A preview deployment is checked to ensure that there are no runtime errors and that good performance makes its way into production. This is all thanks to the end-to-end reliability checks and *Web Vitals* performance checks that are done. Next.js Live During the conference, we learned about the evolution of Next.js Live, which was presented at last year's Next.js Conf. Next.js Live provides an instant development and real-time collaboration experience for Next.js. All it takes to collaborate with Next.js Live is a link. Next.js Live makes it possible to code, chat, draw, and edit, directly from a web browser. Next.js Live now provides new Git integrations. Next.js Live runs natively in web browsers, and now boots up instantly thanks to innovations like ES Modules and Web Assembly, which the new compiler takes advantage of. Notable Talks Next.js 12 Overview Developer Experience of the Future by Lee Robinson. Learn more about the features included in Next.js 12. Edge functions Next.js at the Edge by Suzanne Aldrich and Lee Robinson. Learn more about Edge functions with Next.js and Vercel. Edge Functions Explained by Kelsey Hightower and Lee Robinson. See a demo of edge functions and learn how they're different from the traditional way of building for the web. Next.js and databases Next.js and Prisma: Databases in Serverless Made Easy by Daniel Norman. Learn how Prisma makes building database-driven applications with Next.js a breeze. Streaming Streaming in Next.js by Kara Erickson. Learn about the benefits of streaming with Next.js. Getting Started Getting Started with Next.js by Delba de Oliveira. Learn the fundamentals of React and Next.js. All Talks To view all the talks that were part of Next.js Conf 2021, visit the Vercel YouTube page....

Nov 18, 2021

6 mins

JavaScriptNodeJSNextJS

End-to-end type-safety with JSON Schema

End-to-end type-safety with JSON Schema I recently wrote an introduction to JSON Schema post. If you’re unfamiliar with it, check out the post, but TLDR: It’s a schema specification that can be used to define the input and output data for your JSON API. In my post, I highlight many fantastic benefits you can reap from defining schemas for your JSON API. One of the more interesting things you can achieve with your schemas is end-to-end type safety from your backend API to your client application(s). In this post, we will explore how this can be accomplished slightly deeper. Overview The basic idea of what we want to achieve is: * a JSON API server that validates input and output data using JSON Schema * The JSON Schema definitions that our API uses transformed into TypeScript types With those pieces in place, we can achieve type safety on our API server and the consuming client application. The server side is pretty straightforward if you’re using a server like Fastify with already enabled JSON Schema support. This post will focus on the concepts more than the actual implementation details though. Here’s a simple diagram illustrating the high-level concept: We can share the schema and type declaration between the client and server. In that case, we can make a request to an endpoint where we know its type and schema, and assuming the server validates the data against the schema before sending it back to the client, our client can be confident about the type of the response data. Marrying JSON Schema and TypeScript There are a couple of different ways to accomplish this: * Generating types from schema definitions using code generation tools * Creating TypeBox definitions that can infer TypeScript types and be compiled to JSON Schema I recommend considering both and figuring out which would better fit your application and workflows. Like anything else, each has its own set of trade-offs. In my experience, I’ve found TypeBox to be the most compelling if you want to go deep with this pattern. Code generation A couple of different packages are available for generating TS types from JSON Schema definitions. * https://github.com/bcherny/json-schema-to-typescript * https://github.com/vega/ts-json-schema-generator They are CLI tools that you can provide a glob path to where your schema files are located and will generate TS declaration files to a specified output path. You can set up an npm hook or a similar type of script that will generate types for your development environment. TypeBox TypeBox is a JSON Schema type builder. With this approach, instead of json files, we define schemas in code using the TypeBox API. The TypeBox definitions infer to TypeScript types directly, which eliminates the code generation step described above. Here’s a simple example from the documentation of a JSON Schema definition declared with TypeBox: ` This can then be inferred as a TypeScript type: ` Aside from schemas and types, TypeBox can do a lot more to help us on our type-safety journey. We will explore it a bit more in upcoming sections. Sharing schemas between client and server applications Sharing our JSON Schema between our server and client app is the main requirement for end-to-end type-safety. There are a couple of different ways to accomplish this, but the simplest would be to set up our codebase as a monorepo that contains both the server and client app. Some popular options for TypeScript monorepos are: PNPM, Turborepo, and NX. If a monorepo is not an option, you can publish your schema and types as a package that can be installed in both projects. However, this setup would require a lot more maintenance work. Ultimately, as long as you can import your schemas and types from the client and server app, you are in good shape. Server-to-client validation and type-safety For the sake of simplicity, let's focus on data flowing from the server to the client for now. Generally speaking, the concepts also apply in reverse, as long as your JSON API server validates your inputs and outputs. We’ll look at the most basic version of having strongly typed data on the client from a request to our server. Type-safe client requests In our server application, if we validate the /users endpoint with a shared schema - on the client side, when we make the request to the endpoint, we know that the response data is validated using the user schema. As long as we are confident of this fact, we can use the generated type from that schema as the return type on our client fetch call. Here’s some pseudocode: ` Our server endpoint would look something like this: ` You could get creative and build out a map that defines all of your endpoints, their metadata, and schemas, and use the map to define your server endpoints and create an API client. Transforming data over the wire Everything looks stellar, but we can still take our efforts a bit further. To this point, we are still limited to serialized JSON data. If we have a created_at field (number or ISO string) tied to our user, and we want it to be a Date object when we get a hold of it on the client side - additional work and consideration are required. There are some different strategies out there for deserializing JSON data. The great thing about having shared schemas between our client and server is that we can encode our type information in the schema without sending additional metadata from our server to the client. Using format to declare type data In my initial JSON Schema blog post, I touched on the format field of the specification. In our schema, if the actual type of our date is a string in ISO8601 format, we can declare our format to be "date-time". We can use this information on the client to transform the field into a proper Date object. ` Transforming serialized JSON Data This can be a little bit tricky; again, there are many ways to accomplish it. To demonstrate the concept, we’ll use TypeBox to define our schemas as discussed above. TypeBox provides a Transform type that you can use to declare, encode, and decode methods for your schema definition. ` It even provides helpers to statically generate the decoded and encoded types for your schema ` If you declare your decode and encode functions for your schemas, you can then use the TypeBox API to handle decoding the serialized values returned from your JSON API. Here’s what the concept looks like in practice fetching a user from our API: ` Nice. You could use a validation library like Zod to achieve a similar result but here we aren’t actually doing any validation on our client side. That happened on the server. We just know the types based on the schema since both ends share them. On the client, we are just transforming our serialized JSON into what we want it to be in our client application. Summary There are a lot of pieces in play to accomplish end-to-end type safety. With the help of JSON Schema and TypeBox though, it feels like light work for a semi-roll-your-own type of solution. Another great thing about it is that it’s flexible and based on pretty core concepts like a JSON API paired with a TypeScript-based client application. The number of benefits that you can reap from defining JSON Schemas for your APIs is really great. If you’re like me and wanna keep it simple by avoiding GraphQL or other similar tools, this is a great approach....

Apr 17, 2024

6 mins

JSONTypeScript