Skip to content

docs: add slice-groups documentation#906

Open
Gaic4o wants to merge 2 commits intofeature-sliced:mainfrom
Gaic4o:docs-slice-groups
Open

docs: add slice-groups documentation#906
Gaic4o wants to merge 2 commits intofeature-sliced:mainfrom
Gaic4o:docs-slice-groups

Conversation

@Gaic4o
Copy link
Copy Markdown
Contributor

@Gaic4o Gaic4o commented Mar 14, 2026

Background

Add a dedicated documentation page for Slice groups.
This concept was briefly mentioned on the existing Slices and segments page, but lacked a more detailed explanation.

Motivation

The current Slices and segments page only introduces slice groups briefly, without explaining when to use them, what rules apply, or what pitfalls to avoid.

Since slice groups are a recurring topic in the FSD community, this dedicated page helps clarify:

  • what a slice group is (and what it is not)
  • the core rules behind it
  • when introducing it makes sense
  • concrete examples in entities and pages
  • anti-patterns such as placing shared code at the group level

I placed the page under Reference, after Slices and segments and before Public API, because it felt closer to a structural concept than to a usage guide.

For now, I only added Korean and English versions. If this direction is approved, I’ll prepare translations for the other supported languages as a follow-up.

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 14, 2026

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
pr-fsd ✅ Ready (View Log) Visit Preview ccbef8e

Copy link
Copy Markdown
Contributor

@Solant Solant left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a feeling that this is a bit verbose for the purpose of slice groups


> **Rule 1: A group folder is just a structural folder**
>
> A group folder does not have its own segments like `model`, `ui`, or `api`. It also does not have a public API like `index.ts`.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's do a very strict ban on any code reuse instead, so the message is very clear, just like in https://fsd.how/docs/reference/slices-segments/#slice-groups

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I agree. I’ll rephrase this more strictly. Also, I think if we include the image from the slice groups section in the docs, we can probably shorten or omit some of the explanation I added here.

<FileTree>
- pages/
- order/ slice group
- orderCreate/ slice
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: do we need to remove prefix part from the grouped slices? like

- pages/
  - order/
    - create/

or

- pages/
  - order/
    - order-create/

?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’ll go with create/ here, since the parent group already provides that context.

Not all slices need to be placed in a group.
Slices like `user/`, whose meaning is clear on its own, can remain without a group.

### pages — domain-based page grouping
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is definitely new; I've never used this pattern for pages 🤔

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to show that slice groups may also be used in the pages layer. I included this as an example, not as a default pattern.

This structure is helpful when there are many pages on the same topic, such as list, detail, create, and edit.
Opening just one parent folder lets you see all related pages together.

### Can it be used in features too?
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think slice groups were originally introduced to primarily tackle feature layers (I think in 2.0), so it is strange to ban it like this

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point. I agree this should not be framed as a ban. As I mentioned before, grouping in the features layer can be less obvious because a feature often spans multiple entities and flows. So rather than treating it as exceptional, I think it would be better to clarify that slice groups can work in some cases but not in others, depending on whether there is a natural grouping criterion. I’m thinking of reflecting that in the document with examples of cases where grouping is a good fit and where it is not.

Therefore, it is better to view slice groups in features as an option to be used exceptionally.
If there is no natural grouping criterion, it is better not to force their introduction.

## Patterns to avoid
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to ban even the idea of doing code share on the slice-group level in the first lines of the document (not literally, but you get the idea).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you mean. I’ll make that explicit in the opening section, and then I think the later explanation can be removed.

For example, group only cases where viewing them together is natural, like `payment/invoice` and `payment/receipt`,
while slices that are independently understood like `user` and `settings` can remain without a group.

### Is it okay if the group name is included in the import path?
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it the question regarding absolute vs. relative imports?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant that part as a note about absolute vs. relative imports, but I agree it doesn’t really belong here. I’ll remove it. Thanks for catching that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants