Kapeel Kokane Coder by day, content creator by night, learner at heart!

Next.js 13: Working with the new app directory

7 min read 2031

Nextjs 13

Next.js is well known for its file system-based routing. However, Next.js v13, which is new at the time of writing, has changed the manner in which many tasks were previously performed through its new app directory.

While still supporting the same file system-based routing, which uses the pages directory, the new app directory introduces the concepts of layouts, error components, and loading components while also leveraging React’s server components for building a UI. In this article, we’ll explore these new features by building a simple app. Let’s get started!

Table of contents

New features in Next.js 13

Before we get started working on a project with Next.js 13, we’ll review the new features and concepts that Next.js 13 has introduced.

Page directory vs. app directory

If you’ve worked with previous versions of Next.js, you might already be familiar with the pages directory. Any file created inside of the pages directory would act as a route in the UI. For example, pages/home.jsx would take care of the /home route:

Pages Home JSX Route


The new app directory works alongside the pages directory to support incremental adoption and provides other new features like server-side rendering and static-site generation.

Routing with the app directory

Just like files inside of the pages directory, routing with the app directory is controlled via the folders inside of it. The UI for a particular route is defined with a page.jsx file inside of the folder.

Therefore, a folder structure that looks like app/profile/settings/page.jsx will take care of rendering the /profile/settings route:

Nextjs App Directory Routing

loading.tsx file

loading.tsx is an optional file that you can create within any directory inside the app folder. It automatically wraps the page inside of a React suspense boundary. The component will be shown immediately on the first load as well as when you’re navigating between the sibling routes.

error.tsx file

error.tsx is an optional file that isolates the error to the smallest possible subsection of the app. Creating the error.tsx file automatically wraps the page inside of a React error boundary. Whenever any error occurs inside the folder where this file is placed, the component will be replaced with the contents of this component.

layout.tsx file

You can use the layout.tsx file to define a UI that is shared across multiple places. A layout can render another layout or a page inside of it. Whenever a route changes to any component that is within the layout, its state is preserved because the layout component is not unmounted.

template.tsx file

template.tsx is similar to the layout.tsx file, but upon navigation, a new instance of the component is mounted and the state is not preserved.

Using layouts and templates allows us to take advantage of a concept known as partial rendering. While moving between routes inside of the same folder, only the layouts and pages inside of that folder are fetched and rendered:

Template Tsx Partial Rendering

Caveats of using the app directory

With so many changes having been introduced in Next.js 13, there are some things that we need to keep in mind when moving to the app directory from the pages directory.

Mandatory root layout

There must be a file that defines the root layout at the top level of the app directory. This layout is applicable to all the routes in the app. In addition, the root layout must define the <html> and the <body> tags because Next.js does not automatically add them.

Head tag

Inside any folder in the app directory, we’ll create a head.js file that will define the contents of the <head> tag for that folder. The component returned from this head.js file can only return certain limited tags like <title>, <meta>, <link>, and <script>.

Route groups

Every folder inside the app directory contributes to the URL path. But, it is possible to opt-out of it by wrapping the folder name inside of parentheses. All the files and folders inside of this special folder are said to be a part of that route group:

Nextjs Partial Rendering Route Groups

Server components

By default, all of the components created inside of the app directory are React server components, leading to better performance due to a smaller bundle size. But, if we want to switch to the client component, we need to specify that with the use client directive at the top of the file.

Hands-on with Next.js 13

Let’s experiment with all the new features in Next.js 13 by running through an example.

Project creation

First, we create a new Next.js project using Create Next App:

npx create-next-app next-13
cd next-13

Let’s run the bootstrapped code as is:

npm run dev

We are greeted with the familiar homepage:

Nextjs Homepage

The page and layout file

Let’s create a folder parallel to the pages directory and name it app. Create a layout.js file inside of app with the code below:

export default function Layout({ children }) {
  return (
    <html lang="en">

Create a page.js file with the following code:

import '../styles/globals.css'
export default function Page() {
  return <h1>Hello, Next.js!</h1>;

We’ve also imported the global.css file to make use of the global styles that are already defined. The app directory is still an experimental feature, so we need to set a flag in the next.config.js file in order to use it:

module.exports = {
  reactStrictMode: true,
  experimental:{appDir: true}

Finally, we need to delete the pages/index.js file, which will conflict with the file in the app directory. With that in place, we can now run the dev server:

npm run dev

We see that the root route / now shows the UI corresponding to the app/page.js file:

Page-js Route UI

Testing the layout

With that in place, let’s test how the layout file impacts the overall UI. First, we’ll write some CSS styles in a layout.module.css file in the same directory:

.header {
  width: 100%;
  height: 50vh;
  background-color: cyan;
  text-align: center;
  font-size: 2rem;

Next, we import those styles in the layout.js file and add them to a div inside the body just above the children:

import styles from './layout.module.css'

export default function Layout({ children }) {
  return (
    <html lang="en">
        >From layout</div>

The UI now looks like the following:

Import Styles Layout JS UI

Let’s add a new folder in the app directory called second. Create a file inside it named page.js with the following code:

import '../../styles/globals.css'

export default function Page() {
  return <h1>Second route!</h1>;

Navigating to the second route http://localhost:3000/second loads the following UI:

NextJs Secound Route UI

The layout file placed inside the app directory is being shared by the page.js in the same directory as well as the page.js inside of the second folder. You can accomplish any common changes that deal with the layout via the layout file.

Testing the error file

Next, let’s check out the error.js file. We’ll create a folder inside the app folder; we’ll name the folder breaking and create separate page.js and breaking.module.css files:

'use client';

import '../../styles/globals.css'
import styles from './breaking.module.css';

export default function Page() {
  return (
    <div className={styles.component}>
        <button onClick={(e) => console.log(e.b.c)}>
          break this

At the top of the page, use client tells Next.js to render this component as a client component, not a server component, which is the default. We’re handling user input via the button component below:

.component {
  width: 200px;
  height: 200px;
  display: flex;
  align-items: center;
  justify-content: center;
  border: 2px solid black;
  flex-direction: column;

.error {
  background-color: tomato;
  color: white;

With this CSS in place, the component looks something like the image below:

Nextjs Render Client Component

Now, let’s create an error.js file in the breaking folder. error.js will act as an error boundary in case any error occurs either inside this component or any components in its subtree:

'use client';

import '../../styles/globals.css'
import { useEffect } from 'react';
import styles from './breaking.module.css';

export default function Error({
}) {
  useEffect(() => {
    // Log the error to an error reporting service
  }, [error]);

  return (
    <div className={styles.error}>
      <p>Something went wrong!</p>
      <button onClick={() => reset()}>Reset error boundary</button>

Notice that this is also a client component. Two props are passed to this component: the error prop provides more details about the error, and the reset function resets the error boundary. This should be enough to contain the error only to the component and preserve the UI as well as the state of the rest of the application.

Testing the loading file

Next, we’ll test the functionality of the loading.js file. Let’s create one inside of the same folder with the following code:

export default function Loading() {
  return <h1>Loading...</h1>

With that in place, we need to set up some navigation. Inside the second/page.js we place a link to navigate to the /breaking route:

export default function Page() {
  return (<Link href="/breaking">navigate to breaking</Link>);

Upon clicking this link, we’ll see that before the breaking component gets mounted, the UI from the loading.js file will appear for a split second:

Loadingjs File UI Display

Data fetching

Lastly, we’ll explore how data fetching in Next.js 13 differs from earlier versions. All of the components inside the app folder are server components by default.

Let’s make the changes to the second.js component to fetch random dog facts from the Dog Facts API:

async function getData() {
  const index = Math.floor(Math.random()*10)
  const res = await fetch(https://dog-facts-api.herokuapp.com/api/v1/resources/dogs?index=${index}`);
  return res.json();

We’ll call this function directly inside of our React component by making it async:

export default async function Page() {
  const data = await getData();
  return (

The code above fetches the dog fact on the server side and displays it in our component:

Dog Fact Fetched Server Side

Client and server-side rendering

Using the Fetch API natively inside the component provides us with the ability to cache and revalidate the requests as per our requirement. Therefore, the previous utils like getStaticProps and getServerSideProps can be implemented via just one API as seen below:

// Generates statically like getStaticProps.
fetch(URL, { cache: 'force-cache' });

// Generates server-side upon every request like getServerSideProps.
fetch(URL, { cache: 'no-store' });

// Generates statically but revalidates every 20 seconds
fetch(URL, { next: { revalidate: 20 } });


That wraps up almost all the changes that were introduced with the app directory in Next.js 13.

Although at the time of writing, these new features are in beta and are bound to change slightly before being officially released, we can agree that they provide much more flexibility to configure our UI through the loading, error, and layout components. The simplicity of the native Fetch API on server components is also a great addition.

Here’s the link to the code that we worked with. Feel free to explore!

LogRocket: Full visibility into production Next.js apps

Debugging Next applications can be difficult, especially when users experience issues that are difficult to reproduce. If you’re interested in monitoring and tracking state, automatically surfacing JavaScript errors, and tracking slow network requests and component load time, try LogRocket.

LogRocket is like a DVR for web and mobile apps, recording literally everything that happens on your Next.js app. Instead of guessing why problems happen, you can aggregate and report on what state your application was in when an issue occurred. LogRocket also monitors your app's performance, reporting with metrics like client CPU load, client memory usage, and more.

The LogRocket Redux middleware package adds an extra layer of visibility into your user sessions. LogRocket logs all actions and state from your Redux stores.

Modernize how you debug your Next.js apps — .

Kapeel Kokane Coder by day, content creator by night, learner at heart!

3 Replies to “Next.js 13: Working with the new app directory”

Leave a Reply