Next.js Project Structure: Folder Organization Best Practices

Next.js project structure decisions made early affect every build, deploy, and developer onboarding that follows. The App Router's file-system routing gives you powerful organizational primitives — private folders, route groups, layouts, and parallel routes — but without a consistent structure, these tools create confusion instead of clarity.

This guide covers proven patterns for organizing Next.js applications, from solo projects to enterprise monorepos. You'll learn where to put files, how to use App Router conventions effectively, and which patterns scale.

The Minimal Starter: What Next.js Gives You

When you run npx create-next-app@latest, you get a bare-bones structure: pages/ (or app/ if using the App Router), public/, styles/, and config files like next.config.js. This is intentionally minimal to avoid imposing opinions. However, for any real project, this flat layout quickly becomes unmanageable. The pages/ directory (or app/ directory) is the heart of routing, but dumping all components, utilities, and API routes there is a recipe for disaster. The default structure is a starting point, not a production-ready architecture. You must extend it with a logical separation of concerns.

npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app
tree -L 2 -I node_modules

The Core Principle: Separation by Feature, Not by Type

The most common mistake beginners make is grouping files by type: components/, utils/, hooks/, types/. This works for tiny apps but fails at scale because related code is scattered across folders. Instead, organize by feature or domain. For example, a UserProfile feature would have its own folder containing the component, its styles, its tests, its hooks, and its API calls. This makes it easy to locate all code related to a feature, simplifies deletion or replacement, and reduces merge conflicts because teams work on different features. The top-level folders become features/, shared/, lib/, and config/. This is often called the 'feature-first' or 'domain-driven' structure.

my-app/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   └── SignupForm.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── api/
│   │   │   └── authApi.ts
│   │   ├── types/
│   │   │   └── auth.ts
│   │   └── index.ts
│   └── dashboard/
│       ├── components/
│       │   ├── DashboardLayout.tsx
│       │   └── StatsCard.tsx
│       ├── hooks/
│       │   └── useDashboardData.ts
│       └── api/
│           └── dashboardApi.ts
├── shared/
│   ├── ui/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   └── Modal/
│   │       └── ...
│   └── lib/
│       └── formatDate.ts
├── pages/
│   ├── index.tsx
│   ├── login.tsx
│   └── dashboard.tsx
└── ...

The `pages/` Directory: Keep It Thin

The pages/ directory (or app/ in App Router) should only contain route files that are thin wrappers. Each page file should import a feature component and pass props. Never put business logic, data fetching, or complex UI directly in a page file. This keeps routing concerns separate from feature logic. For example, pages/dashboard.tsx should just render <DashboardPage /> from features/dashboard/. This also makes it easy to test pages in isolation and swap out features without touching routing. If you use Next.js API routes, keep them in pages/api/ but again, keep them thin — delegate to service functions in features/ or lib/.

import { GetServerSideProps } from 'next';
import { DashboardPage } from '@/features/dashboard';
import { getDashboardData } from '@/features/dashboard/api';

interface DashboardProps {
  data: DashboardData;
}

export default function Dashboard({ data }: DashboardProps) {
  return <DashboardPage data={data} />;
}

export const getServerSideProps: GetServerSideProps<DashboardProps> = async () => {
  const data = await getDashboardData();
  return { props: { data } };
};

The `shared/` Directory: Reusable UI and Utilities

The shared/ folder contains code that is used across multiple features. This includes UI primitives (Button, Input, Modal), layout components (Header, Footer), utility functions (date formatting, validation), and custom hooks that are not feature-specific. Each shared UI component should be a self-contained folder with its component file, styles, tests, and an index.ts barrel export. This makes components easy to find, test, and reuse. Avoid putting feature-specific logic in shared — that's what feature folders are for. Keep shared small and generic; if a component starts accumulating feature-specific props, it's time to move it into a feature.

import React from 'react';

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
}

export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  size = 'md',
  children,
  ...props
}) => {
  const baseClasses = 'rounded font-semibold focus:outline-none focus:ring-2';
  const variantClasses = {
    primary: 'bg-blue-600 text-white hover:bg-blue-700',
    secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
    danger: 'bg-red-600 text-white hover:bg-red-700',
  };
  const sizeClasses = {
    sm: 'px-3 py-1.5 text-sm',
    md: 'px-4 py-2 text-base',
    lg: 'px-6 py-3 text-lg',
  };

  return (
    <button
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}
      {...props}
    >
      {children}
    </button>
  );
};

The `lib/` Directory: Pure Logic and Configuration

The lib/ folder holds pure functions, configuration, and third-party integrations that are not tied to any feature. Examples: API client setup (Axios instance), database connection, authentication helpers, environment variable parsing, and constants. This folder should have minimal dependencies on React or Next.js — it's the 'backend' of your frontend. Keep it flat or group by concern (e.g., lib/api/, lib/db/, lib/constants/). Avoid putting React hooks or components here; those belong in shared/ or features/. The lib/ folder is also where you put utility functions that are used across features, like formatCurrency or validateEmail.

import axios from 'axios';

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json',
  },
});

apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('authToken');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      // Redirect to login
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export default apiClient;

The `public/` Directory: Static Assets Only

The public/ folder is for static assets that are served directly by the web server: images, fonts, robots.txt, favicon, and other files that don't need processing. Next.js automatically serves files from public/ at the root URL. For example, public/logo.png is accessible at /logo.png. Do not put source code, compiled files, or anything that needs to be imported here. For images that are used in components, consider using the next/image component with a remote URL or placing them in public/images/. Organize by type: public/images/, public/fonts/, public/icons/. Avoid deep nesting.

tree public/ -L 2

The `styles/` Directory: Global and Module CSS

Next.js supports global CSS and CSS Modules. The styles/ folder typically contains globals.css for global styles (reset, fonts, CSS variables) and module CSS files for component-specific styles. However, with the rise of Tailwind CSS and CSS-in-JS, many projects no longer use a dedicated styles/ folder. If you use Tailwind, you only need globals.css for Tailwind directives. If you use CSS Modules, co-locate the .module.css file with the component in its feature folder, not in a global styles/ folder. This follows the co-location principle: keep styles close to the component they style.

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  body {
    @apply bg-gray-50 text-gray-900 antialiased;
  }
}

@layer components {
  .btn-primary {
    @apply bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700;
  }
}

The `types/` Directory: Shared TypeScript Types

If your project uses TypeScript (and it should), you need a place for shared types and interfaces. The types/ folder at the root is for types that are used across multiple features, such as API response types, user types, or global enums. Feature-specific types should live inside the feature folder (e.g., features/auth/types/auth.ts). This keeps types close to where they are used and reduces import complexity. Export all shared types from an index.ts barrel file. Avoid putting types in lib/ or shared/ unless they are truly generic.

export interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user';
  createdAt: string;
}

export interface AuthResponse {
  user: User;
  token: string;
}

export type LoginCredentials = {
  email: string;
  password: string;
};

The `tests/` Directory: Testing Strategy

Testing is non-negotiable. The tests/ folder at the root is for integration and end-to-end tests (e.g., Playwright, Cypress). Unit tests should be co-located with the component or function they test, using the .test.tsx or .spec.ts suffix. This co-location makes it obvious when a file lacks tests and ensures tests are deleted when the source is deleted. For shared utilities, place tests in a __tests__/ folder inside lib/ or alongside the utility file. Configure Jest or Vitest to pick up files with .test. pattern. Avoid a separate __tests__/ folder at the root for unit tests — it disconnects tests from code.

import { render, screen, fireEvent } from '@testing-library/react';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('renders email and password fields', () => {
    render(<LoginForm />);
    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });

  it('calls onSubmit with credentials', () => {
    const handleSubmit = jest.fn();
    render(<LoginForm onSubmit={handleSubmit} />);
    fireEvent.change(screen.getByLabelText(/email/i), { target: { value: 'test@test.com' } });
    fireEvent.change(screen.getByLabelText(/password/i), { target: { value: 'password123' } });
    fireEvent.click(screen.getByRole('button', { name: /log in/i }));
    expect(handleSubmit).toHaveBeenCalledWith({
      email: 'test@test.com',
      password: 'password123',
    });
  });
});

The `config/` Directory: Environment and App Config

The config/ folder holds configuration files that are not environment variables but are still project-wide settings. Examples: config/site.ts for site metadata (title, description, URL), config/navigation.ts for navigation links, config/seo.ts for default SEO settings. This separates configuration from logic and makes it easy to find and change settings without digging through code. Environment variables should still go in .env.local and be accessed via lib/constants/env.ts. The config/ folder is for static, non-sensitive configuration that is committed to the repo.

export const siteConfig = {
  name: 'TheCodeForge',
  description: 'Production-focused technical blog',
  url: 'https://thecodeforge.io',
  ogImage: 'https://thecodeforge.io/og.jpg',
  links: {
    twitter: 'https://twitter.com/thecodeforge',
    github: 'https://github.com/thecodeforge',
  },
};

export type SiteConfig = typeof siteConfig;

The `hooks/` Directory: Custom React Hooks

Custom hooks that are shared across multiple features belong in a top-level hooks/ folder. Feature-specific hooks should stay in the feature folder. The hooks/ folder is for hooks like useDebounce, useLocalStorage, useMediaQuery, or useIntersectionObserver. These are generic enough to be used anywhere. Keep each hook in its own file, named after the hook (e.g., useDebounce.ts). Export from an index.ts barrel. Avoid putting hooks that depend on a specific feature's types or API here — that's a sign they should be in the feature folder.

import { useState, useEffect } from 'react';

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => {
      clearTimeout(handler);
    };
  }, [value, delay]);

  return debouncedValue;
}

Putting It All Together: A Production-Ready Structure

Here's the final recommended structure for a Next.js project using the Pages Router. Adjust for App Router by replacing pages/ with app/ and using layout.tsx and page.tsx. The key is consistency: every team member should understand where to put new code. Use a CONTRIBUTING.md to document the structure. Enforce it with ESLint rules (e.g., no imports from features/ into other features except through shared). This structure scales to hundreds of pages and dozens of developers. It's not perfect for every project, but it's a proven starting point that avoids the most common pitfalls.

my-app/
├── config/
│   ├── site.ts
│   └── navigation.ts
├── features/
│   ├── auth/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── types/
│   │   └── index.ts
│   └── dashboard/
│       └── ...
├── hooks/
│   ├── useDebounce.ts
│   └── useLocalStorage.ts
├── lib/
│   ├── api/
│   │   └── client.ts
│   ├── constants/
│   │   └── env.ts
│   └── utils/
│       └── formatDate.ts
├── pages/
│   ├── api/
│   │   └── auth.ts
│   ├── _app.tsx
│   ├── index.tsx
│   ├── login.tsx
│   └── dashboard.tsx
├── public/
│   ├── images/
│   └── favicon.ico
├── shared/
│   ├── ui/
│   │   ├── Button/
│   │   └── Modal/
│   └── layout/
│       ├── Header.tsx
│       └── Footer.tsx
├── styles/
│   └── globals.css
├── tests/
│   └── e2e/
│       └── login.spec.ts
├── types/
│   ├── user.ts
│   └── index.ts
├── next.config.js
├── tsconfig.json
└── package.json