Next.js Enterprise Project Structure

During a course on Enterprise Architecture Patterns by Łukasz Ruebbelke, I was introduced to the idea of "The Iron Triangle of Programming".

The concept is around about three pillars of code that when left poorly managed tend towards programmer purgatory. These concepts are:

It is undeniable that code bases will continue to grow, so we can set ourselves up for success with code volume by focusing on the project layout.

This post will display an overview of an opinionated project structure and how to set it up for Next.js. This code structure is one that has made it more manageable for me to separate application code from configuration as well as infrastructure code when maintaining a large, mono-repo.

Source code can be found on my okeeffed/nextjs-enterprise-project-structure GitHub repo.

Prerequisites

Getting started

We will let create-next-app create the project directory nextjs-enterprise-project-structure for us:

$ npx create-next-app@latest --ts nextjs-enterprise-project-structure
# ... creates Next.js app for us
$ cd nextjs-enterprise-project-structure
copy

The ts flag will enable TypeScript support.

At this stage, a working Next.js app is ready for us. We can check this by running npm run dev and checking the app runs on localhost.

Opting for a src directory

By default, using the tree command, we can see that our project structure looks like the following:

# Outputs the tree ignoring node_modules and .git.
$ tree -I "node_modules|.git"
.
├── README.md
├── next-env.d.ts
├── next.config.js
├── package-lock.json
├── package.json
├── pages
│   ├── _app.tsx
│   ├── api
│   │   └── hello.ts
│   └── index.tsx
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── styles
│   ├── Home.module.css
│   └── globals.css
└── tsconfig.json
copy

The first change that we are aiming to make to opt to use a src folder to host our Next.js code.

Using src is documented under the Next.js src directory documentation.

The aim of this is to separate our application code from our top-level configuration.

If you have written a large Next.js project before, you'll notice that the top-level folders start to become unruly as you add more and more top-level folders to separate our application concerns.

Placing them within src enables us to keep our top-level folders clean and organized as well as have a mutual understanding across developers about where code for the application belongs.

For this project, we can move pages and styles into src.

# Create `src` folder
$ mkdir src
# Move desired folders into `src`
$ mv pages styles src
copy

If we now run npm run dev again, then you'll see that without changing our configuration more than moving the pages folder, then the Next.js config will know where to find our project entry point (as per the documentation).

At this stage, if we re-run our tree command the project structure will look like the following:

# Output updated structure
$ tree -I "node_modules|.git"
.
├── README.md
├── next-env.d.ts
├── next.config.js
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── src
│   ├── pages
│   │   ├── _app.tsx
│   │   ├── api
│   │   │   └── hello.ts
│   │   └── index.tsx
│   └── styles
│       ├── Home.module.css
│       └── globals.css
└── tsconfig.json
copy

Breaking up our src folder

Now that we have our src folder, it is worth breaking things down even further into logical pieces.

In general, the folder structure that I generally opt for with larger projects follows the concept of Colocation but still using the design principle Separation of Concerns as a guideline.

For my larger projects, this normally means that my src folder is split into four folders:

The common folder itself generally becomes the most complex. Within that, I also define a number of different folders based on the project I am running:

For example, a current larger project I am working on currently has the following folders within common:

$ tree src/common -L 1
src/common
├── components
├── context
├── hooks
├── mocks
├── queries
├── styles
├── types
└── utils
copy

Within components again, I generally break down my components into three areas:

It is entirely up to you how you structure your common folder, but the same principle applies of colocating when directly related or following the separation of concerns.

Once this has been set up (and if you are using TypeScript), the last change that I make to the initial setup is to use TS configuration paths.

Setting up TypeScript configuration paths

Within tsconfig.json, you can set the compiler option with baseUrl to be . and then set a paths array to help with the import statements.

My personal rule of thumb is to set a path for modules and content and then for each of the folders within common:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/common/components/*"],
      "@styles/*": ["src/common/styles/*"],
      "@modules/*": ["src/modules/*"],
      "@content/*": ["src/content/*"]
    }
    // ... omitted for brevity
  }
  // ... omitted for brevity
}
copy

This now means that if we have a named export component available in src/common/components/application/my-component.tsx, we can import it as import { MyComponent } from '@components/application/my-component'.

To see some of this structure in action, let's update the default Next.js app to reflect some of the concepts we've spoken about.

Breaking the default app up

At this point, we want our src to have the following structure:

$ tree src
src
├── common
│   ├── components
│   │   └── marketing
│   │       ├── Card
│   │       │   ├── Card.module.css
│   │       │   ├── Card.tsx
│   │       │   └── index.ts
│   │       ├── Footer
│   │       │   ├── Footer.module.css
│   │       │   ├── Footer.tsx
│   │       │   └── index.ts
│   │       └── SimpleGrid
│   │           ├── SimpleGrid.module.css
│   │           ├── SimpleGrid.tsx
│   │           └── index.ts
│   └── styles
│       └── globals.css
├── modules
│   └── home
│       ├── Home.module.css
│       ├── Home.tsx
│       └── index.ts
└── pages
    ├── _app.tsx
    ├── api
    │   └── hello.ts
    └── index.tsx
copy

Within common you will need to create a components folder and a styles folder and within modules we need to create a home folder.

Given that everything displayed is what I would consider "marketing" content, I will create a marketing folder within common and within that, I will create a Card, Footer and SimpleGrid component to reflect some of the "re-useable" components that I identified within the home page.

Below will go into depth of each file we create and what to add to it.

Note that I personally opt to use barrels and enforce it with ESLint rules, but you may argue it goes against the concept of Code Volume that we spoke about earlier with the Iron Triangle of Programming.

src/common/components/marketing/Card

The following files and content were created.

Card.module.css:

.card {
  margin: 1rem;
  padding: 1.5rem;
  text-align: left;
  color: inherit;
  text-decoration: none;
  border: 1px solid #eaeaea;
  border-radius: 10px;
  transition: color 0.15s ease, border-color 0.15s ease;
  max-width: 300px;
}

.card:hover,
.card:focus,
.card:active {
  color: #0070f3;
  border-color: #0070f3;
}

.card h2 {
  margin: 0 0 1rem 0;
  font-size: 1.5rem;
}

.card p {
  margin: 0;
  font-size: 1.25rem;
  line-height: 1.5;
}
copy

Card.tsx:

import * as React from "react";
import styles from "./Card.module.css";

interface CardProps {
  href: string;
  title: string;
  body: string;
}

export const Card: React.FC<CardProps> = ({ href, title, body }) => {
  return (
    <a href={href} className={styles.card}>
      <h2>{title}</h2>
      <p>{body}</p>
    </a>
  );
};
copy

index.ts:

export { Card } from "./Card";
copy

src/common/components/marketing/Footer

Footer.module.css:

.footer {
  display: flex;
  flex: 1;
  padding: 2rem 0;
  border-top: 1px solid #eaeaea;
  justify-content: center;
  align-items: center;
}

.footer a {
  display: flex;
  justify-content: center;
  align-items: center;
  flex-grow: 1;
}

.logo {
  height: 1em;
  margin-left: 0.5rem;
}
copy

Footer.tsx:

import * as React from "react";
import Image from "next/image";
import styles from "./Footer.module.css";

export const Footer: React.FC = () => {
  return (
    <footer className={styles.footer}>
      <a
        href="https://vercel.com?utm_source=create-next-app&utm_medium=default-template&utm_campaign=create-next-app"
        target="_blank"
        rel="noopener noreferrer"
      >
        Powered by{" "}
        <span className={styles.logo}>
          <Image src="/vercel.svg" alt="Vercel Logo" width={72} height={16} />
        </span>
      </a>
    </footer>
  );
};
copy

index.ts:

export { Footer } from "./Footer";
copy

src/common/components/marketing/SimpleGrid

SimpleGrid.module.css:

.grid {
  display: flex;
  align-items: center;
  justify-content: center;
  flex-wrap: wrap;
  max-width: 800px;
}

@media (max-width: 600px) {
  .grid {
    width: 100%;
    flex-direction: column;
  }
}
copy

SimpleGrid.tsx:

import * as React from "react";
import styles from "./SimpleGrid.module.css";

export const SimpleGrid: React.FC = ({ children }) => {
  return <div className={styles.grid}>{children}</div>;
};
copy

index.ts:

export { SimpleGrid } from "./SimpleGrid";
copy

src/common/styles

globals.css:

html,
body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu,
    Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
}

a {
  color: inherit;
  text-decoration: none;
}

* {
  box-sizing: border-box;
}
copy

src/common/components/modules/Home

Home.module.css:

.main {
  min-height: 100vh;
  padding: 4rem 0;
  flex: 1;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
}

.title a {
  color: #0070f3;
  text-decoration: none;
}

.title a:hover,
.title a:focus,
.title a:active {
  text-decoration: underline;
}

.title {
  margin: 0;
  line-height: 1.15;
  font-size: 4rem;
}

.title,
.description {
  text-align: center;
}

.description {
  margin: 4rem 0;
  line-height: 1.5;
  font-size: 1.5rem;
}

.code {
  background: #fafafa;
  border-radius: 5px;
  padding: 0.75rem;
  font-size: 1.1rem;
  font-family: Menlo, Monaco, Lucida Console, Liberation Mono, DejaVu Sans Mono,
    Bitstream Vera Sans Mono, Courier New, monospace;
}
copy

Home.tsx:

import * as React from "react";
import { Card } from "@components/marketing/Card";
import { SimpleGrid } from "@components/marketing/SimpleGrid";
import styles from "./Home.module.css";

export const Home: React.FC = () => {
  return (
    <main className={styles.main}>
      <h1 className={styles.title}>
        Welcome to <a href="https://nextjs.org">Next.js!</a>
      </h1>

      <p className={styles.description}>
        Get started by editing{" "}
        <code className={styles.code}>pages/index.tsx</code>
      </p>

      <SimpleGrid>
        <Card
          title="Documentation"
          body="Find in-depth information about Next.js features and API."
          href="https://nextjs.org/docs"
        />
        <Card
          title="Learn &rarr;"
          body="Learn about Next.js in an interactive course with quizzes!"
          href="https://nextjs.org/learn"
        />
        <Card
          title="Examples"
          body="Discover and deploy boilerplate example Next.js projects."
          href="https://github.com/vercel/next.js/tree/master/examples"
        />
        <Card
          title="Deploy &rarr;"
          body="Instantly deploy your Next.js site to a public URL with Vercel."
          href="https://vercel.com/new?utm_source=create-next-app&utm_medium=default-template&utm_campaign=create-next-app"
        />
      </SimpleGrid>
    </main>
  );
};
copy

index.ts:

export { Home } from "./Home";
copy

src/pages

index.tsx:

import type { NextPage } from "next";
import Head from "next/head";
import { Home } from "@modules/home";
import { Footer } from "@components/marketing/Footer";

const IndexPage: NextPage = () => {
  return (
    <div
      style={{
        padding: "0 2rem",
      }}
    >
      <Head>
        <title>Create Next App</title>
        <meta name="description" content="Generated by create next app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <Home />
      <Footer />
    </div>
  );
};

export default IndexPage;
copy

As for the _app.tsx file, we need to update the styles import:

import "@styles/globals.css";
import type { AppProps } from "next/app";

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

export default MyApp;
copy

Running the app one last time

At this stage, if you now run the app again, you will see no changes to the default app, but we now have an example of the default app working in a format that follows some of the opinionated conventions mentioned above.

Summary

Today's post demonstrated an opinionated approach to a Next.js project structure that can scale.

Although we used a contrived example with the default application, you can see how the files begin to break up and can be reused.

It is important to note that the example app did not break up things into pieces such as i18n for content, nor displayed how the configuration works at the top-level as you add more and more to the mono-repo (things such as infrastructure-as-code or dev-ops files).

The larger the app becomes, the more a layout like the one displayed becomes useful!

The final code can be found at okeeffed/nextjs-enterprise-project-structure GitHub repo.

Resources and further reading

Photo credit: lanceanderson