Contents (9)
- Thoughts on the FSD architecture
- introduction
- problem
- Problem 1. Layer of the Card component with request cancellation
- Problem 2. Where should I put the API? (Still thinking about it)
- Problem 3. Do you really need to put code that seems like it will only be used on a single page into entities?
- Conclusion on the problems
- organize
- finish
Thoughts on the FSD architecture
introduction
At my company, we build the frontend using the FSD architecture. This is my second FSD architecture project. Before actually implementing it myself, everyone assumes that dividing layers separates roles, ensuring dependencies flow unidirectionally, allowing any team member to quickly locate files, and making maintenance easier.
However, as always, deciding "where to place" a layer in practice is very difficult in itself. This article is a retrospective that honestly summarizes the changes in my judgment.
problem
Problem 1. Layer of the Card component with request cancellation
I created a Card component that performs the roles of [displaying payment request information] and [request cancellation action]. In this case, it seems like an appropriate separation to implement the payment request information display in the Entity layer and the request cancellation action in the Feature layer. However, I thought it was better to include the Card component itself in the Entity layer, so I implemented the cancellation as well within the Entities layer.
entities/ payment-request/ ui/ PaymentRequestCard.tsx ← The cancel button is here. model/ api/
The problem with the structure above is that it deviates from FSD principles. (If you object to this, I 100% agree that architecture does not have to be used strictly according to a fixed format!! I also believe that it should be used that way. However, I am speaking only in principle.) It would be better to focus on handling user actions in the features layer and representing business model units in entities.
So I changed it to fit the principles.
features/ cancel-payment-request/ ui/ CancelPaymentRequestButton.tsx model/ useCancelPaymentRequest.tsentities/ payment-request/ ui/ PaymentRequestCard.tsx ← Structure that receives buttons as props// Combination in widgets<PaymentRequestCard data={data} action={<CancelPaymentRequestButton id={data.id} />} // External injection/>After making these changes, the structure became one where the Cancel button position in the PaymentRequestCard component is determined by the layout, received via props, and rendered in the {action} slot. Since entities already have dependencies because they know in advance what action will come and where it will be placed, it felt like a contradiction within the FSD architectural hierarchy.
So, I thought it would be more natural to move the Card component to the Widget layer, so I did. That is because it represents both the action and the entity.
const PaymentRequestCard = ({ data }) => { const { cancel } = usePaymentRequest(data.id); return ( <Card> <CardContent>{data.title}</CardContent> <Button onClick={cancel}>Cancel request</Button> </Card> );};The final result is
Before change: entities/payment-request/ui/PaymentRequestCard.tsx
After change: widgets/payment-request-card/ui/PaymentRequestCard.tsx
It has changed like this. I think it is correct to move it to the widget layer when "data representation + action" are together.
If you feel that the code placement is odd while using an architecture, it is highly likely that you are not thinking in accordance with the architecture's intent. It goes without saying, but if it is a partitioned architecture, you should partition based on the functions and roles.
Problem 2. Where should I put the API? (Still thinking about it)
The FSD documentation ( I'm not sure if it's official, though, because personally, I disagree with many parts of it as it seems too focused on architecture) provides guidelines to place APIs within each layer to the functions most closely related to it. However,
Unlike the explanation in the FSD documentation, I grouped the APIs into Entities. This is because all CRUD APIs are closely related to Entities, and I thought that placing them in a location with even closer specific relationships would make them harder to find.
entities/ credit/ api/ index.ts fetchCreditXXX.ts postCreditXXX.ts keys/ getCreditOptions.ts ← queryOptions chargeCreditOptions.ts ← mutationOptions useCreditOptions.ts ← mutationOptionsAlso, the API layer shares the responsibility of converting all DTOs into Entity types used internally within the app. I thought it was much easier to manage because the DTO to Entity conversion process could be consolidated into a single Entity layer.
However, simply consolidating APIs into the Entity layer without any functional connection didn't seem to align well with the FSD architectural philosophy, so I wondered if there might be a better approach.
So, I considered moving the responsibility for converting DTOs to Entities to `queryOptions` and `queryMutation`, and moving all pure API call functions and endpoints to `/shared/api`. I thought this would allow us to maintain the original dependency orientation while further ensuring the Single Responsibility Principle and reusability of the `fetch` function.
shared/ api/ credits/ fetchCredit.ts ← Pure HTTP functions only postChargeCredit.ts postUseCredit.tsentities/ credit/ api/ getCreditOptions.ts ← queryOptionsfeatures/ charge-credit/ api/ chargeCreditOptions.ts ← mutationOptions use-credit/ api/ useCreditOptions.ts ← mutationOptions// entities/credit/api/getCreditOptions.tsexport const getCreditOptions = queryOptions({ queryFn: async () => { const dto = await fetchCredit(); return toCreditEntity(dto); // ← The conversion is here }});Implementing it this way clearly adheres to the principles of FSD. However, code acting as an Adaptor is scattered throughout, and its logic is hidden within `queryOptions`. Furthermore, tracing the direction of dependencies becomes complex.
So right now, I'm stuck in a dilemma. I think the inconvenience stems from the fact that the codebase isn't large enough yet to be split into FSD. I think I need to give this more thought to fit the current codebase.
To summarize, my thought process is as follows.
Initially, everything was consolidated into entities/credit/api → High domain cohesion but incompatible with FSD architectural philosophy
How about extracting pure HTTP communication functions into shared/api, separating options by layer, and assigning Entity responsibilities as well? → This is close to the principle, but the locations of DTO transformations become scattered.
Every time we solve one problem, another comes along, so we are in a trade-off relationship. Since we don't see any issues with consolidating everything into entities in the current state, option 1 seems like the correct answer. However, wouldn't option 2 become the answer later as the codebase grows?
Problem 3. Do you really need to put code that seems like it will only be used on a single page into entities?
The FSD architecture tutorial also specifies that code used on only one page should be placed in the page layer. However, the annoying part is that the tutorial also requires placing domain models in entities and actions in features. While separating into entities and features feels conceptually cleaner, the code that is actually clean and verifiable in practice is properly separated and placed in the page layer.
For example, let's say the "Balance Banner" is used only on the Credit page. However, it is most closely related to the Credit Entity. So, I arranged it as follows.
entities/ credit/ ui/ CreditBalanceBanner.tsx ← Balance banner CreditHistoryHeader.tsx ← History headerHowever, the balance banner is actually used on only one page and has never been reused even once. And it doesn't seem likely that it will be reused on other pages either. So, I actually moved the balance banner UI from entities to pages. I think this is a much better approach. There is no need to go out of your way to expose an API for "autocomplete" code that won't be reused, is there?
pages/ credit/ ui/ CreditPage.tsx CreditBalanceBanner.tsx ← Since I'm only using it here CreditHistoryHeader.tsxSo, I think this style of code is better. I even thought it would be fine to include APIs or hooks if necessary. However, I refrained from doing so because I felt that having APIs or hooks scattered everywhere would make the code harder to understand.
Conclusion on the problems
While grappling with these concerns, I realized that getting too trapped in architecture, the compulsion to separate things, or the obsession with a single responsibility significantly restricts my freedom of thought. The important thing is the big picture. Furthermore, we need to understand why FSD was created and how to utilize it effectively to solve that problem. I think I should focus more on the intention rather than getting bogged down in the methods. We always find ourselves worrying about the means when they are not the end, even if utilizing the means isn't actually the goal.
organize
situation | Initial judgment | result |
|---|---|---|
Card with a cancel button | Place cards on entities | Go to widgets. If data representation + action are together, move to a layer higher than Widget. |
Feature button injection | Separated by prop injection | → On the contrary, it becomes more complex and impairs readability |
Domain API Location | Planning to separate all CRUD operations from entities/credit/api into shared/api | Solving this brings with it the issue of DTO transformation location. It appears the correct answer will vary depending on the scale of the codebase. |
UI dedicated to specific pages | Place in entities/credit/ui | Components that cannot be reused are piling up in the Entity. It might be better to put them in the Page. |
finish
I actually don't prefer the FSD architecture. When I look at FSD architecture tutorials, it feels like they force a structure upon you. Perhaps that is why, for the past few years, I have even removed some layers entirely from the formula. Also, people often just take the FSD architecture idea and separate the layer names, numbers, and purposes to fit their company's code or philosophy.
The FSD architecture definitely seems like an architecture that could actually ruin a beginner's experience. You need to be able to flexibly borrow only parts of the architecture to take advantage of its strengths or adapt it to your code, but beginners often lack that ability. That is why it seems like an architecture designed for experts. An expert wouldn't always use these architectural rules strictly; instead, when necessary, they would likely borrow the philosophy and modify it to suit their own or their organization's preferences, allowing for more flexible usage.
