37590801?s=460&v=4

A software engineer who dreams about non-electric sheep and autonomous vehicles and likes to champion security.

Software Engineer

Dan Arias

Learn how to use Next.js to create server-side rendered React applications.



In this tutorial series, you'll be provided with a practical introduction to how Next.js can help you build web applications.

Created by [Vercel, a cloud company for hosting frontends and serverless functions](https://vercel.com/home), Next.js is a React framework capable of creating applications that run both on the client and the server, otherwise known as Universal JavaScript applications. This framework helps you build universal apps faster by streamlining basic features like client-side routing and page layout while simplifying advance features like server-side rendering and code splitting.

In this first part of the series, you'll learn how to create pages and a page layout [using Next.js 9](https://nextjs.org/blog/next-9), the most recent framework version at the time of writing. [Familiarity with the React library](https://auth0.com/blog/react-tutorial-building-and-securing-your-first-app/) is recommended.

## Getting Started

To start, you need to bootstrap a React project with `next` as a dependency. Anywhere in your system, create a folder named `whatabyte` and make it your current directory:

```bash
mkdir whatabyte
cd whatabyte
```

Then, initialize a default Node.js project under the `whatabyte` directory and install core dependencies by issuing these commands:

```bash
npm init -y
npm install --save react react-dom next
```

As the name suggests, `next` is the package that will allow you to use the Next.js framework in your project with all of its modules, components, and dependencies.

Next.js is flexible but has one major structural requirement for it to work. Every Next.js project needs to have a `pages` subdirectory child to the project directory. Therefore, create a new `pages` subdirectory like so:

```bash
mkdir pages
```

Every page of your web app will be defined as a React component in a JavaScript file under the `pages` subdirectory. For example, the file `index.js` represents the root path, `/` and a file named `user.js` represents the `/user` path. You'll get a more detailed explanation of these mechanics in the next section.

To make running and building your Next.js application easy, replace the NPM scripts of your `package.json` with the following:

```json
{
  //...
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  },
  //...
}
```

Save the changes made to `package.json`. To run the project, execute this command in the terminal:

```bash
npm run dev
```

Head to [`http://localhost:3000/`](http://localhost:3000/) and bask in the glory of a `404` error. You haven't done anything wrong. This error shows up because the `pages` directory is empty. It needs an `index.js` file inside to render the default `/` home route. You'll do that... Next!

## Creating Your First Next.js Page

To understand how Next.js works, it helps to think about creating websites the classical way using HTML pages. The `index.html` file is the entry point of a website and it contains logic that takes the visitor to any other pages, like `about.html` and `profile.html`.

With Next.js, each page is represented by a JavaScript file under the `pages` subdirectory. Each file, instead of having HTML templates, exports a React component that is used by Next.js to render the page with the default root route being `index.js`. Go ahead and create this file under `pages` subdirectory:

```bash
touch pages/index.js
```

* Windows PowerShell:

```bash
ni pages/index.js
```

Populate `index.js` with this code:


```javascript
// pages/index.js

const Index = () => (
  <div>
    <p>Thank u, next</p>
  </div>
);

export default Index;
```

Without having to restart the app, Next.js detects the new `index.js` and the exported `Index` component and updates the view in the browser automatically.

![Next.js index page](https://images.ctfassets.net/23aumh6u8s0i/2bXaYCcMmJDNz0US5biyQb/62f0e3dbcc6d0cfe90e1e8d8f69b24dd/nextjs-practical-introduction_nextjs-index-page)

If you were using `create-react-app` to build your React application, you'd be looking here at rendering an `App` component instead. The `App` component is the parent or shell component for the whole application. With Next.js, you can think of that component as being implied through the `pages` subdirectory and hierarchy.

To achieve a uniform core interface for each page, you'd want to have a common layout that includes a header, a content container, and a navigation bar. This can be easily done with Next just like you'd do it with `create-react-app`: using components.

## Creating a Next.js Layout Using React Components

Under the `whatabyte` root directory, create a `components` directory:

```bash
mkdir components
```

The name of this directory could be really anything, but it makes sense to stick with well-understood file structure names that make it easier for anyone else to understand the structure of your application.

You need three components for creating a layout:

* `Layout` to hold the core view in place
* `Header` to provide a standard header to all views
* `NavBar` to provide navigation buttons

Thus, create the following files under the `components` directory:

* `Layout.js`
* `Header.js`
* `NavBar.js`

```bash
touch components/Layout.js components/Header.js components/NavBar.js
```

* Windows PowerShell:

```bash
ni components/Layout.js, components/Header.js, components/NavBar.js
```

Open `Header.js` and add the following code to it:

```javascript
// components/Header.js

const headerStyle = {
  backgroundColor: "blue",
  color: "white",
  width: "100%",
  height: "50px"
};

const Header = () => (
  <div className="Header" style={headerStyle}>
    HEADER
  </div>
);

export default Header;
```

In `NavBar.js` add the following:

```javascript
// components/NavBar.js

const navBarStyle = {
  backgroundColor: "red",
  color: "white",
  width: "100%",
  height: "60px"
};

const NavBar = () => (
  <div className="NavBar" style={navBarStyle}>
    NAVBAR
  </div>
);

export default NavBar;
```

In `Layout.js`, use the `Header` and `NavBar` components to render any content passed through `props.children` within a `Content` container:

```javascript
// components/Layout.js

import Header from "./Header";
import NavBar from "./NavBar";

const layoutStyle = {
  display: "flex",
  flexDirection: "column",
  height: "100%",
  width: "100%"
};

const contentStyle = {
  flex: 1,
  display: "flex",
  flexDirection: "column"
};

const Layout = props => (
  <div className="Layout" style={layoutStyle}>
    <Header />
    <div className="Content" style={contentStyle}>
      {props.children}
    </div>
    <NavBar />
  </div>
);

export default Layout;
```

These three components use inline CSS styling to give improve their structure and presentation.

Finally, update `index.js` to use the `Layout` component:

```javascript
// pages/index.js

import Layout from "../components/Layout";

const Index = () => <Layout>Welcome to WHATABYTE!</Layout>;

export default Index;
```  

![Next.js index page using a layout component](https://images.ctfassets.net/23aumh6u8s0i/69v0dEitl6ISUXJtGPylY/7b08e470423209df73b4c8340384968b/nextjs-practical-introduction_nextjs-index-page-using-a-layout-component)

> The look and feel of the interface will improve in the next part of this tutorial.

In the browser, the index page now shows a blue box serving as a header, a white box with a message serving as content, and a red box serving as the navigation bar. With a layout in place, you are ready to create more pages with a consistent structure.

## Creating More Pages Using Next.js

The _WHATABYTE_ app has four core views:

* Explore: To show trending restaurants and dishes
* Near Me: To show restaurants near the user
* My Cart: To show the orders of the user
* Profile: To show the user information such as name, address, and billing data

As you may be thinking, you'll need to add new files under the `pages` directory to represent each of these pages. You are right. The plan here is to create a route for each view:

* `/explore`
* `/nearme`
* `/mycart`
* `/profile`

To create these views, create the following files under the `pages` directory and add their respective content:

```bash
touch pages/explore.js pages/nearme.js pages/mycart.js pages/profile.js
```

* Windows PowerShell:

```bash
ni pages/explore.js, pages/nearme.js, pages/mycart.js, pages/profile.js
```

- `explore.js`:

```javascript
// pages/explore.js

import Layout from "../components/Layout";

const ExploreView = props => <Layout>{`Explore View`}</Layout>;

export default ExploreView;
```

- `nearme.js`:

```javascript
// pages/nearme.js

import Layout from "../components/Layout";

const NearMeView = props => <Layout>{`Near Me View`}</Layout>;

export default NearMeView;
```

- `mycart.js`:

```javascript
// pages/mycart.js

import Layout from "../components/Layout";

const MyCartView = props => <Layout>{`My Cart View`}</Layout>;

export default MyCartView;
```

- `profile.js`:

```javascript
// pages/profile.js

import Layout from "../components/Layout";

const ProfileView = props => <Layout>{`Profile View`}</Layout>;

export default ProfileView;
```

In the browser, you can visit [`http://localhost:3000/explore`](http://localhost:3000/explore) and see the new Explore page up and running! You can try any of the other paths as well.

<include src="TweetQuote" quoteText="Learn how to bootstrap a Next.js application to create pages and a page layout."/>

## Get Your Head In the Next.js Game

Your Next.js pages need to have a document title shown on the page tab or window title bar of the browser. To add a document title, you need to use the [`<title>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) HTML element which can only be used within a web page's `<head>` block.

Next.js pages are created with a `<head>` block that has sensible defaults such as the following:

```html
<head>
  <title class="next-head"></title>
  <meta charset="utf-8" class="next-head">
  <meta
    name="viewport"
    content="width=device-width,minimum-scale=1,initial-scale=1"
    class="next-head">
</head>
```

However, notice that the `title` tag is empty. To modify the `head` block, Next.js offers a [built-in `Head` component](https://github.com/zeit/next.js/#populating-head) in the `next/head` module which appends elements to the `<head>` block of a page. To modify the document title, you'd nest a `title` HTML element within the `Head` component.

Since you need the document title to be present on every page, the `<head>` block should be modified within the `Layout` component template. Open `components/Layout.js` and update its content as follows:

```javascript
// components/Layout.js

import Head from "next/head";

// Component imports remain the same

// Style objects already defined

const Layout = props => (
  <div className="Layout" style={layoutStyle}>
    <Head>
      <title>WHATABYTE</title>
    </Head>

    <Header />
    <div className="Content" style={contentStyle}>
      {props.children}
    </div>
    <NavBar />
  </div>
);

export default Layout;
```

The browser tab or window hosting your page should now reflect the "WHATABYTE" title.

The `<head>` block can also contain other important metadata (data that describes data) like scripts, stylesheets, character encoding, name, and much more.

> For more information, visit the [`<head>` block](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) and [metadata](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#Attributes) MDN docs.

<include src="TweetQuote" quoteText="Learn how to get started with Next.js, a universal JavaScript framework based on React."/>

## Next Steps

The current layout of the application is not working as it should. The `.Content` container, within the `Layout` component, is expected to stretch out to fill the space left by the `Header` and `NavBar` components as its `contentStyle` object specifies the `flex: 1` CSS property. However, this flexible property depends on the height value of the its parent, the `.Layout` container.

Despite the `height` of the `.Layout` container being specified in its `layoutStyle` object as `100%`, this container is not filling out the full height of the viewport. In turn, this could only mean that its parent doesn't have a definite height.

If you open the browser Dev Tools and look at the structure of the Index page, you'll notice that the parent container for the app is a `div` element with the ID `__next`. Clicking on that element shows that it has no height or width; therefore, its descendant containers have no height value to inherit and use for dynamic sizing.

To fix this, you'd need to give the `__next` container a `height` and `width` of `100%`. But Next.js doesn't come with a default global index stylesheet like with `create-react-app`. The solution is to style components in the "Next.js way" or to use custom SCSS, which is the topic of the next second part of this tutorial.

## Recap

In this first part, you have learned how to use Next.js to create pages that integrate a page layout. Using a page layout gives your pages consistent high-level structure. To give the elements within each page better styling and positioning, you need to rely on CSS.

So far, you applied basic styling to your pages using inline style objects. However, Next.js offers more scalable and powerful mechanisms to apply styles to your pages. In the next part of this tutorial, your pages will go from this...

![Another Next.js view with basic layout](https://images.ctfassets.net/23aumh6u8s0i/2D9tCkdKRpVwyNcCJxThNf/94870998bf1d698363b2fdb6ddeb51e3/nextjs-practical-introduction_another-nextjs-view-with-basic-layout)

... to this!

![Next.js polished layout](https://images.ctfassets.net/23aumh6u8s0i/1URWqzEEl1HZEdGTmW8vD4/37d1dfb6885b42030cbd1fb789349274/nextjs-practical-introduction_nextjs-polished-layout)

### [Continue to Part 2: Next.js Styling and Theming](https://auth0.com/blog/next-js-practical-introduction-for-react-developers-part-2/)


Next.js Practical Introduction: Pages and Layout

Learn how to use Express and Pug to build a website in Node.js

Build a Website with Node.js and Express

roy-derks

Roy Derks is a serial startup CTO and conference speaker from Amsterdam. He also teaches React and GraphQL workshops, and works on open-source JavaScript projects for the City of Amsterdam.

Guest Author

Roy Derks

Learn how to handle authentication and authorization of a GraphQL server using Node.js and JWTs.

Build and Secure a GraphQL Server with Node.js

Learn how to use Passport.js to add user authentication to a web app built with Node.js and Express.

Node.js and Express Authentication Using Passport

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how clickjacking attacks implement visual tricks to capture users' clicks, and how you can prevent them by applying client-side and server-side solutions.

Clickjacking Attacks and How to Prevent Them

Learn how to use Next.js to add navigation and routing to server-side rendered React applications.



In this tutorial series, you'll be provided with a practical introduction to how Next.js can help you build web applications. 

Created by [ZEIT, a cloud company for hosting frontends and serverless functions](https://zeit.co/), Next.js is a React framework capable of creating applications that run both on the client and the server, otherwise known as Universal JavaScript applications. This framework helps you build universal apps faster by streamlining basic features like client-side routing and page layout while simplifying advance features like server-side rendering and code splitting.

Part one of this Nextjs series shows developers [how to create pages and layouts](https://auth0.com/blog/next-js-practical-introduction-for-react-developers-part-1/). In the second part of the series, you learned [how to add styling and create themes](https://auth0.com/blog/next-js-practical-introduction-for-react-developers-part-2/). In this third part of the series, you'll learn how to navigate to pages and implement routing using [using Next.js 9](https://nextjs.org/blog/next-9), the most recent framework version at the time of writing. [Familiarity with the React library](https://auth0.com/blog/react-tutorial-building-and-securing-your-first-app/) is recommended.

## Setting Up the Project

If you are starting from this part, you can get the app that was built in the previous, second part by cloning the repo and checking out the `part-2` branch:

```bash
git clone git@github.com:auth0-blog/whatabyte-next-intro.git whatabyte
cd whatabyte
git checkout part-2
```

If you haven't [connected to GitHub using SSH](https://help.github.com/en/articles/connecting-to-github-with-ssh), please clone the repo with the HTTPS URL:

```bash
git clone https://github.com/auth0-blog/whatabyte-next-intro.git whatabyte
cd whatabyte
git checkout part-2
```

The repository is cloned into the directory called `whatabyte` on your local machine. If the directory doesn't exist, it is created.

With the branch checked out, proceed to install the project dependencies:

```bash
npm install
```

Finally, execute the following command in your terminal to run the app:

```bash
npm run dev
```

To see the app in action and start following the tutorial, visit [`http://localhost:3000`](http://localhost:3000) on your browser.

## Understanding Next.js Routing

The _WHATABYTE_ app has four core routes:

* `/explore`: To show trending restaurants and dishes
* `/nearme`: To show restaurants near the user
* `/mycart`: To show the orders of the user
* `/profile`: To show the user information such as name, address, and billing data

From these four core routes, the `/explore` route will be the main route. Thus, the root path, `/`, should redirect to `/explore`.

First, to get familiar with navigation in Next.js, you'll navigate to the Explore page from the Index page by adding a hyperlink inside the content container of the Index page. You can do this easily by using the [Next.js `Link` component](https://nextjs.org/docs#with-link) inside `index.js` as follows:

```javascript
// pages/index.js
import Link from "next/link";

import Layout from "../components/Layout";

const Index = () => (
  <Layout>
    <br />
    <Link href="/explore">
      <a> Welcome to WHATABYTE! Start Exploring Now</a>
    </Link>
  </Layout>
);

export default Index;
```

The Next.js `Link` component takes a route or navigation path as the value of its `href` property. You can embed any other component within `Link` as long as that component can take an `href` prop.

After the view updates in the browser, visit [`http://localhost:3000/`](http://localhost:3000/) and click on the link. It will take you to the Explore page.

![Next.js app using the Link component](https://images.ctfassets.net/23aumh6u8s0i/p60hqwOc0JhYZ0QZfr89b/9450c893ce78d695ecd3d01ad20313bd/nextjs-practical-introduction_nextjs-app-using-link-component)

Using this link to navigate to another page is good for testing but what the app needs is navigation through the `NavBar` component. To do so, you'd need a `NavButton` component to make the creation of four navigation buttons standard and easy to maintain. 

To make the buttons look nice, you'll use the [FontAwesome icons](https://fontawesome.com/icons?d=gallery). Using another console window or tab, install the following packages:

```bash
npm i @fortawesome/fontawesome-svg-core \
  @fortawesome/free-solid-svg-icons \
  @fortawesome/react-fontawesome
```

* Windows PowerShell:

```bash
npm i @fortawesome/fontawesome-svg-core `
  @fortawesome/free-solid-svg-icons `
  @fortawesome/react-fontawesome
```

Creating the navigation bar dynamically would be much easier if you can encapsulate all of its configuration in a file. Under the `whatabyte` directory, create a `config` subdirectory:

```bash
mkdir config
```

Within that new subdirectory, create a `buttons.js` file within it:

```bash
touch config/buttons.js
```

* Windows PowerShell:

```bash
ni config/buttons.js
```

Then, populate `buttons.js` as follows:

```javascript
// config/buttons.js

import React from "react";
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
import {
  faCompass,
  faMapMarkerAlt,
  faUser,
  faShoppingCart
} from "@fortawesome/free-solid-svg-icons";

const navButtons = [
  {
    label: "Explore",
    path: "/explore",
    icon: <FontAwesomeIcon icon={faCompass} />
  },
  {
    label: "Near Me",
    path: "/nearme",
    icon: <FontAwesomeIcon icon={faMapMarkerAlt} />
  },
  {
    label: "My Cart",
    path: "/mycart",
    icon: <FontAwesomeIcon icon={faShoppingCart} />
  },
  {
    label: "Profile",
    path: "/profile",
    icon: <FontAwesomeIcon icon={faUser} />
  }
];

export default navButtons;
```

Then, under the `components` directory, create a `NavButton.js` file that exports the `NavButton` component:

```bash
touch components/NavButton.js
```

* Windows PowerShell:

```bash
ni components/NavButton.js
```

Then, populate `NavButton.js` with the following:

```javascript
// components/NavButton.js

import Link from "next/link";

import "./NavButton.scss";

const NavButton = props => (
  <Link href={props.path}>
    <div className="NavButton">
      <div className="Icon">{props.icon}</div>
      <span className="Label">{props.label}</span>
    </div>
  </Link>
);

export default NavButton;
```

The `NavButton` needs its proper styling. Create `NavButton.scss` as a sibling file:

```bash
touch components/NavButton.scss
```

* Windows PowerShell:

```bash
ni components/NavButton.scss
```

Then, populate `NavButton.scss` with the following [style rules](https://sass-lang.com/documentation/style-rules):

```scss
// components/NavButton.scss

.NavButton {
  display: flex;
  flex-direction: column;
  justify-content: space-around;
  align-items: center;

  height: 100%;

  cursor: pointer;

  .Icon {
    font-size: 20px;
  }

  .Label {
    font-size: 12px;
    text-transform: capitalize;
  }
}
```

Import the button configuration file in the `Layout` component and pass its data as the `navButtons` props to the `NavBar` component:

```javascript
// components/Layout.js
import Head from "next/head";

import Header from "./Header";
import NavBar from "./NavBar";

import "./Layout.scss";
import "./index.scss";

import navButtons from "../config/buttons";

const Layout = props => {
  const appTitle = `> WHATABYTE`;

  return (
    <div className="Layout">
      <Head>
        <title>WHATABYTE</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <meta charSet="utf-8" />
      </Head>

      <Header appTitle={appTitle} />
      <div className="Content">{props.children}</div>
      <NavBar navButtons={navButtons} />
    </div>
  );
};

export default Layout;
```

It's better for the `Layout` component to be the one responsible for passing the button configuration to the `NavBar` component as it is in charge of enforcing a consistent structure for each page of the application. If you wanted to keep `Layout` as a presentational component, then you could wrap it into a container component that passes it the button configuration data.

To render the buttons within the `NavBar` component, update the content of the `NavBar.js` file as follows:

```javascript
// components/NavBar.js

import "./NavBar.scss";
import NavButton from "./NavButton";

const NavBar = props => (
  <div className="NavBar">
    {props.navButtons.map(button => (
      <NavButton
        key={button.path}
        path={button.path}
        label={button.label}
        icon={button.icon}
      />
    ))}
  </div>
);

export default NavBar;
```

If your app is not running, execute `npm run dev` in the terminal. Otherwise, visit [`http://localhost:3000/`](http://localhost:3000/) directly and then click on the Profile button. You'll be taken to the Profile page. Try using the other navigation buttons. 

> If the labels and icons of the buttons look too big, refresh the page.

Did you notice a bit of delay when you navigated from page to page? If you look at the terminal window or tab where the server is running, you may see a message from Next.js explaining that the pages need to be compiled when you first load them, causing a small delay:

```bash
Note that pages will be compiled when you first load them.
```

The navigation bar becomes much more functional and expressive by having those buttons with icons and labels on them. However, adding a visual indicator of what view is active by looking at the navbar would further improve the user experience. You'll learn how to do that in the next section by applying the `.active` CSS class to `NavButton` components dynamically.

<include src="TweetQuote" quoteText="Learn how to add navigation and routing to Next.js apps."/>

## Using High-Order Components with Next.js

The Next.js `Link` component has two main props:

- `href` specifies a path inside the `pages` directory to use as a route.

- `as` is used to customize the path rendered in the browser URL bar. 

 
There's no "active" class prop that we can pass to it. To style it, you need to do so within its underlying components.

The Next.js router keeps track of the active page through a `router.pathname` property. To inject the `pathname` prop in your component, you can use the [`withRouter` higher-order component](https://nextjs.org/docs#using-a-higher-order-component). Using this prop with conditional styling will let you have a distinctive style for the active page button. 

Open `components/NavButton.js` and update its content to this:

```javascript
// components/NavButton.js

import Link from "next/link";
import { withRouter } from "next/router";

import "./NavButton.scss";

const NavButton = props => (
  <Link href={props.path}>
    <div
      className={`NavButton ${
        props.router.pathname === props.path ? "active" : ""
      }`}
    >
      <div className="Icon">{props.icon}</div>
      <span className="Label">{props.label}</span>
    </div>
  </Link>
);

export default withRouter(NavButton);
```

If the `path` prop matches the `router.pathname` prop, the `active` class is added to the `NavButton` class name. Save your changes and test the navigation buttons in the browser. Once you click on a button, its icon lights up into an orange-red-like color.

![Next.js nav bar with active view indicator](https://images.ctfassets.net/23aumh6u8s0i/7CGRo1E2kEu4n0r74at5x1/c43e0ae420ce84103ca404111249cc58/nextjs-practical-introduction_nextjs-nav-bar-with-active-view-indicator)

## Recap

In this part of the tutorial, you have learned how to use Next.js built-in components to navigate to pages within your app and to represent the state of the router through navigation UI elements. 

You've done a lot so far throughout this tutorial and there is a lot more than could be done using Next.js! The last part of this practical introduction to Next.js will teach you how to create a login page and add user authentication to your app using Passport.js and Auth0.

Again, you can reference [Part 2 for adding styling and creating themes, here](https://auth0.com/blog/next-js-practical-introduction-for-react-developers-part-2/) and [Part 1 for creating pages and a page layout](https://auth0.com/blog/next-js-practical-introduction-for-react-developers-part-1/)

> Can't wait to learn about Next.js authentication? Feel free to read Bruno's [Next.js Authentication Tutorial](https://auth0.com/blog/next-js-authentication-tutorial/).

<include src="asides/AboutAuth0" />


Next.js Practical Introduction: Navigation and Routing

Learn how to handle styling and theming while using Next.js to build server-side rendered React applications.

Next.js Practical Introduction: Styling and Theming

30b8d1b7c0dab4bb311c121a47a6aae9?s=80 avatar

30b8d1b7c0dab4bb311c121a47a6aae9?s=80

Vladimir Fomene

Learn how to use Express Validator, a set of middleware functions, to perform server-side validation on user data.



**TL;DR:** In this article you will learn to validate and sanitize data in your Express.js
applications using a set of middleware called [`express-validator`](https://express-validator.github.io/docs/). You will do so by completing a demo application that takes in user input and validates/sanitizes it using
this library. If you want to see the complete application developed throughout this article, take a look at [this GitHub repository](https://github.com/auth0-blog/expressjs-validator).

## Prerequisites

Software you need to install to follow this tutorial:

* [Node.js and NPM (Node Package Manager)](https://nodejs.org/en/download/). While writing this article, the author used Node.js `v8.13.0`.
* Any text editor or IDE of your choice ([VS Code](https://code.visualstudio.com/), [WebStorm](https://www.jetbrains.com/webstorm/download/), [Atom](https://atom.io/), [Sublime](https://www.sublimetext.com/), etc.).

## What Is Express Validator?

According to the [official website](https://express-validator.github.io/docs/), Express Validator is a set of [Express.js middleware](http://expressjs.com/en/guide/using-middleware.html) that wraps [`validator.js`](https://github.com/chriso/validator.js), a library that provides validator and sanitizer functions. Simply said, Express Validator is an Express middleware library that you can incorporate in your apps for server-side data validation.

### Why Server-Side Validation?

Mainly speaking, you _must_ care about server-side validation because data coming from other clients (single-page apps, regular web apps, mobile applications, etc.) cannot be trusted. For example, your servers have no means to know if a malicious user (or virus) disabled front-end validation (e.g., JavaScript) to allow the app to submit bogus data to your server. That is, client-side validation is _not enough_.

## Set Up Your Playground For Express Validator

To start playing with Express Validator, you will clone a simple Express server to use as a playground. To do so, open your terminal in a preferred directory and clone the starter project with the following command:

```bash
# clone repository
git clone https://github.com/auth0-blog/expressjs-validator.git

# move into your clone repository
cd expressjs-validator
```

Then, install all the project dependencies by running the following command in the project root:

```bash
npm install
```

This simple Express application contains just enough for you to get started and focus on learning about the `express-validator` library. For example, if you check the `views/layout.pug` file, you will see that it contains some basic HTML elements to define how the app should look like.

> **Note:** If you are not familiar with [Pug, the template engine](https://pugjs.org/api/getting-started.html), you might find the syntax of this file a bit different. Don't worry, you don't need to be acquainted with Pug to follow this article along. Also, if you take a close look to the source code, you will probably understand what is going on. For example, you will see a line starting with `link` that contains the `href` keyword pointing to a [BootStrap](https://getbootstrap.com/) file. This is just the code telling the browser to import an external CSS file, quite similar to what you would do in HTML.

Besides the `views/layout.pug` file, these are other important files that you must know about:

- `./routes/index.js`: This file is responsible for rendering the homepage of your app. The `res.render('index')` line will make Express and Pug work together to render the `views/index.pug` file.
- `./routes/users.js`: For now, this file adds an endpoint to your app that doesn't do anything. Soon, you will start using this file to learn about the `express-validator` library.
- `./public/javascripts/script.js`: This is the file that will be in charge of sending user data to your backend. The requests will be some AJAX calls to the endpoint defined on the `routes/users.js` file.
- `./app.js`: This is the file responsible for bootstrapping the backend. This file sets up Pug as the template engine and tells Express.js where to find the other JavaScript files.

With that, you now know how the app is structured, but don't run the project yet! You still need to define the home page of your app.

## Build Homepage For User Input

After learning about the structure of the playground, you will need to add the following code to the `views/index.pug` file:

```pugjs
extends layout

block content
  .container
    .alert(class="alert-danger", role="alert", id="error-group", style="display: none")
      ul(id="errors")
    .row
      .col-sm.col-md-8.offset-md-2.col-lg-6.offset-lg-3
        h3 Welcome To Express Validator!
        form
          .form-group
            input.form-control(type="text", id="name", placeholder="Name")
          .form-group
            input.form-control(type="text", id="classYear", placeholder="Class Year")
          .form-group
            input.form-control(type="text", id="weekday", placeholder="Available Weekday")
          .form-group
            input.form-control(type="email", id="email", placeholder="Email")
          .form-group
            input.form-control(type="password", id="password", placeholder="Password")
          .form-group
            input.form-control(type="password", id="confirmPassword", placeholder="Confirm Password")
          .form-group
            button.form-control(type="button", class="btn btn-primary", id="signup-btn") Submit
```

What you are doing here is to add a bunch of `input` elements to the homepage that will receive user input to be sent to the backend. With that covered, you have everything in place to have a sneak peek at the app. Go to the project root directory
and run the following command to get the app started.

```bash
node app.js
```

Now, if you visit [`http://localhost:3000/`](http://localhost:3000/) in your favorite browser, you should see the following page:

![Express Validator Tutorial: Scaffolding the sample app.](https://images.ctfassets.net/23aumh6u8s0i/4HKvT3HZ3MqdXsTZMKUaqQ/5e1105b1c1c24aad89af2bee6938c70e/app-screenshot)

> **Note:** You can stop the server now, but whenever you add a new feature/functionality, you will need to restart the server if it is already running or just start it.

Once the user enters data on your homepage and clicks the **Submit** button, you will need to handle the on submit event and make an AJAX request to your Express back-end. To do that, add the following code to your `./public/javascripts/script.js` file:

```js
$('#signup-btn').click(function () {
  $.ajax({
    url: '/users',
    type: 'POST',
    cache: false,
    data: {
      name: $('#name').val(),
      classYear: $('#classYear').val(),
      weekday: $('#weekday').val(),
      email: $('#email').val(),
      phoneNumber: $('#phoneNumber').val(),
      password: $('#password').val(),
      confirmPassword: $('#confirmPassword').val()
    },
    success: function () {
      $('#error-group').css('display', 'none');
      alert('Your submission was successful');
    },
    error: function (data) {
      $('#error-group').css('display', 'block');
      var errors = JSON.parse(data.responseText);
      var errorsContainer = $('#errors');
      errorsContainer.innerHTML = '';
      var errorsList = '';

      for (var i = 0; i < errors.length; i++) {
        errorsList += '<li>' + errors[i].msg + '</li>';
      }
      errorsContainer.html(errorsList);
    }
  });
});
```

From the code above, on form submission, a POST request is made to the `http://localhost:3000/users` endpoint with the data entered by users on the HTML fields defined before. If there is an error during validation, this code will make sure to display the error messages inside a `div` marked with the `alert` class. If no errors are found, a successful validation will trigger an alert with this message: "Your submission was successful".

## Server-Side Validation With Express Validator

Now that you have your front-end set up, you will start learning about `express-validator`. To do that, the first thing you will need to do is to install the library:

```bash
npm install express-validator --save
```

After installing `express-validator`, open the `routes/users.js` file and import the [check API](https://express-validator.github.io/docs/check-api.html) to use its validation functions:

```js
// ... call to require('express') ...
const {check, validationResult} = require('express-validator/check');

// ... leave the rest untouched ...
```

### Making sure fields are not empty

Now, to validate your form input, you need to pass an array in which you specify the fields that you want to validate as a second argument to your route handler for `/users` POST requests. To do that, add the following code after the GET route handling code in `routes/user.js`:

```js
// ... require statements ...

// ... router.get ...

router.post('/', [
    check('name').not().isEmpty().withMessage('Name must have more than 5 characters'),
    check('classYear', 'Class Year should be a number').not().isEmpty(),
    check('weekday', 'Choose a weekday').optional(),
    check('email', 'Your email is not valid').not().isEmpty(),
    check('password', 'Your password must be at least 5 characters').not().isEmpty(),
  ],
  function (req, res) {
    const errors = validationResult(req);
    console.log(req.body);

    if (!errors.isEmpty()) {
      return res.status(422).jsonp(errors.array());
    } else {
      res.send({});
    }
  });

module.exports = router;
```

The string passed as an argument to the `check` function specifies which data field you want to validate (e.g., `classYear`). The `not().isEmpty()` function chain makes the library validate that this field is not empty. The string argument added to `withMessage()` specifies a custom error message which will be send back to your users if this particular field violates a validation requirement.

> **Note:** You can also provide a custom error message by passing it as a second argument to the `check()` function.

By calling the `optional()` function on it, you have made the `weekday` field optional. So far, you have only specified how you want your fields to be validated. You might be wondering where Express.js actually does the validation. Validation happens in the request handler when it calls the `validationResult()` function. To test this, run your application and submit an empty form to the server and you should see the following error displayed in red.

![Express validator showing error messages.](https://images.ctfassets.net/23aumh6u8s0i/55oL7TnIWUeSSUPWph5aal/fc62311dd2d57123edf25666b015efc5/error-messages)

Remark how there is no error for the **weekday** field, this is because you made the field optional during validation. Pretty cool, huh?

### Validating fields' length

You can also check if a data field meets a certain character length requirement by using the `isLength()` function. This function takes in an object in which you specify the minimum and/or the maximum number of characters in that field. To see this in action, update the validation requirements for the name and password field as follows:

```js
[
  // ... leave other validations untouched ...
  check('name').not().isEmpty().isLength({min: 5}).withMessage('Name must have more than 5 characters'),
  check('password', 'Your password must be at least 5 characters').not().isEmpty().isLength({min: 5}),
]
```

Now, restart the app and try to enter a name and password less than five characters long. You should see the app complaining about the field length.

### Validating fields' type

Apart from validating the character length of a field, you can also validate its type or validate it against a list. For example, you can specify that your `classYear` field needs to be an integer. You can also specify that weekday should not be Saturday or Sunday. To do that, update your validation requirements as follows:

```js
[
  // ... leave other validations untouched ...
  check('classYear', 'Class Year should be a number').not().isEmpty().isInt(),
  check('weekday', 'Choose a weekday').optional().not().isIn(['Sunday', 'Saturday']),
]
```

Now, after restarting the app, if you try to enter a value which is not an integer in the class year field, you will see an error message. Also, if you enter "Saturday" or "Sunday" in the weekday field, you will see the backend complaining.

### Validating and sanitizing emails

Express Validator also validates emails with the `isEmail()` function. Besides that, you can also make this library normalize emails with the `normalizeEmail()` function. In case you are wondering what it means to normalize an email, you can read about it in this [Stack Overflow post](https://stackoverflow.com/questions/27936705/what-does-it-mean-to-normalize-an-email-address).

In order to validate the email field, refactor the `check('email'` call in your code:

```js
[
  // ... leave other validations untouched ...
  check('email', 'Your email is not valid').not().isEmpty().isEmail().normalizeEmail(),
]
```

Then, after restarting the app, if you enter an invalid email on your homepage you will get an error message:

![Validating email addresses with Express Validator](https://images.ctfassets.net/23aumh6u8s0i/26cwBYI8B4AvRLMizfbUcV/57d5b927eb05c0ab024257c38a9607e9/email-error-messages)

### Sanitizing fields with trim and escape

With Express Validator, you can also trim away spaces from your data and escape special characters using the `trim()` and `escape()` functions. The `escape()` function can really come in handy when protecting yourself from cross-site scripting attacks. To add this feature to your app, refactor the call to `check('name')` as follows:

```js
[
  // ... leave other validations untouched ...

  check('name').exists().isLength({min: 5}).trim().escape().withMessage('Name must have more than 5 characters'),
]
```

To test this, the starter project came with code that prints every request body to the console after validation. So, imagine a malicious user types the following JavaScript code in your name field: `<script> alert("hello, there");</script>`. By using `escape` you will have no problem, as the name that you will get in your backend will look like:

```text
&lt;script&gt; alert(&quot;hello, there&quot;);&lt;&#x2F;script&gt;
```

That is, Express Validator transformed the malicious code into special HTML characters. Amazing, right?

### Validating with custom validators

Although Express Validator offers a bunch of solutions out of the box for you, chances are you will need to implement some custom validation. For example, imagine you need to make sure that the `password` field matches the `confirmPassword` field. To do that, you can use the `custom()` validation function as follows:

```js
[
  // ... leave other validations untouched ...

  check('confirmPassword', 'Passwords do not match').custom((value, {req}) => (value === req.body.password)),
]
```

The `custom` function takes in a function (an arrow function in this case) as an argument and checks if the `value` of the `confirmPassword` is the same as the value of the `req.body.password` field. To see this in action, restart your app, then enter a different password and you should get the message saying that "passwords do not match".

## Conclusion

In this article, you learned how to use the Express Validator middleware to validate and sanitize user data in an Express application. Guess what? You only scratched the surface of what is possible with Express Validator. Aside from learning more validation and sanitization functions, you can learn how to add wildcards to your validations, do schema validation and whole body validation from [Express Validator's documentation](https://express-validator.github.io/docs/). I will love to see what you build with Express Validator.

<include src="asides/AboutAuth0" />


"server-side"