Javascript

Introduction to LoopBack

Published Aug 4, 2021

Updated Feb 14, 2023

8 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

When one wants to implement a Node.js-based backend API, the first framework that usually comes to mind is Express. This is, perhaps, the most popular web framework for Node.js. This framework is also usually the top choice for demonstration purposes such as proof of concepts, or tutorials, which further contributes to its popularity. A framework such as LoopBack is usually not the first option, even though this is a relatively mature and stable framework, and backed by an IBM company called StrongLoop.

As part of this blog post, we'll demonstrate the basic functionalities of LoopBack by building a small REST API.

Features at a Glance

LoopBack uses Express under the hood, but there are several noticeable features that make LoopBack stand out from other API frameworks:

First-Class Support for TypeScript If you like TypeScript, then you'll definitely want to consider LoopBack. It can be a great companion to other TypeScript-based frameworks such as Angular, as frontend and backend teams will use the same programming language for the entire stack.
OpenAPI-Driven APIs The OpenAPI standard is becoming widely adopted, and LoopBack makes it easy to create OpenAPI-based REST APIs.
Great CLI Tool LoopBack comes with its CLI tool, which is great for scaffolding initial projects, or generating additional code. Many can get a project running within minutes.
Loads of Connectors There are numerous connectors written for LoopBack, from REST/SOAP connectors, to database connectors for relational and NoSQL databases. This way, you can easily integrate your application with other APIs without much custom code.
Dependency Injection LoopBack has a DI-based context at its core, allowing for writing loosely coupled code. Your components declare dependencies on other components, and it's up to LoopBack to wire them up.

Getting Started

Now that we know what LoopBack is about, let's try to implement an application that will demonstrate the usage of two common functionalities that most API backends have, such as saving to a database, and invoking an external API. For this purpose, we'll build a small application that acts like a proxy towards the GitHub issue API, but with local caching. It will expose an endpoint where you can fetch a specific issue, and then this issue will be fetched from the local cache, or from GitHub if it's not cached.

Scaffolding the Project

To start off, install the LoopBack CLI which is used to scaffold projects quickly:

$ npm install -g @loopback/cli

Now that you have the CLI installed, start by scaffolding your application:

$ lb4 loopback-demo

The CLI tool will ask you a couple of questions about the project, and allow you to select which features you will be using. Let's select all features, for now, just to see everything that you can get out of the box:

? Project description: Demonstration of basic features of LoopBack.
? Project root directory: LoopBackDemoApplication
? Application class name: LoopbackDemoApplication
? Select features to enable in the project (Press <space> to select, <a> to toggle all, <i> to invert selection)
>(*) Enable eslint: add a linter with pre-configured lint rules
 (*) Enable prettier: install prettier to format code conforming to rules
 (*) Enable mocha: install mocha to run tests
 (*) Enable loopbackBuild: use @loopback/build helpers (e.g. lb-eslint)
 (*) Enable vscode: add VSCode config files
 (*) Enable docker: include Dockerfile and .dockerignore
 (*) Enable repositories: include repository imports and RepositoryMixin

At this point, we already have the application running with a sample REST endpoint, but let's do a couple of additional steps first that will make our development easier. At the moment, the LoopBack starter project does not come with a hot restart functionality, so let's add that first:

$ npm install -D tsc-watch

Then add this line under your "scripts" tag in package.json:

"start:watch": "tsc-watch --target es2017 --outDir ./dist --onSuccess \"node .\"",

LoopBack does not output many logs by default, unfortunately. Log output is controlled via the DEBUG environment variable, which determines the scope of the logs. To set this variable in a cross-platform manner and output some useful logs, we will use cross-env:

npm install -D cross-env

Now, add the following command, which adds some basic logging to standard out:

"start:watch:debug": "cross-env DEBUG=loopback:connector:*,loopback:rest:* npm run start:watch",

Running the Project

Running the project is now easy- simply execute npm run start:watch:debug, and the application process will automatically restart on every code change. Open http://localhost:3000/ping in your browser, and you should see something like this:

{"greeting":"Hello from LoopBack4","date":"2021-07-23T13:33:28.014Z","url":"/ping","headers":{"host":"localhost:3000","connection":"keep-alive","cache-control":"max-age=0","sec-ch-ua":"\"Chromium\";v=\"92\", \" Not A;Brand\";v=\"99\", \"Google Chrome\";v=\"92\"","sec-ch-ua-mobile":"?0","upgrade-insecure-requests":"1","user-agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.107 Safari/537.36","accept":"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9","sec-fetch-site":"none","sec-fetch-mode":"navigate","sec-fetch-user":"?1","sec-fetch-dest":"document","accept-encoding":"gzip, deflate, br","accept-language":"en-US,en;q=0.9"}}

That's it! You now have a LoopBack application running at http://localhost:3000/.

Project Structure

The project is organized into several layers, where each layer has its own subdirectory within the root project tree. The first layer that you'll probably notice, and the first layer that you reached by executing the GET request in the previous chapter, is the controllers layer. A controller is where you would implement your API endpoint, and place your business logic. The controller will authenticate the incoming request, parse and validate the request, as well as orchestrate calls to services and repositories. There are no services in the starter project, but services provide you with interfaces to invoke local and remote operations. Repositories, on the other hand, handle all CRUD operations on your models, which represent domain objects.

LoopBack comes with dependency-injection (DI) out of the box, and components such as controllers, services, and repositories are registered automatically to the DI context. There's no need to wire them up manually. In fact, they are detected automatically when the application is booted.

Developing Our Cache Application

The cache will have the following flow:

A GET request is sent to /issues to retrieve a GitHub issue.
This will look in the internal cache if issue already exists.
- If exists, it will return the cached issue.
- If not, it will retrieve the relevant issue from GitHub using GitHub's REST API, and cache it locally.

For the actual cache, we'll use an in-memory database, which is persisted to disk.

Implementing Basic Controller

To start, we can implement just a basic controller that will accept a request and reflect it back in the response. First, use the lb4 model command to create a CachedIssue model, an instance of which will be a response from the controller. When creating a new model, the CLI tool will typically ask you whether you want to create an instance of a Model, or an instance of an Entity. The difference between the two is that an Entity is saved to a database (therefore it must have a unique ID), while a Model is typically not saved to a database, and can be used for data transfer objects (DTOs) on the API level.

Our CachedIssue will eventually be saved to our database (cache), so we'll choose the Entity option, with the following properties:

issueNumber: number
repositoryOwner: string
repositoryName: string
title: string
reporter: string
state: string

Once the model is created, now we can generate a controller that will use it. Execute the lb4 controller command to generate an empty controller. Implement the following endpoint in the controller:

import {get, getModelSchemaRef, param} from '@loopback/rest';
import {CachedIssue} from '../models';

export class IssueController {
  constructor() {}

  @get('/issues/{repositoryOwner}/{repositoryName}/{issueNumber}', {
    responses: {
      '200': {
        content: {
          'application/json': {
            schema: getModelSchemaRef(CachedIssue),
          },
        },
      },
    },
  })
  async getIssue(
    @param.path.string('repositoryOwner') repositoryOwner: string,
    @param.path.string('repositoryName') repositoryName: string,
    @param.path.number('issueNumber') issueNumber: number,
  ): Promise<CachedIssue> {
    return {
      issueNumber: issueNumber,
      repositoryOwner: repositoryOwner,
      repositoryName: repositoryName,
    } as CachedIssue;
  }
}

It's a simple controller that accepts three properties, specified using the @param annotation, and reflects them back in the response, just to verify that it's working. Even on this simple example, you can see one of the benefits that LoopBack gives you out of the box, and that is a validation of requests. For example, if you send a request that doesn't conform the request specification, LoopBack will throw an error, and inform why the validation failed.

Now execute a GET request towards http://localhost:3000/issues/strongloop/loopback/1553 - this should return an instance of CachedIssue, containing the following properties:

{"issueNumber":1553,"repositoryOwner":"strongloop","repositoryName":"loopback"}

At this point, we have a functioning controller.

Integrating with GitHub

To integrate with an external API, we need to generate two things: a datasource and a service.

Generate a datasource using the command lb4 datasource, name it GitHubApi, and use the REST services connector. This will place the datasource configuration in the git-hub-api.datasource.ts, and LoopBack will use this file to auto-configure the datasource on startup. Be sure to place the following configuration in the datasource after it has been generated.

const config = {
  name: 'GitHubApi',
  connector: 'rest',
  options: {
    headers: {
      accept: 'application/json',
      'content-type': 'application/json',
      'User-Agent': 'LoopBack', // GitHub API requires User-Agent header
    },
  },
  operations: [
    {
      template: {
        method: 'GET',
        url: 'https://api.github.com/repos/{repositoryOwner}/{repositoryName}/issues/{issueNumber}',
      },
      functions: {
        // The service that uses this datasource will need to have these functions in its interface
        getIssue: ['repositoryOwner', 'repositoryName', 'issueNumber'],
      },
    },
  ],
};

This configuration specifies general configuration of the connector (such as the user agent used), however it also specifies the operations that we will expose internally towards the controllers, the GitHub API URL for each operation, and parameters for each operation. There is plenty of other configuration properties for the REST connector, but we'll keep it simple for the purposes of this tutorial.

Controllers normally access datasources through services, and the next step is to generate a service. Use the lb4 service command to generate a service named "GitHubApi". Choose the Remote service proxy backed by a data source option and choose the GitHubApiDatasource datasource. Once the service is generated, create an interface that will match the operations specified in the configuration of the REST connector:

import {inject, Provider} from '@loopback/core';
import {getService} from '@loopback/service-proxy';
import {GitHubApiDataSource} from '../datasources';

/**
 * This class is used for representing the response from GitHub API. Only a subset of returned properties is used.
 */
export class GitHubIssueResponse {
  'number': number;
  title: string;
  user: {login: string};
  state: string;
}

/**
 * When other components want to use this service, they declare dependency on the following interface.
 */
export interface GitHubApi {
  getIssue(
    repositoryOwner: string,
    repositoryName: string,
    issueNumber: number,
  ): Promise<GitHubIssueResponse>;
}

export class GitHubApiProvider implements Provider<GitHubApi> {
  constructor(
    // GitHubApi must match the name property in the datasource json file
    @inject('datasources.GitHubApi')
    protected dataSource: GitHubApiDataSource = new GitHubApiDataSource(),
  ) {}

  value(): Promise<GitHubApi> {
    return getService(this.dataSource);
  }
}

Here, we used GitHubIssueResponse to define the properties that are read from the GitHub API. GitHub API returns numerous properties in the response, but we'll only use a few properties for simplicity. LoopBack will automatically parse GitHub API's response, and instantiate an object of GitHubIssueResponse with the properties that we need.

Notice also how we declared a dependency on GitHubApiDataSource in the constructor. This is LoopBack's dependency injection mechanism at work - we only declare the dependency through @inject annotation, and LoopBack's DI container is responsible for injecting an instance of GitHubApiDataSource during bootstrap.

Saving Issues to Local Database

Our cache would not work without having some local storage. LoopBack has a variety of database connectors, but we'll go with the most simple one: an in-memory database which is persisted to a JSON file on the local disk. Run the lb4 datasource command, name the datasource "FileDb" and use the In-memory db connector with data/db.json as the full path for file persistence. Config of the generated datasource should look like this:

const config = {
  name: 'FileDb',
  connector: 'memory',
  localStorage: '',
  file: './data/db.json' // Make sure the file exists!
};

As you can see, the configuration for an in-memory database is quite simple when compared to the configuration of the REST connector that we configured earlier. One thing to note here is that LoopBack expects the file ./data/db.json to exists on the filesystem. Be sure to create it before starting the application (it can be empty).

The controller will access this datasource through a service, but not just any service. For CRUD operations, we use a specialized service called a repository. Repositories provide strong-typed data access operations of a domain model against the underlying database or service. Before we create a repository, we need a model to persist first. Execute lb4 model, and choose Entity model this time, since it will be persisted to the database.

import {Entity, model, property} from '@loopback/repository';

/**
 * This model represents the issue that is persisted to local database.
 */
@model()
export class CachedIssue extends Entity {
  @property({
    type: 'number',
    id: true,
    generated: false,
    required: true,
  })
  issueNumber: number;

  @property({
    type: 'string',
    required: true,
  })
  repositoryOwner: string;

  @property({
    type: 'string',
    required: true,
  })
  repositoryName: string;

  @property({
    type: 'string',
    required: true,
  })
  title: string;

  @property({
    type: 'string',
    required: true,
  })
  reporter: string;

  @property({
    type: 'string',
    required: true,
  })
  state: string;

  constructor(data?: Partial<CachedIssue>) {
    super(data);
  }
}

export interface CachedIssueRelations {
  // describe navigational properties here
}

export type IssueWithRelations = CachedIssue & CachedIssueRelations;
tions {
  // describe navigational properties here
}

export type IssueWithRelations = Issue & IssueRelations;

Use the lb4 repository command to generate a repository using the FileDbDatasource datasource and the CachedIssue model:

import {inject} from '@loopback/core';
import {DefaultCrudRepository} from '@loopback/repository';
import {FileDbDataSource} from '../datasources';
import {CachedIssue, IssueRelations} from '../models';

export class IssueRepository extends DefaultCrudRepository<
  CachedIssue,
  typeof CachedIssue.prototype.issueNumber,
  IssueRelations
> {
  constructor(@inject('datasources.FileDb') dataSource: FileDbDataSource) {
    super(CachedIssue, dataSource);
  }
}
import {inject} from '@loopback/core';
import {DefaultCrudRepository} from '@loopback/repository';
import {FileDbDataSource} from '../datasources';
import {Issue, IssueRelations} from '../models';

export class IssueRepository extends DefaultCrudRepository<
  Issue,
  typeof Issue.prototype.issueNumber,
  IssueRelations
> {
  constructor(
    @inject('datasources.FileDb') dataSource: FileDbDataSource,
  ) {
    super(Issue, dataSource);
  }
}

Putting It All Together

With all the integrations in place, we can now finalize the controller and add some business logic to it. The controller should read parameters from the request, propagate them to GitHub API, and read GitHub API's response, which is represented by an instance of GitHubIssueResponse object. Once it has this object, it uses the issue number as a primary key to see if the issue has already been persisted to the database. If it has, the controller will return the cached issue, otherwise it will fetch it from GitHub before returning it.

import {get, getModelSchemaRef, HttpErrors, param} from '@loopback/rest';
import {CachedIssue} from '../models';
import {inject} from '@loopback/core';
import {GitHubApi} from '../services';
import {repository} from '@loopback/repository';
import {IssueRepository} from '../repositories';

export class IssueController {
  constructor(
    @inject('services.GitHubApi')
    protected gitHubApiService: GitHubApi,
    @repository(IssueRepository)
    public issueRepository: IssueRepository,
  ) {}

  @get('/issues/{repositoryOwner}/{repositoryName}/{issueNumber}', {
    responses: {
      '200': {
        content: {
          'application/json': {
            schema: getModelSchemaRef(CachedIssue),
          },
        },
      },
    },
  })
  async getIssue(
    @param.path.string('repositoryOwner') repositoryOwner: string,
    @param.path.string('repositoryName') repositoryName: string,
    @param.path.number('issueNumber') issueNumber: number,
  ): Promise<CachedIssue> {
    try {
      // This method will return saved entity if exists, otherwise it will raise ENTITY_NOT_FOUND error
      return await this.issueRepository.findById(issueNumber);
    } catch (e) {
      if (e.code === 'ENTITY_NOT_FOUND') {
        const issueResponse = await this.gitHubApiService.getIssue(
          repositoryOwner,
          repositoryName,
          issueNumber,
        );

        const newIssueEntity = new CachedIssue();
        newIssueEntity.issueNumber = issueResponse.number;
        newIssueEntity.title = issueResponse.title;
        newIssueEntity.reporter = issueResponse.user?.login;
        newIssueEntity.state = issueResponse.state;
        newIssueEntity.repositoryName = repositoryName;
        newIssueEntity.repositoryOwner = repositoryOwner;

        return this.issueRepository.create(newIssueEntity);
      } else {
        throw new HttpErrors.InternalServerError(
          `Error while looking up issue #${issueNumber} in the database`,
        );
      }
    }
  }
}

We now have a fully functioning application. You can try re-sending the GET request from earlier, and verify that it is persisted to ./data/db.json. Of course, we're still missing some important cache features such as eviction of unused data, but we'll leave it to you to implement in case you'd like to play with the framework further.

We hope you enjoyed this brief intro to LoopBack, and perhaps you'll even consider it for your next project. LoopBack has many other functionalities and built-in connectors, but as part of this tutorial, we focused on the common ones: creating a simple API, invoking an external API, and using a database. The complete project is available on GitHub in case you'd like to check it out.

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.

About the author(s)

Dario Djuric
Dario is a full-stack engineer who has spent most of his career doing enterprise Java projects. He has always had a hidden passion for frontend, though -- and he is now able to pursue that passion at This Dot. He spends most of his free time with his two sons, but occasionally, he manages to squeeze in some casual sports activities such as jogging, cycling, and soccer.
@dario_djuric @dariodjuric

Learning Paths for Next.JS Developers with Ankita Kulkarni

In this video, Rob Ocel and co-hosts Tracy Lee, Adam Rackis, and Danny Thompson talk with tech educator Ankita Kulkarni about her journey from engineering leader to full-time educator. Ankita shares insights on teaching Next.js, bridging practical knowledge gaps, and helping developers tackle real-world challenges. They discuss Next.js as a React-based framework, its benefits, and the challenges it presents for beginners. Chapters - Introduction to the Podcast and Guests 00:01 - Meet Ankita Kulkarni, Tech Educator 00:26 - Ankita's Transition to Full-Time Education 01:41 - Teaching Practical Knowledge in Next.js 03:19 - Effective Methods for Teaching Next.js 05:27 - Challenges of Being a Full-Time Educator 07:48 - Balancing Broad and Specific Examples 09:54 - Embracing Mistakes as a Teaching Tool 12:13 - Pair Programming and Mentorship 14:00 - Discussion on Next.js and Framework Adoption 16:48 - Advantages and Challenges of Next.js 18:12 - Choosing the Right Framework for Your Needs 20:35 - Impact of Next.js in React Documentation 22:26 - Learning Paths for New Developers 23:24 - The Rise of Full-Stack Web Development 25:09 - Benefits of Frameworks Abstracting Complexity 26:27 - OpenNext and Deployment Flexibility 28:06 - Ankita's Excitement for New Next.js Features 30:35 - The Future of Next.js Without Vercel 32:16 - Final Thoughts and Where to Find Everyone Online 34:21 Follow Ankita Kulkarni on Social Media Twitter: https://x.com/kulkarniankita9 YouTube: https://www.youtube.com/@kulkarniankita Sponsored by This Dot: thisdot.co...

Nov 12, 2024

2 mins

NextJSJavaScript

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Integrating Next.js with New Relic

Integrating Next.js with New Relic When it comes to application monitoring, New Relic is genuinely one of the veterans in the market. Founded in 2008, it offers a large set of tools designed for developers to help them analyze application performance, troubleshoot problems, and gain insight into user behavior through real-time analytics. We needed to integrate New Relic's application monitoring with a modern Next.js app built on top of the app router. This blog post will explain your options if you want to do the same in your project. Please keep in mind that depending on when you read this blog post, there may be some advances in how New Relic works with Next.js. You can always refer to the official New Relic website for up-to-date documentation. The approach is also different, depending on whether you use Vercel's managed Next.js hosting (or any other provider that is lambda-based) or self-host Next.js on an alternative provider such as Fly.io. We'll start with the typical steps you need to do for both ways of deploying; then we'll continue with the self-hosted option, which uses a complete set of features from New Relic, and finish with Vercel where we recommend the OpenTelemetry integration for now. Common Prerequisite Steps First, let's install the necessary packages. These were built by New Relic and are needed whether you self-host your Next.js app or host it on Vercel. ` The next thing you'll want to do is define your app name. The name will be different depending on the environment the app is running in, such as a local environment, staging, or production. This will ensure that the data you send to New Relic is always tagged with a proper app name and will not be mixed between environments. An environment-changing parameter, such as the app name, should always be included in an environment variable. In your local environment, that would be in .env.local, while staging/production or any other hosted environments would be configured in the provider. ` To get full coverage with New Relic, in Next.js, we need to cover the parts running on the client (in the browser) and on the server. The server-running part is different on Vercel's managed hosting, where all of the logic is executed within lambdas, and self-hosting variants, where the server logic is executed on a Node.js server. The client part is configured by going to the New Relic dashboard and clicking "Add Data" / "Browser Monitoring". Choose "place a JavaScript snippet in frontend code," name it the same name you used in the environment variable above, click "Continue" to the last step, and copy the part between the script tags: ` Then paste it to a variable inside any module of your code. For example, this is how we did it: ` Now, create a component that will use this script and put it to Next's Script component. Then you can use the component in your root layout: ` There are several things to note here. First, we need to set a unique ID for the Script component for Next.js to track and optimize the script. We also need to set the strategy to beforeInteractive so that the New Relic script is added to the document’s head element. Finally, we use some environment helper variables. IS_PRODUCTION and IS_STAGING are just helper variables that read the environment variables to determine if we are in a local environment, staging, or production. Now you can create an app router error page and report any uncaught errors to New Relic: ` With this in place, the client part is covered, and you should start seeing data in the New Relic dashboard under "All Entities" / "Browser Applications." Let's now focus on the server part, with both a self-hosted option and Vercel. Self-Hosting Next.js If you self-host Next.js, It will typically run through a Node server (containerized or not), meaning you can fully utilize New Relic's APM agent. Start by adding this to the Next.js config (next.config.js) to mark the newrelic package as external, otherwise you would not be able to import it. ` The next step that New Relic recommends is to copy the newrelic.js file from the newrelic library to the root of the folder. However, we want to keep our project root clean, and we'll store the file in o11y/newrelic.js (“o11y” is an abbreviation for observability). This will also demonstrate the configuration needed to make this possible. This file, by default, will look something like this. ` As you can see, some environment variables are involved, such as NEW_RELIC_APP_NAME and NEW_RELIC_LICENSE_KEY. These environment variables will be needed when the New Relic agent starts up. The trick here is that the agent doesn't start up with your app but *earlier* by preloading the library through another environment variable, NODE_OPTIONS. On the server, that would be done by modifying the start script to this: ` This ensures the agent is preloaded before starting the app, and the rest of the environment variables (such as NEW_RELIC_APP_NAME and NEW_RELIC_LICENSE_KEY) should already exist. Making sure this works in local development is not that easy due to different stages of loading environment variables. The environment variables from .env.local are loaded by the framework, which is too late for the New Relic agent (which is preloaded by the Node process). However, it is possible with a trick. First, add the following new environment variables to .env.local: ` (We have not mentioned NEW_RELIC_HOME so far, but the New Relic agent implicitly uses it to locate the newrelic.js file. We need to specify that since we moved it to the o11y folder.) Next, install the nodenv package. ` The nodenv package provides a cross-platform way of preloading environment variables before we start the Node process. If we provide it with the .env.local file, this means all of the environment variables from that file will be available to the New Relic agent! Change the scripts in package.json: ` And that's it. If you now start the local server using the dev command, nodenv will make environment variables available to the Node process. The Node process will preload the New Relic agent (because we have NODE_OPTIONS in .local.env), the agent will read all the environment variables needed by newrelic.js, and everything will work as expected. The first thing you might notice is the creation of the newrelic_agent.log. This is just a log file by the agent which you can use to troubleshoot if the agent is not working correctly. You can safely add this file to .gitignore. From this point on, the server-side part of the app can utilize New Relic's API (such as noticeError and recordLogEvent) and the agent will automatically be recording transactions made through the server. The data should be visible in the New Relic dashboard, under "All Entities" / "Services - APM". This is how you would log an error in your server action, for example: ` The full source of this type of integration is available on StackBlitz. Using Vercel's Managed Next.js Hosting Using the New Relic APM agent on Vercel is currently not possible, as the server part of Next.js runs within lambdas, and not within a typical Node server as in the self-hosted option. In the future, this may be possible. At the moment, the only way to integrate Vercel and New Relic is by using the Vercel OpenTelemetry collector, which is only available for some plans. The first step is to enable the integration in Vercel's dashboard and then install the following packages: ` Create an instrumentation.ts file in the root of your project and add the following code: ` In the the Next.js config (next.config.js), add: ` The OpenTelemetry integration does not work locally, hence the above conditional check. With the above configuration, the collected OpenTelemetry data should be visible in the New Relic dashboard under "All Entities" / "Services - OpenTelemetry". Optionally, Logging via New Relic API When using the Vercel OpenTelemetry integration, there is no easy way to submit custom logs to New Relic. New Relic offers a logging API, however, so to send custom logs from your backend, you could use a logger such as Winston, which has good library support for custom transports, such as the one for New Relic. Install the following packages: ` Then create a logger.ts file with the following code: ` NewRelicTransport utilizes the New Relic logging API to send application logs. Now you can use the serverLogger in your backend code, from server components to server actions. Conclusion As you can see, various options exist for integrating New Relic with the modern, app-router-based Next.js. Sadly, at the time of writing, no one-size-fits-all solution works equally for all hosting options, as Vercel's managed Next.js platform is still relatively young, and so is the app router in Next.js. If you liked this blog post, feel free to browse our other Next.js blog posts for more tips and tricks in other areas of the Next.js ecosystem....

Jul 19, 2024

7 mins

NextJS

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

In this episode of the Modern Web Podcast, Danny Thompson sits down with Ferdinand Como and Baptiste Leproux from Nuxt Labs to uncover the story behind Nuxt Studio, a tool that's transforming how developers and non-technical users interact with Nuxt applications. Ferdinand and Baptiste share how Nuxt Studio bridges the gap between developer customization and user-friendly content management. Built to empower agencies, freelancers, and their clients, Nuxt Studio combines powerful features like live previews, Vue component integration, and schema-driven forms to make managing content seamless. The conversation also explores the broader mission of Nuxt Labs—building sustainable open-source tools that enhance developer experience and meet real-world needs. With insights into the future of Nuxt Studio and its potential to scale for larger organizations, this episode is a must-listen for anyone passionate about innovation in web development. Chapters 1. Introduction and Setting the Stage (00:00:00) 2. The Vision Behind Nuxt Studio (00:03:10) 3. Nuxt Studio’s Core Features (00:08:45) 4. Challenges in Building Nuxt Studio (00:16:20) 5. Target Audience and Use Cases (00:22:35) 6. Sustainability in Open Source (00:29:00) 7. The Future of Nuxt Studio (00:35:10) 8. Nuxt Studio’s Role in the Nuxt Ecosystem (00:42:30) 9. Closing Thoughts and What’s Next (00:48:00) 10. Sponsor Shoutout and Wrap-Up (00:53:20) Follow Baptiste Leproux and Ferdinand Coumau Baptiste Twitter: https://x.com/_larbish Ferdinand Twitter: https://x.com/CoumauFerdinand Baptiste Linkedin: https://www.linkedin.com/in/baptiste-leproux-618842b0/ Ferdinand Linkedin: https://www.linkedin.com/in/ferdinand-coumau-nuxt/ Sponsored by This Dot: thisdot.co...

Nov 20, 2024

2 mins

VueNuxtJS

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Introduction to LoopBack

Features at a Glance

Getting Started

Scaffolding the Project

Running the Project

Project Structure

Developing Our Cache Application

Implementing Basic Controller

Integrating with GitHub

Saving Issues to Local Database

Putting It All Together

Dario Djuric

You might also like

Learning Paths for Next.JS Developers with Ankita Kulkarni

Introduction to Zod for Data Validation

Integrating Next.js with New Relic

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau

Let's innovate together!

You might also like

Learning Paths for Next.JS Developers with Ankita Kulkarni

Introduction to Zod for Data Validation

Integrating Next.js with New Relic

How Nuxt Studio is Redefining Developer & User Experience with Baptiste Leproux & Ferdinand Coumau