Pattern to split Next.js app into modules/domain contexts

[michaelhays]

Problem

Hello, I'd like to be able to split my source code into modules/domain contexts, like so:

src/
├── auth/
│   ├── api/
│   │   ├── login.ts
│   │   ├── logout.ts
│   │   └── signup.ts
│   ├── components/
│   │   ├── LoginForm.tsx
│   │   └── SignupForm.tsx
│   └── pages/
│       ├── login.tsx
│       └── signup.tsx
├── core/
│   ├── components/
│   │   ├── Form.tsx
│   │   └── LabeledTextField.tsx
│   ├── layouts/
│   |   └── DefaultLayout.tsx
|   └── pages/
│       ├── _app.tsx
│       ├── _document.tsx
│       ├── 404.tsx
│       └── index.tsx
├── posts/
│   ├── api/
│   │   ├── createPost.ts
│   │   ├── getPost.ts
│   │   └── getPosts.ts
│   ├── components/
│   │   ├── Post.tsx
│   │   └── Posts.tsx
│   └── pages/
│       └── posts/
│           ├── index.tsx
│           └── [slug].tsx
└── users/
    ├── api/
    │   └── getUser.ts
    ├── components/
    │   └── User.tsx
    └── pages/
        └── users/
            └── [id].tsx

Is there any known pattern for accomplishing something like this?

This is purely an organizational change; the application would still be built as one cohesive unit. In my experience, this kind of organization is necessary once your codebase grows above ~50k lines of code.

The Next.js automatic file-based routing would still work as expected, combining pages/ and api/ for all modules, and it would be up to the user to ensure that there are no conflicts (i.e. two different modules defining the same page route).

Examples

Blitz.js (pre framework-agnostic pivot) supports this by default.

The file structure nested inside app/ can be anything you want, but we recommend the following:

• First layer folders to be a "domain context", like core/, projects/, users/, billing/, etc.
• All other folders like components/ and hooks/ go inside one of the above domain context folders

Existing issues/discussions

I couldn't find much in Next.js issues or discussions that addresses this. #6040 is related, but focuses on complete build separation rather than simple organizational changes:

Each part should be deployable separately

Explored Solutions

The article Dividing Your App Into Modules describes the issue well, and explores a few options:

1. Custom Page Extensions + Rewrites + importing/exporting
   This works, but it's very tedious to maintain the original structure in pages/ and api/ for the importing.
2. Multi Zones
   Much like Feasibility of micro frontends #6040, this treats each module as a separate build context.

I also considered using Turborepo, but this also treats each module as a separate Next.js application.

[anthonysidesap]

Problem

Hello, I'd like to be able to split my source code into modules/domain contexts, like so:

src/
├── auth/
│   ├── api/
│   │   ├── login.ts
│   │   ├── logout.ts
│   │   └── signup.ts
│   ├── components/
│   │   ├── LoginForm.tsx
│   │   └── SignupForm.tsx
│   └── pages/
│       ├── login.tsx
│       └── signup.tsx
├── core/
│   ├── components/
│   │   ├── Form.tsx
│   │   └── LabeledTextField.tsx
│   ├── layouts/
│   |   └── DefaultLayout.tsx
|   └── pages/
│       ├── _app.tsx
│       ├── _document.tsx
│       ├── 404.tsx
│       └── index.tsx
├── posts/
│   ├── api/
│   │   ├── createPost.ts
│   │   ├── getPost.ts
│   │   └── getPosts.ts
│   ├── components/
│   │   ├── Post.tsx
│   │   └── Posts.tsx
│   └── pages/
│       └── posts/
│           ├── index.tsx
│           └── [slug].tsx
└── users/
    ├── api/
    │   └── getUser.ts
    ├── components/
    │   └── User.tsx
    └── pages/
        └── users/
            └── [id].tsx

Is there any known pattern for accomplishing something like this?

This is purely an organizational change; the application would still be built as one cohesive unit. In my experience, this kind of organization is necessary once your codebase grows above ~50k lines of code.

The Next.js automatic file-based routing would still work as expected, combining pages/ and api/ for all modules, and it would be up to the user to ensure that there are no conflicts (i.e. two different modules defining the same page route).

Examples

Blitz.js (pre framework-agnostic pivot) supports this by default.

The file structure nested inside app/ can be anything you want, but we recommend the following:

• First layer folders to be a "domain context", like core/, projects/, users/, billing/, etc.
• All other folders like components/ and hooks/ go inside one of the above domain context folders

Existing issues/discussions

I couldn't find much in Next.js issues or discussions that addresses this. #6040 is related, but focuses on complete build separation rather than simple organizational changes:

Each part should be deployable separately

Explored Solutions

The article Dividing Your App Into Modules describes the issue well, and explores a few options:

1. Custom Page Extensions + Rewrites + importing/exporting
   This works, but it's very tedious to maintain the original structure in pages/ and api/ for the importing.
2. Multi Zones
   Much like Feasibility of micro frontends #6040, this treats each module as a separate build context.

I also considered using Turborepo, but this also treats each module as a separate Next.js application.

Yes its can be done its the new meta verse coming .. anything is possible

[michaelhays]

lol thanks

[Jero786]

there is some news? I'm interested in this feature/module organization as well.

[eddsaura]

Hey we are interested in a similar solution, actually we've find the same dead end, multizones and turborepo.

[michaelhays]

For anyone still looking for a solution to this, I've been using this project structure with a lot of success for a ~50k LOC project:

src/
├── modules/
│   ├── Contact/
│   │   ├── create.ts
│   │   ├── delete.ts
│   │   ├── list.ts
│   │   ├── Table.tsx
│   │   └── update.ts
│   └── User/
│       ├── create.ts
│       ├── delete.ts
│       ├── list.ts
│       ├── Table.tsx
│       └── update.ts
├── pages/
│   ├── contacts.tsx
│   └── users.tsx
├── ui/
│   ├── Button.tsx
│   └── Table.tsx
└── utils/

src/modules/ contains the vast majority of the business logic and feature-specific code.

src/pages/ is mostly just used for the file-based routing, and more-or-less just serves to import components from src/modules/.

[Mahoo12138]

Any new progress?