You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.mdx
+32-23Lines changed: 32 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,24 +2,24 @@
2
2
sidebar_position: 1
3
3
---
4
4
5
-
# Overview
5
+
# Overview{#overview}
6
6
7
-
**Feature-Sliced Design** (FSD) is an architectural methodology for scaffolding front-end applications. Simply put, it's a compilation of rules and conventions on organizing code. The main purpose of this methodology is to make the project more understandable and structured in the face of ever-changing business requirements.
7
+
**Feature-Sliced Design** (FSD) is an architectural methodology for scaffolding front-end applications. Simply put, it's a compilation of rules and conventions on organizing code. The main purpose of this methodology is to make the project more understandable and stable in the face of ever-changing business requirements.
8
8
9
-
Apart from a set of conventions, FSD is also a toolchain. We have a [linter][ext-steiger] to check your project's architecture, [folder generators][ext-tools]in CLI and IDEs, as well as a rich library of [examples][examples].
9
+
Apart from a set of conventions, FSD is also a toolchain. We have a [linter][ext-steiger] to check your project's architecture, [folder generators][ext-tools]through a CLI or IDEs, as well as a rich library of [examples][examples].
10
10
11
-
## Is it right for me?
11
+
## Is it right for me?{#is-it-right-for-me}
12
12
13
13
FSD can be implemented in projects and teams of any size. It is right for your project if:
14
14
15
15
- You're doing **frontend** (UI on web, mobile, desktop, etc.)
16
16
- You're building an **application**, not a library
17
17
18
-
And that's it! There are no restrictions on what programming language, UI framework or state manager you use. You can also adopt FSD incrementally, use it in monorepos, and scale to great lengths.
18
+
And that's it! There are no restrictions on what programming language, UI framework, or state manager you use. You can also adopt FSD incrementally, use it in monorepos, and scale to great lengths by breaking your app into packages and implementing FSD individually within them.
19
19
20
20
If you already have an architecture and you're considering a switch to FSD, make sure that the current architecture is **causing trouble** in your team. For example, if your project has grown too large and inter-connected to efficiently implement new features, or if you're expecting a lot of new members to join the team. If the current architecture works, maybe it's not worth changing. But if you do decide to migrate, see the [Migration][migration] section for guidance.
21
21
22
-
## Basic example
22
+
## Basic example{#basic-example}
23
23
24
24
Here is a simple project that implements FSD:
25
25
@@ -46,62 +46,62 @@ Folders inside `📂 pages` are called _slices_. They divide the layer by domain
46
46
47
47
Folders inside `📂 app`, `📂 shared`, and `📂 pages/article-reader` are called _segments_, and they divide slices (or layers) by technical purpose, i.e. what the code is for.
48
48
49
-
## Concepts
49
+
## Concepts{#concepts}
50
50
51
51
Layers, slices, and segments form a hierarchy like this:
52
52
53
53
<figure>
54
-
54
+
<p>Three pillars, labeled left to right as "Layers", "Slices", and "Segments" respectively.</p>
57
+
<p>Pictured above: three pillars, labeled left to right as "Layers", "Slices", and "Segments" respectively.</p>
58
58
<p>The "Layers" pillar contains seven divisions arranged top to bottom and labeled "app", "processes", "pages", "widgets", "features", "entities", and "shared". The "processes" division is crossed out. The "entities" division is connected to the second pillar "Slices" in a way that conveys that the second pillar is the content of "entities".</p>
59
59
<p>The "Slices" pillar contains three divisions arranged top to bottom and labeled "user", "post", and "comment". The "post" division is connected to the third pillar "Segments" in the same way such that it's the content of "post".</p>
60
60
<p>The "Segments" pillar contains three divisions, arranged top to bottom and labeled "ui", "model", and "api".</p>
61
61
</figcaption>
62
62
</figure>
63
63
64
-
### Layers
64
+
### Layers{#layers}
65
65
66
66
Layers are standardized across all FSD projects. You don't have to use all of the layers, but their names are important. There are currently seven of them (from top to bottom):
67
67
68
68
1. App\* — everything that makes the app run — routing, entrypoints, global styles, providers.
3. Pages — full pages or large parts of a page in nested routing scenarios.
70
+
3. Pages — full pages or large parts of a page in nested routing.
71
71
4. Widgets — large self-contained chunks of functionality or UI, usually delivering an entire use case.
72
-
5. Features — _reusable_ implementations of entire product features, i.e. actions that bring business value to the user.
72
+
5. Features — _reused_ implementations of entire product features, i.e. actions that bring business value to the user.
73
73
6. Entities — business entities that the project works with, like `user` or `product`.
74
-
7. Shared\* — reusable functionality, ideally detached from the specifics of the project/business.
74
+
7. Shared\* — reusable functionality, especially when it's detached from the specifics of the project/business, though not necessarily.
75
75
76
-
_\* — Layers App and Shared are made up of segments directly, while other layers are made up of slices that are then made up of segments._
76
+
_\* — these layers, App and Shared, unlike the other layers, don't have slices, and are made up of segments directly._
77
77
78
78
The trick with layers is that modules on one layer can only know about and import from modules from the layers strictly below.
79
79
80
-
### Slices
80
+
### Slices{#slices}
81
81
82
82
Next up are slices, which partition the code by business domain. You're free to choose any names for them, and create as many as you wish. Slices make your codebase easier to navigate by keeping logically related modules close together.
83
83
84
84
Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling.
85
85
86
-
### Segments
86
+
### Segments{#segments}
87
87
88
-
Slices, as well as layers App and Shared, consist of segments, and segments group your code by its purpose. Segment names are not constrained by standard, but there are several conventional names for the most common purposes:
88
+
Slices, as well as layers App and Shared, consist of segments, and segments group your code by its purpose. Segment names are not constrained by the standard, but there are several conventional names for the most common purposes:
89
89
90
90
-`ui` — self-explanatory
91
91
-`api` — also self-explanatory
92
92
-`model` — the data model: schemas, interfaces, stores, and business logic
93
93
-`lib` — library code that's only used within this slice
94
94
-`config` — configuration files and feature flags
95
95
96
-
Usually these segments are enough for most layers, you would only create your own segments in Shared or App, but this is not a rule that you have to obey.
96
+
Usually these segments are enough for most layers, you would only create your own segments in Shared or App, but this is not a rule.
97
97
98
-
## Advantages
98
+
## Advantages{#advantages}
99
99
100
100
-**Uniformity**
101
101
Since the structure is standardized, projects become more uniform, which makes onboarding new members easier for the team.
102
102
103
103
-**Stability in face of changes and refactoring**
104
-
A module on a layer cannot use other modules on the same layer, or the layers above.
104
+
A module on one layer cannot use other modules on the same layer, or the layers above.
105
105
This allows you to make isolated modifications without unforeseen consequences to the rest of the app.
106
106
107
107
-**Controlled reuse of logic**
@@ -111,19 +111,28 @@ Usually these segments are enough for most layers, you would only create your ow
111
111
-**Orientation to business and users needs**
112
112
The app is split into business domains and usage of the business language is encouraged in naming, so that you can do useful product work without fully understanding all other unrelated parts of the project.
113
113
114
-
## Incremental adoption
114
+
## Incremental adoption{#incremental-adoption}
115
115
116
-
If you have an existing codebase that you want to migrate to FSD, we suggest this strategy. We found it useful in our own migration experience.
116
+
If you have an existing codebase that you want to migrate to FSD, we suggest the following strategy. We found it useful in our own migration experience.
117
117
118
-
1. Start by slowly moving code module-by-module to the App and Shared layers to create a foundation. Usually, these layers are the smallest.
118
+
1. Start by slowly shaping up the App and Shared layers module-by-module to create a foundation. Usually, these layers are the smallest.
119
119
120
120
2. Distribute all of the existing UI across Widgets and Pages using broad strokes, even if they have dependencies that violate the rules of FSD.
121
121
122
122
3. Start gradually resolving import violations and also extracting Entities and possibly even Features.
123
123
124
124
It's advised to refrain from adding new large entities while refactoring or refactoring only certain parts of the project.
125
125
126
+
## Next steps {#next-steps}
127
+
128
+
-**Want to get a good grasp of how to think in FSD?** Check out the [Tutorial][tutorial].
129
+
-**Prefer to learn from examples?** We have a lot in the [Examples][examples] section.
130
+
-**Have questions?** Drop by our [Telegram chat][ext-telegram] and get help from the community.
0 commit comments