Mastering Next.js: The Ultimate Guide to Structuring Large-Scale Projects in 2024

Introduction: Taming the Next.js Jungle

Hey there, code wranglers and Next.js enthusiasts! 👋 Are you feeling like Indiana Jones, hacking through a dense jungle of components, hooks, and config files? Don't worry, you're not alone in this adventure. I've been there, machete in hand, trying to carve a path through the wilderness of a large-scale Next.js project.

But here's the thing: with the right map and tools, your Next.js jungle can become a well-organized, thriving ecosystem. In this comprehensive guide, I'll share my hard-earned wisdom on structuring large-scale Next.js projects. Whether you're scaling up an existing app or starting a new behemoth from scratch, this guide is your trusty compass.

Why Your Next.js Project Structure Can Make or Break You

Before we dive into the nitty-gritty, let's talk about why spending time on your project structure is like investing in a good pair of coding shoes – it'll take you far and keep you comfortable:

1. Developer Sanity: A good structure means less time playing "Where's Waldo?" with your components and more time actually coding.
2. Team Harmony: When your team can navigate the project blindfolded, collaboration becomes a breeze, not a battle.
3. Scalability: A well-structured project grows organically, like a happy plant, instead of mutating into a code monster.
4. Performance Boost: Next.js optimization features work best when your project is organized logically.
5. Maintainability: Future you (or the poor soul who inherits your project) will be eternally grateful for a clean, intuitive structure.

The Next.js Project Structure That'll Make You Want to Frame It

Alright, drum roll, please! 🥁 Here's a structure that's been battle-tested in the trenches of large-scale Next.js development:

📁 my-awesome-nextjs-project
|
|_ 📁 app
|  |_ 📁 (auth)
|  |  |_ 📁 login
|  |  |  |_ 📄 page.tsx
|  |  |  |_ 📄 layout.tsx
|  |  |_ 📁 register
|  |     |_ 📄 page.tsx
|  |     |_ 📄 layout.tsx
|  |_ 📁 dashboard
|  |  |_ 📄 page.tsx
|  |  |_ 📄 layout.tsx
|  |_ 📁 api
|  |  |_ 📁 users
|  |  |  |_ 📄 route.ts
|  |  |_ 📁 posts
|  |     |_ 📄 route.ts
|  |_ 📄 layout.tsx
|  |_ 📄 page.tsx
|
|_ 📁 components
|  |_ 📁 ui
|  |  |_ 📄 Button.tsx
|  |  |_ 📄 Card.tsx
|  |  |_ 📄 Modal.tsx
|  |_ 📁 forms
|  |  |_ 📄 LoginForm.tsx
|  |  |_ 📄 RegisterForm.tsx
|  |_ 📁 layouts
|     |_ 📄 Header.tsx
|     |_ 📄 Footer.tsx
|     |_ 📄 Sidebar.tsx
|
|_ 📁 lib
|  |_ 📄 api.ts
|  |_ 📄 utils.ts
|  |_ 📄 constants.ts
|
|_ 📁 hooks
|  |_ 📄 useUser.ts
|  |_ 📄 useAuth.ts
|  |_ 📄 usePosts.ts
|
|_ 📁 types
|  |_ 📄 user.ts
|  |_ 📄 post.ts
|  |_ 📄 api.ts
|
|_ 📁 styles
|  |_ 📄 globals.css
|  |_ 📄 variables.css
|
|_ 📁 public
|  |_ 📁 images
|  |  |_ 📄 logo.svg
|  |  |_ 📄 hero-image.png
|  |_ 📁 fonts
|     |_ 📄 custom-font.woff2
|
|_ 📁 config
|  |_ 📄 seo.ts
|  |_ 📄 navigation.ts
|
|_ 📄 next.config.js
|_ 📄 package.json
|_ 📄 tsconfig.json
|_ 📄 .env.local
|_ 📄 .gitignore

Now, let's break this down and see why each piece is crucial to your Next.js masterpiece.

The Heart of Your Next.js App: The app Directory

The app directory is where the magic happens. It's the core of your Next.js 13+ project, leveraging the new App Router:

📁 app
|_ 📁 (auth)
|  |_ 📁 login
|  |_ 📁 register
|_ 📁 dashboard
|_ 📁 api
|_ 📄 layout.tsx
|_ 📄 page.tsx

Route Grouping with (auth)

The (auth) folder is a clever way to group related routes without affecting the URL structure. It's perfect for organizing authentication-related pages.

// app/(auth)/login/page.tsx
export default function LoginPage() {
  return <h1>Welcome to the Login Page</h1>;
}

API Routes: Your Backend in Disguise

Keep your backend logic tidy in the api directory. Each file becomes an API route:

// app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  // Fetch users logic
  return NextResponse.json({ users: ['Alice', 'Bob'] });
}

Layouts and Pages: The Building Blocks of Your UI

Use layout.tsx to create consistent designs across pages:

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Each page.tsx represents a unique route in your application:

// app/page.tsx
export default function HomePage() {
  return <h1>Welcome to our awesome Next.js app!</h1>;
}

Components: Your Next.js LEGO Set

Think of components as LEGO bricks. Organized well, they're easy to find and fun to use:

📁 components
|_ 📁 ui
|_ 📁 forms
|_ 📁 layouts

UI Components: The Building Blocks

Create reusable UI elements that maintain consistency across your app:

// components/ui/Button.tsx
export default function Button({ children, onClick }) {
  return (
    <button onClick={onClick} className="bg-blue-500 text-white py-2 px-4 rounded">
      {children}
    </button>
  );
}

Form Components: Making Data Entry a Breeze

Encapsulate form logic for cleaner, more maintainable code:

// components/forms/LoginForm.tsx
import { useState } from 'react';
import Button from '../ui/Button';

export default function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      onSubmit(email, password);
    }}>
      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
      <Button type="submit">Log In</Button>
    </form>
  );
}

Layout Components: The Framework of Your UI

Create consistent page structures with reusable layout components:

// components/layouts/Header.tsx
import Link from 'next/link';

export default function Header() {
  return (
    <header>
      <nav>
        <Link href="/">Home</Link>
        <Link href="/dashboard">Dashboard</Link>
        <Link href="/profile">Profile</Link>
      </nav>
    </header>
  );
}

The Supporting Cast: lib, hooks, and types

These directories are the unsung heroes of your project:

lib: Your Utility Belt

Store helper functions and constants here:

// lib/utils.ts
export function formatDate(date: Date): string {
  return date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
}

// lib/constants.ts
export const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'https://api.example.com';

hooks: Custom React Superpowers

Create custom hooks to encapsulate complex logic:

// hooks/useUser.ts
import { useState, useEffect } from 'react';
import { fetchUser } from '../lib/api';

export function useUser(userId: string) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser(userId).then(userData => {
      setUser(userData);
      setLoading(false);
    });
  }, [userId]);

  return { user, loading };
}

types: TypeScript's Best Friend

Define your TypeScript interfaces and types:

// types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

// types/post.ts
export interface Post {
  id: string;
  title: string;
  content: string;
  authorId: string;
  createdAt: Date;
}

Styling Your Next.js Masterpiece

Keep your styles organized in the styles directory:

/* styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Your custom global styles here */
body {
  font-family: 'Arial', sans-serif;
}

/* styles/variables.css */
:root {
  --primary-color: #3490dc;
  --secondary-color: #ffed4a;
  --text-color: #333333;
}

Public Assets: The Face of Your App

The public directory is home to your static assets. Optimize images and use custom fonts to make your app shine:

import Image from 'next/image';

export default function Logo() {
  return <Image src="/images/logo.svg" alt="Company Logo" width={200} height={50} />;
}

Configuration: The Backbone of Your Project

Don't forget about these crucial files in your root directory:

// next.config.js
module.exports = {
  images: {
    domains: ['example.com'],
  },
  // Other Next.js config options
};

// .env.local
DATABASE_URL=postgresql://username:password@localhost:5432/mydb
NEXT_PUBLIC_API_URL=https://api.example.com

Pro Tips for Large-Scale Next.js Success

1. Embrace the App Router: It's not just new; it's a game-changer for performance and nested layouts.
2. Code Splitting is Your Friend: Use dynamic imports to keep your app snappy:

   import dynamic from 'next/dynamic';

   const DynamicComponent = dynamic(() => import('../components/HeavyComponent'));

1. Optimize Those Images: Next.js's Image component is like a personal trainer for your images:

   import Image from 'next/image';

   export default function Hero() {
     return <Image src="/hero-image.png" alt="Hero" width={1200} height={600} priority />;
   }

1. Server Components FTW: Use them to slash your client-side JavaScript:

   // This component will be rendered on the server by default in Next.js 13+
   export default async function UserProfile({ userId }) {
     const user = await fetchUser(userId);
     return <div>Welcome, {user.name}!</div>;
   }

1. API Routes for the Win: Keep your server-side logic secure and separated:

   // pages/api/posts.ts
   import type { NextApiRequest, NextApiResponse } from 'next';

   export default async function handler(req: NextApiRequest, res: NextApiResponse) {
     if (req.method === 'GET') {
       const posts = await fetchPosts();
       res.status(200).json(posts);
     } else {
       res.status(405).end(); // Method Not Allowed
     }
   }

Wrapping Up: Your Next.js Project, Organized and Ready to Scale

There you have it – a structure that'll make your large-scale Next.js project feel like a well-oiled machine. Remember, this isn't a one-size-fits-all solution. Feel free to tweak it to fit your project's unique needs.

By following this structure, you'll spend less time scratching your head over where things go and more time building awesome features. Your code will be cleaner, your team will be happier, and your project will scale like a dream.

So, what are you waiting for? Give this structure a spin in your next project. Your future self (and your teammates) will high-five you for it!

Happy coding, and may your Next.js projects always be organized and bug-free! 🚀

---

Remember, the key to a successful large-scale Next.js project isn't just in the initial setup – it's in how you maintain and evolve your structure as your project grows. Stay flexible, keep learning, and don't be afraid to refactor when needed. You've got this!

Comments

[Sheraz Manzoor]

Great written boy. I am Senior Software Engineer and I appreciate this structure. One minor thing I will suggest to improve, the components is a different thing and forms is a different.

For forms and big layouts, which are route related (means which are for a specific page) they should kept in modules directory..

And only reusable components should kept in components directory. That it. I just wanted to see how others structure this and what are you teaching to other.

With that minor improvement, I suggest all the juniors to follow this structure!!!

[Zakharov Vladyslav]

Where are components styles? I have a structure

components/
|__ component-name/
|_____ component-name.module.scss
|_____ index.tsx
|__ index.ts

in index.ts:

export * from ‘./component-name’

so after that I can import components like

import { ComponentName } from ‘@/components’;

[Prince Muel]

Barrel exports are easier to make but can increase your code import size. Also, they can leak client component code into server components and vice versa.

[Zakharov Vladyslav]

Thanks a lot for this. Never knew and never met explanations for it

[Mohammad Mahdi Bahrami]

I do it the same way! 😅

[Nikolai Lehbrink]

Nice article, but I think you should update the API Routes for the Win section @vyan, because that's not an API Route from Next.js 13+ :) It is more like:

// app/api/posts/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const posts = await fetchPosts();
  return NextResponse.json(posts);
}

[Vishal Yadav]

Thanks!

[Vitaliy Potapov]

Regarding to auth, we have an opposite structure - keep most pages in (authorized) dir and only login/register on the root level. This is because for all authorized pages we have a header in layout, but it is not shown on login/register pages:

|_ 📁 app
|  |_ 📁 (authorized)
|  |  |_ 📁 dashboard
|  |  |  |_ 📄 page.tsx
|  |  |_ 📄 layout.tsx
|  |_ 📁 login
|  |  |  |_ 📄 page.tsx
|  |  |  |_ 📄 layout.tsx

Could you advice how can we achieve the same with (auth) dir?

[Barack Okaka Obama]

Next is a very clean language.

[Thomas TS]

NextJS has JS in the name because is Javascript. And Javascript is a language.

Why bother with a Microsoft (evil) tool as Typescript if we have JSDoc?

[Bijay Das]

hey!!, this is exactly my structure

[Vishal Yadav]

Cool

[Michael Steven David]

Where would you likely put server action files? Would it be inside its own folder within the root folder or inside the lib?

[lwooden]

Great article! I did notice that you omitted an “actions” folder under lib, but this is probably because you are using /api as a backend instead of SAs. Additionally, you have reference components that are using client side hooks but you didn’t annotate the file like so: “use client”

[Ogbole Divine]

All these folders do they have extra price of coding within them?
If yes how do u write those and embed them on ur Next.js screen.....

Secondly can I use vs.code to work on a next.js app?
Can I also write them in pseudocode?