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 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