Skip to main content

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.

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 pages layer in the FSD structure to avoid conflicts with the NextJS pages folder. You can rename the pages 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. You should still also add the pages folder to the root, because the App router is compatible with the Pages router.

β”œβ”€β”€ app                # NextJS app folder
β”œβ”€β”€ pages # Stub NextJS pages folder
β”‚ β”œβ”€β”€ README.md # Description of why this folder exists
β”œβ”€β”€ src
β”‚ β”œβ”€β”€ app # FSD app folder
β”‚ β”œβ”€β”€ entities
β”‚ β”œβ”€β”€ features
β”‚ β”œβ”€β”€ pages # FSD app folder
β”‚ β”œβ”€β”€ shared
β”‚ β”œβ”€β”€ widgets

Open in StackBlitz

See also​