Usage with NextJS

It is possible to implement FSD in a NextJS project, but conflicts arise due to differences between the requirements for the NextJS project structure and the principles of FSD in two points:

Routing files in the pages layer
Conflict or absence of the app layer in NextJS

Conflict between FSD and NextJS on `pages` layer

NextJS suggests using the pages folder to define application routes. NextJS expects files in the pages folder to match URLs. This routing mechanism does not correspond to the FSD concept, since it is not possible to maintain a flat slice structure in such a routing mechanism.

Moving the `pages` folder of NextJS to the root folder of the project (recommended)

The approach is to move the pages NextJS folder to the root folder of the project and import the FSD pages into the pages NextJS folder. This saves the FSD project structure inside the src folder.

├── pages              # NextJS pages folder
├── src
│   ├── app
│   ├── entities
│   ├── features
│   ├── pages          # FSD pages folder
│   ├── shared
│   ├── widgets

Renaming the `pages` layer within the FSD structure

Another way to solve the problem is to rename the app layer in the FSD structure to avoid conflicts with the NextJS pages folder. You can rename the app layer in FSD to views. In that way, the structure of the project in the src folder is preserved without contradiction with the requirements of NextJS.

├── app
├── entities
├── features
├── pages              # NextJS pages folder
├── views              # Renamed FSD pages folder
├── shared
├── widgets

Keep in mind that it's highly recommended to document this rename prominently in your project's README or internal documentation. This rename is a part of your "project knowledge".

The absence of the `app` folder in NextJS

In NextJS below version 13, there is no explicit app folder, instead NextJS provides the _app.tsx file, which plays the role of a wrapping component for all project pages.

Importing app functionality to `pages/_app.tsx` file

To solve the problem of missing the app folder in the NextJS structure, you can create an App component inside the app layer and import the App component into pages/_app.tsx so that NextJS can work with it. For example:

// app/providers/index.tsx

const App = ({ Component, pageProps }: AppProps) => {
  return (
    <Provider1>
      <Provider2>
        <BaseLayout>
            <Component {...pageProps} />
        </BaseLayout>
      </Provider2>
    </Provider1>
  );
};

export default App;

Then you can import the App component and global project styles into pages/_app.tsx as follows:

// pages/_app.tsx

import 'app/styles/index.scss'

export { default } from 'app/providers';

Dealing with App Router

App Router has become stable in NextJS version 13.4. App Router allows you to use the app folder for routing instead of the pages folder. To comply with the principles of FSD, you should treat the NextJS app folder in the same way as recommended to resolve a conflict with the NextJS pages folder.

The approach is to move the NextJS app folder to the root folder of the project and import the FSD pages into the NextJS app folder. This saves the FSD project structure inside the src folder.

├── app                # NextJS app folder
├── src
│   ├── app            # FSD app folder
│   ├── entities
│   ├── features
│   ├── pages
│   ├── shared
│   ├── widgets

Usage with NextJS

Conflict between FSD and NextJS on pages layer

Moving the pages folder of NextJS to the root folder of the project (recommended)

Renaming the pages layer within the FSD structure

The absence of the app folder in NextJS

Importing app functionality to pages/_app.tsx file