+
@@ -41,7 +41,7 @@ This methodology is not tied to a particular stack — it can be used for web or
To show off that your project uses FSD, you can use the GitHub topic `feature-sliced` and one of the following badges:
-[![Feature-Sliced Design][shields-fsd-white]](https://feature-sliced.design/) [![Feature-Sliced Design][shields-fsd-pain]](https://feature-sliced.design/) [![Feature-Sliced Design][shields-fsd-domain]](https://feature-sliced.design/) [![Feature-Sliced Design][shields-fsd-feature]](https://feature-sliced.design/)
+[![Feature-Sliced Design][shields-fsd-white]](https://feature-sliced.github.io/documentation/) [![Feature-Sliced Design][shields-fsd-pain]](https://feature-sliced.github.io/documentation/) [![Feature-Sliced Design][shields-fsd-domain]](https://feature-sliced.github.io/documentation/) [![Feature-Sliced Design][shields-fsd-feature]](https://feature-sliced.github.io/documentation/)
[shields-fsd-white]: https://img.shields.io/badge/Feature--Sliced-Design?style=for-the-badge&labelColor=262224&color=F2F2F2&logoWidth=10&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAaCAYAAAC3g3x9AAAACXBIWXMAAALFAAACxQGJ1n/vAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAA/SURBVHgB7dKxCgAgCIThs/d/51JoNQIdDrxvqMXlR4FmFs92KDIX/wI7JSdDN+eHtkxIycnQvMNW8hN/crsDc5QgGX9NvT0AAAAASUVORK5CYII=
@@ -55,28 +55,28 @@ To show off that your project uses FSD, you can use the GitHub topic `feature-sl
```markdown
White:
-[![Feature-Sliced Design][shields-fsd-white]](https://feature-sliced.design/)
+[![Feature-Sliced Design][shields-fsd-white]](https://feature-sliced.github.io/documentation/)
[shields-fsd-white]: https://img.shields.io/badge/Feature--Sliced-Design?style=for-the-badge&labelColor=262224&color=F2F2F2&logoWidth=10&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAaCAYAAAC3g3x9AAAACXBIWXMAAALFAAACxQGJ1n/vAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAA/SURBVHgB7dKxCgAgCIThs/d/51JoNQIdDrxvqMXlR4FmFs92KDIX/wI7JSdDN+eHtkxIycnQvMNW8hN/crsDc5QgGX9NvT0AAAAASUVORK5CYII=
----
Pain (red):
-[![Feature-Sliced Design][shields-fsd-pain]](https://feature-sliced.design/)
+[![Feature-Sliced Design][shields-fsd-pain]](https://feature-sliced.github.io/documentation/)
[shields-fsd-pain]: https://img.shields.io/badge/Feature--Sliced-Design?style=for-the-badge&labelColor=262224&color=F2F2F2&logoWidth=10&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAaCAYAAAC3g3x9AAAACXBIWXMAAALFAAACxQGJ1n/vAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAABHSURBVHgB7dKxCQAgDETR08ZNHNBBHNBNrBQFuyCCKQK5V6QMfBJAWVij5zLwKbW6d0VYx2TZyXnBKxvEZJnDx2bylf1kdRM6tiAZsruQ/QAAAABJRU5ErkJggg==
----
Domain (blue):
-[![Feature-Sliced Design][shields-fsd-domain]](https://feature-sliced.design/)
+[![Feature-Sliced Design][shields-fsd-domain]](https://feature-sliced.github.io/documentation/)
[shields-fsd-domain]: https://img.shields.io/badge/Feature--Sliced-Design?style=for-the-badge&color=F2F2F2&labelColor=262224&logoWidth=10&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAaCAYAAAC3g3x9AAAACXBIWXMAAALFAAACxQGJ1n/vAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAABISURBVHgB7dKxCQAgDETR0w2cws0cys2cwhEUBbsggikCuVekDHwSQFlYo7Q+8KnmtHdFWMdk2cl5wSsbxGSZw8dm8pX9ZHUTMBUgGU2F718AAAAASUVORK5CYII=
----
Feature (green):
-[![Feature-Sliced Design][shields-fsd-feature]](https://feature-sliced.design/)
+[![Feature-Sliced Design][shields-fsd-feature]](https://feature-sliced.github.io/documentation/)
[shields-fsd-feature]: https://img.shields.io/badge/Feature--Sliced-Design?style=for-the-badge&labelColor=262224&color=F2F2F2&logoWidth=10&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAaCAYAAAC3g3x9AAAACXBIWXMAAALFAAACxQGJ1n/vAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAABISURBVHgB7dKxCQAgDETR00EcwYEc0IEcwUUUBbsggikCuVekDHwSQFlYo/Y88KmktndFWMdk2cl5wSsbxGSZw8dm8pX9ZHUTdIYgGbPdU2QAAAAASUVORK5CYII=
```
@@ -112,7 +112,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 Sergey Sova 📝 📖 💡 🤔 📆 💬 🚇 🔬 📋 ✅ 📢 🚧 |
+ Sergey Sova 📝 📖 💡 🤔 📆 💬 🚇 🔬 📋 ✅ 📢 🚧 |
 Ilya Azin 📖 💡 🤔 📆 💬 👀 🚇 📓 🎨 ✅ 📢 🚧 |
 Rin 🦊🪐😈 Akaia 📖 🖋 🤔 💬 🌍 📢 🚧 🔬 |
 Alexander Khoroshikh 📖 🤔 💬 👀 🔧 🛡️ 📢 ✅ 🚧 |
diff --git a/babel.config.js b/babel.config.js
deleted file mode 100644
index dd249ac168..0000000000
--- a/babel.config.js
+++ /dev/null
@@ -1,3 +0,0 @@
-module.exports = {
- presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
-};
diff --git a/blog/2022-06-04-rebranding.md b/blog/2022-06-04-rebranding.md
index abe4bf384c..345116bb99 100644
--- a/blog/2022-06-04-rebranding.md
+++ b/blog/2022-06-04-rebranding.md
@@ -8,12 +8,14 @@ authors:
url: https://github.com/azinit
image_url: https://github.com/azinit.png
tags: [brand, promo]
-image: https://feature-sliced.design/img/blog/rebranding-stable.png
+image: https://feature-sliced.github.io/documentation/img/blog/rebranding-stable.png
hide_table_of_contents: false
---
+import useBaseUrl from "@docusaurus/useBaseUrl";
+
| primary (#29BEDC, #517AED) |
-  |
+ ![logo-primary]({useBaseUrl("/img/brand/logo-primary.png")}){kind=logo} |
Preferred in most cases | |
| flat (#3193FF) |
-  |
+ ![logo-flat]({useBaseUrl("/img/brand/logo-flat.png")}){kind=logo} |
For one-color context | |
| monochrome (#FFF) |
-  |
+ ![logo-monocrhome]({useBaseUrl("/img/brand/logo-monochrome.png")}){kind=logo} |
For grayscale context | |
| square (#3193FF) |
-  |
+ ![logo-square]({useBaseUrl("/img/brand/logo-square.png")}){kind=logo} |
For square boundaries |
+ ![logo-primary]({useBaseUrl("/img/blog/rebranding-stable.png")})
+ ![post-cover]({useBaseUrl("/img/blog/international-community.png")})
-
+![banner-primary]({useBaseUrl("/img/brand/banner-primary.jpg")})
+![banner-monochrome]({useBaseUrl("/img/brand/banner-monochrome.jpg")})
## Social Preview
@@ -78,4 +80,3 @@ Work in progress...
- [Discussion (github)](https://github.com/feature-sliced/documentation/discussions/399)
- [History of development with references (figma)](https://www.figma.com/file/RPphccpoeasVB0lMpZwPVR/FSD-Brand?node-id=0%3A1)
-- [Rebranding demo](https://rebrand-sliced.netlify.app/en/)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx b/i18n/en/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
index 204c8e329c..6323490ad0 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
+++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
@@ -1,5 +1,6 @@
---
-sidebar_position: 3
+# sidebar_position: 3
+unlisted: true
---
# Decomposition cheatsheet
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md
index daecfad948..2f9b4bda5b 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md
@@ -13,7 +13,7 @@ You can ask your question in our [Telegram chat][telegram], [Discord community][
### Is there a toolkit or a linter?
-There is an official ESLint config — [@feature-sliced/eslint-config][eslint-config-official], and an ESLint plugin — [@conarti/eslint-plugin-feature-sliced][eslint-plugin-conarti], created by Aleksandr Belous, a community member. You're welcome to contribute to these projects or start your own!
+Yes! We have a linter called [Steiger][ext-steiger] to check your project's architecture and [folder generators][ext-tools] through a CLI or IDEs.
### Where to store the layout/template of pages?
@@ -24,7 +24,7 @@ If you need plain markup layouts, you can keep them in `shared/ui`. If you need
### What is the difference between a feature and an entity?
-An _entity_ is a real-life concept that your app is working with. A _feature_ is an nteraction that provides real-life value to your app’s users, the thing people want to do with your entities.
+An _entity_ is a real-life concept that your app is working with. A _feature_ is an interaction that provides real-life value to your app’s users, the thing people want to do with your entities.
For more information, along with examples, see the Reference page on [slices][reference-entities].
@@ -42,7 +42,7 @@ For example, Atomic Design [can be applied well](https://t.me/feature_sliced/165
### Are there any useful resources/articles/etc. about FSD?
-Yes! Welcome! This section helps you to get acquainted with the application of Feature-Sliced Design and the basics of the methodology. You will also understand the key advantages of the methodology and the reasons for its creation.
-## Main - -import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" -import { RocketOutlined, BuildOutlined, PlaySquareOutlined } from "@ant-design/icons"; -Pictured above: three pillars, labeled left to right as "Layers", "Slices", and "Segments" respectively.
+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".
+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".
+The "Segments" pillar contains three divisions, arranged top to bottom and labeled "ui", "model", and "api".
+
+
+ );
+}
```
-#### Layers: app
+Then re-export this component in the feed page’s public API, the `pages/feed/index.ts` file:
+
+
-As you can see , we have moved all the basic logic to the `app/` directory
+```ts title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+```
-It is there, according to the methodology, that all the preparatory logic should be placed:
+Now connect it to the root route. In Remix, routing is file-based, and the route files are located in the `app/routes` folder, which nicely coincides with Feature-Sliced Design.
-- connecting global styles (`/app/styles/**` + `/app/index.css`)
-- providers and HOCs with initializing logic (`/app/providers/**`)
+Use the `FeedPage` component in `app/routes/_index.tsx`:
-For now, we will transfer all the existing logic there, and leave the other directories empty, as in the diagram above.
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
-```tsx title=app/index.tsx
-import "./index.css";
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
-const App = () => {...}
+export default FeedPage;
```
-### 1.3 Enabling global styles
+Then, if you run the dev server and open the application, you should see the Conduit banner!
+
+
-#### Install dependencies
+### API client
-In the tutorial, we install sass, but you can also take any other preprocessor that supports imports
+To talk to the RealWorld backend, let’s create a convenient API client in Shared. Create two segments, `api` for the client and `config` for variables like the backend base URL:
-```cmd
-$ npm i sass
+```bash
+npx fsd shared --segments api config
```
-#### Creating files for styles
+Then create `shared/config/backend.ts`:
-##### For css variables
+```tsx title="shared/config/backend.ts"
+export const backendBaseUrl = "https://api.realworld.io/api";
+```
-```scss title=app/styles/vars.scss
-:root {
- --color-dark: #242424;
- --color-primary: #108ee9;
- ...
-}
+```tsx title="shared/config/index.ts"
+export { backendBaseUrl } from "./backend";
```
-##### To normalize styles
+Since the RealWorld project conveniently provides an [OpenAPI specification](https://github.com/gothinkster/realworld/blob/main/api/openapi.yml), we can take advantage of auto-generated types for our client. We will use [the `openapi-fetch` package](https://openapi-ts.pages.dev/openapi-fetch/) that comes with an additional type generator.
-```scss title=app/styles/normalize.scss
-html {
- scroll-behavior: smooth;
-}
-...
+Run the following command to generate up-to-date API typings:
+
+```bash
+npm run generate-api-types
```
-##### Connecting all styles
+This will create a file `shared/api/v1.d.ts`. We will use this file to create a typed API client in `shared/api/client.ts`:
+
+```tsx title="shared/api/client.ts"
+import createClient from "openapi-fetch";
+
+import { backendBaseUrl } from "shared/config";
+import type { paths } from "./v1";
-```scss title=app/styles/index.scss
-@import "./normalize.scss";
-@import "./vars.scss";
-...
+export const { GET, POST, PUT, DELETE } = createClient
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+ );
+}
```
-```ts title=app/providers/index.ts
-import compose from "compose-function";
-import { withRouter } from "./with-router";
+The like button doesn’t do anything for now, we will fix that when we get to the article reader page and implement the liking functionality.
+
+Now we can fetch the articles and render out a bunch of these cards. Fetching data in Remix is done with *loaders* — server-side functions that fetch exactly what a page needs. Loaders interact with the API on the page’s behalf, so we will put them in the `api` segment of a page:
+
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+
+import { GET } from "shared/api";
+
+export const loader = async () => {
+ const { data: articles, error, response } = await GET("/articles");
+
+ if (error !== undefined) {
+ throw json(error, { status: response.status });
+ }
-export const withProviders = compose(withRouter);
+ return json({ articles });
+};
+```
+
+To connect it to the page, we need to export it with the name `loader` from the route file:
+
+```tsx title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+export { loader } from "./api/loader";
+```
+
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
+
+export { loader } from "pages/feed";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
+
+export default FeedPage;
```
-```tsx title=app/index.tsx
-import { withProviders } from "./providers";
-...
+And the final step is to render these cards in the feed. Update your `FeedPage` with the following code:
+
+```tsx title="pages/feed/ui/FeedPage.tsx"
+import { useLoaderData } from "@remix-run/react";
+
+import type { loader } from "../api/loader";
+import { ArticlePreview } from "./ArticlePreview";
-const App = () => {...}
+export function FeedPage() {
+ const { articles } = useLoaderData
+
+ 
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ Read more... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
```
-#### Let's add real pages
+### Filtering by tag
-:::note
+Regarding the tags, our job is to fetch them from the backend and to store the currently selected tag. We already know how to do fetching — it’s another request from the loader. We will use a convenience function `promiseHash` from a package `remix-utils`, which is already installed.
-This is just one of the routing implementations
+Update the loader file, `pages/feed/api/loader.ts`, with the following code:
-- You can declare it declaratively or through the list of routes (+ react-router-config)
-- You can declare it at the pages or app level
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
-The methodology does not yet regulate the implementation of this logic in any way
+import { GET } from "shared/api";
-:::
+async function throwAnyErrors
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+ Test Page
;
+export const loader = async () => {
+ return json(
+ await promiseHash({
+ articles: throwAnyErrors(GET("/articles")),
+ tags: throwAnyErrors(GET("/tags")),
+ }),
+ );
};
+```
-export default TestPage;
+You might notice that we extracted the error handling into a generic function `throwAnyErrors`. It looks pretty useful, so we might want to reuse it later, but for now let’s just keep an eye on it.
+
+Now, to the list of tags. It needs to be interactive — clicking on a tag should make that tag selected. By Remix convention, we will use the URL search parameters as our storage for the selected tag. Let the browser take care of storage while we focus on more important things.
+
+Update `pages/feed/ui/FeedPage.tsx` with the following code:
+
+```tsx title="pages/feed/ui/FeedPage.tsx"
+import { Form, useLoaderData } from "@remix-run/react";
+import { ExistingSearchParams } from "remix-utils/existing-search-params";
+
+import type { loader } from "../api/loader";
+import { ArticlePreview } from "./ArticlePreview";
+
+export function FeedPage() {
+ const { articles, tags } = useLoaderData
+
+ );
+}
```
-##### Let's form the routes
+Then we need to use the `tag` search parameter in our loader. Change the `loader` function in `pages/feed/api/loader.ts` to the following:
-```tsx title=pages/index.tsx
-// Or use @loadable/component, as part of the tutorial - uncritically
-import { lazy } from "react";
-import { Route, Routes, Navigate } from "react-router-dom";
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
-const TestPage = lazy(() => import("./test"));
+import { GET } from "shared/api";
-export const Routing = () => {
- return (
-
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
```
-:::
+So that’s also done. There’s also the tab list that can be similarly implemented, but let’s hold on to that until we implement authentication. Speaking of which!
+
+### Authentication
+
+Authentication involves two pages — one to login and another to register. They are mostly the same, so it makes sense to keep them in the same slice, `sign-in`, so that they can reuse code if needed.
+
+Create `RegisterPage.tsx` in the `ui` segment of `pages/sign-in` with the following content:
+
+```tsx title="pages/sign-in/ui/RegisterPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
-## 2. Implementing business logic
+import type { register } from "../api/register";
-:::note
+export function RegisterPage() {
+ const registerData = useActionData
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
+```
-We will try to focus not on the implementation of each module, but on their sequential composition
+We have a broken import to fix now. It involves a new segment, so create that:
-:::
+```bash
+npx fsd pages sign-in -s api
+```
-### 2.1 Let's analyze the functionality
+However, before we can implement the backend part of registering, we need some infrastructure code for Remix to handle sessions. That goes to Shared, in case any other page needs it.
-Before starting the code, we need to decide - [what value we want to convey to the end user][refs-needs]
+Put the following code in `shared/api/auth.server.ts`. This is highly Remix-specific, so don’t worry too much about it, just copy-paste:
-To do this, we decompose our functionality *by responsibility scopes [(layers)][refs-layers]*
+```tsx title="shared/api/auth.server.ts"
+import { createCookieSessionStorage, redirect } from "@remix-run/node";
+import invariant from "tiny-invariant";
-
+import type { User } from "./models";
-#### Pages
+invariant(
+ process.env.SESSION_SECRET,
+ "SESSION_SECRET must be set for authentication to work",
+);
-We will outline the basic necessary pages, and user expectations from them:
+const sessionStorage = createCookieSessionStorage<{
+ user: User;
+}>({
+ cookie: {
+ name: "__session",
+ httpOnly: true,
+ path: "/",
+ sameSite: "lax",
+ secrets: [process.env.SESSION_SECRET],
+ secure: process.env.NODE_ENV === "production",
+ },
+});
-1. `TasksListPage` - the "Task List" page
+export async function createUserSession({
+ request,
+ user,
+ redirectTo,
+}: {
+ request: Request;
+ user: User;
+ redirectTo: string;
+}) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ session.set("user", user);
+
+ return redirect(redirectTo, {
+ headers: {
+ "Set-Cookie": await sessionStorage.commitSession(session, {
+ maxAge: 60 * 60 * 24 * 7, // 7 days
+ }),
+ },
+ });
+}
- - View the task list
- - Go to the page of a specific task
- - *Mark a specific task completed/unfulfilled*
- - Set filtering by completed / unfulfilled tasks
+export async function getUserFromSession(request: Request) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
-2. `TaskDetailsPage` - page "Task card"
+ return session.get("user") ?? null;
+}
- - View information about the task
- - *Mark a specific task as completed/unfulfilled*
- - Go back to the task list
+export async function requireUser(request: Request) {
+ const user = await getUserFromSession(request);
-Each of the described features is a part of the functionality
+ if (user === null) {
+ throw redirect("/login");
+ }
-##### Usual approach
+ return user;
+}
+```
-And there is a great temptation
+And also export the `User` model from the `models.ts` file right next to it:
-- or implement all the logic in the directory of each specific page.
-- or put all" possibly reused "modules in the shared folder `src/components` or similar
+```tsx title="shared/api/models.ts"
+import type { components } from "./v1";
-But if such a solution would be suitable for a small and short-lived project, then in real corporate development, it **can put an end** to the further development of the project, turning it into **"another dense legacy"**
+export type Article = components["schemas"]["Article"];
+export type User = components["schemas"]["User"];
+```
-This is due to the usual conditions of the project development:
+Before this code can work, the `SESSION_SECRET` environment variable needs to be set. Create a file called `.env` in the root of the project, write `SESSION_SECRET=` and then mash some keys on your keyboard to create a long random string. You should get something like this:
-- requirements change quite often
-- there are new circumstances
-- the technical debt is accumulating every day and it is becoming more difficult to add new features
-- it is necessary to scale both the project itself and its team
+```bash title=".env"
+SESSION_SECRET=dontyoudarecopypastethis
+```
-##### Alternative approach
+Finally, add some exports to the public API to make use of this code:
-Even with the basic partitioning, we see that:
+```tsx title="shared/api/index.ts"
+export { GET, POST, PUT, DELETE } from "./client";
-- there are common entities between the pages and their display *(Task)*
-- there are common features *between the pages (Mark the task completed / unfulfilled)*
+export type { Article } from "./models";
-Accordingly, it seems logical to continue to decompose the task, but already based on the above-mentioned features for the user.
+export { createUserSession, getUserFromSession, requireUser } from "./auth.server";
+```
-#### Features
+Now we can write the code that will talk to the RealWorld backend to actually do the registration. We will keep that in `pages/sign-in/api`. Create a file called `register.ts` and put the following code inside:
-Parts of functionality that bring value to the user
+```tsx title="pages/sign-in/api/register.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
-- `
+
+
+
+
+
+ Sign up
++ Have an account? +
+ + {registerData?.error && ( +-
+ {registerData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
+```
-```ts title={layer}/foo/index.ts
-export { Card as FooCard, Thumbnail as FooThumbnail, ... } from "./ui";
-export * as fooModel from "./model";
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+export { SignInPage } from './ui/SignInPage';
+export { signIn } from './api/sign-in';
```
-:::info
+```tsx title="app/routes/login.tsx"
+import { SignInPage, signIn } from "pages/sign-in";
+
+export { signIn as action };
-If you need named namespace exports for the Public API declaration, you can look aside [@babel/plugin-proposal-export-namespace-from](https://babeljs.io/docs/en/babel-plugin-proposal-export-namespace-from)
+export default SignInPage;
+```
-Or, as an alternative, use a more detailed design
+Now let’s give the users a way to actually get to these pages.
-```ts title={layer}/foo/index.ts
-import { Card as FooCard, Thumbnail as FooThumbnail, ... } from "./ui";
-import * as fooModel from "./model";
+### Header
-export { FooCard, FooThumbnail, fooModel };
+As we discussed in part 1, the app header is commonly placed either in Widgets or in Shared. We will put it in Shared because it’s very simple and all the business logic can be kept outside of it. Let’s create a place for it:
+
+```bash
+npx fsd shared ui
```
-:::
+Now create `shared/ui/Header.tsx` with the following contents:
-### 2.3 Let's display the basic task list
+```tsx title="shared/ui/Header.tsx"
+import { useContext } from "react";
+import { Link, useLocation } from "@remix-run/react";
-#### (entities) Task card
+import { CurrentUser } from "../api/currentUser";
-```tsx title=entities/task/ui/task-row/index.tsx
-import { Link } from "react-router-dom";
-import cn from "classnames"; // we can safely use the analogy
-import { Row } from "antd"; // ~ "shared/ui/row"
+export function Header() {
+ const currentUser = useContext(CurrentUser);
+ const { pathname } = useLocation();
-export const TaskRow = ({ data, titleHref }: TaskRowProps) => {
- return (
-
+
+
+
+
+
+ Sign in
++ Need an account? +
+ + {signInData?.error && ( +-
+ {signInData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
);
-};
+}
```
-### 2.4 Adding task status switching
+```tsx title="pages/feed/ui/Pagination.tsx"
+import { Form, useLoaderData, useSearchParams } from "@remix-run/react";
+import { ExistingSearchParams } from "remix-utils/existing-search-params";
-#### (entities) Switching the task status
+import { LIMIT, type loader } from "../api/loader";
-```ts title=entities/task/model/index.ts
-export const toggleTask = createEventPopular Tags
+ + +
+
+ );
+}
+```
+
+We also need to account for the new tab in the loader function:
+
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET, requireUser } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+
+
+
+
+
+
+ );
}
```
-#### (pages) Embedding the checkbox in the page
+This code will send a POST request to `/article/:slug` with `_action=favorite` to mark the article as favorite. It won’t work yet, but as we start working on the article reader, we will implement this too.
-What is noteworthy is that the task card does not know at all about the page where it is used, nor about what action buttons can be inserted into it (the same can be said about the feature itself)
+And with that we are officially done with the feed! Yay!
-This approach allows you to simultaneously **competently share responsibility** and **flexibly reuse logic during implementation**
+### Article reader
-```tsx title=pages/tasks-list/index.tsx
-import { ToggleTask } from "features/toggle-task";
-import { TaskRow, taskModel } from "entities/task";
-...
-
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ Read more... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
);
+}
+```
+
+What’s more interesting is the `ArticleMeta` and `Comments`. They contain write operations such as liking an article, leaving a comment, etc. To get them to work, we first need to implement the backend part. Create `action.ts` in the `api` segment of the page:
+
+```tsx title="pages/article-read/api/action.ts"
+import { redirect, type ActionFunctionArgs } from "@remix-run/node";
+import { namedAction } from "remix-utils/named-action";
+import { redirectBack } from "remix-utils/redirect-back";
+import invariant from "tiny-invariant";
+
+import { DELETE, POST, requireUser } from "shared/api";
+
+export const action = async ({ request, params }: ActionFunctionArgs) => {
+ const currentUser = await requireUser(request);
+
+ const authorization = { Authorization: `Token ${currentUser.token}` };
+
+ const formData = await request.formData();
+
+ return namedAction(formData, {
+ async delete() {
+ invariant(params.slug, "Expected a slug parameter");
+ await DELETE("/articles/{slug}", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirect("/");
+ },
+ async favorite() {
+ invariant(params.slug, "Expected a slug parameter");
+ await POST("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfavorite() {
+ invariant(params.slug, "Expected a slug parameter");
+ await DELETE("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async createComment() {
+ invariant(params.slug, "Expected a slug parameter");
+ const comment = formData.get("comment");
+ invariant(typeof comment === "string", "Expected a comment parameter");
+ await POST("/articles/{slug}/comments", {
+ params: { path: { slug: params.slug } },
+ headers: { ...authorization, "Content-Type": "application/json" },
+ body: { comment: { body: comment } },
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async deleteComment() {
+ invariant(params.slug, "Expected a slug parameter");
+ const commentId = formData.get("id");
+ invariant(typeof commentId === "string", "Expected an id parameter");
+ const commentIdNumeric = parseInt(commentId, 10);
+ invariant(
+ !Number.isNaN(commentIdNumeric),
+ "Expected a numeric id parameter",
+ );
+ await DELETE("/articles/{slug}/comments/{id}", {
+ params: { path: { slug: params.slug, id: commentIdNumeric } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async followAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "Expected a username parameter",
+ );
+ await POST("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfollowAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "Expected a username parameter",
+ );
+ await DELETE("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ });
};
```
-#### (pages) Implementing filtering in the page
+Export that from the slice and then from the route. While we’re at it, let’s also connect the page itself:
-And we implemented the logic again, without asking too many questions:
+```tsx title="pages/article-read/index.ts"
+export { ArticleReadPage } from "./ui/ArticleReadPage";
+export { loader } from "./api/loader";
+export { action } from "./api/action";
+```
-- And where to put the filtering logic?
-- Can these filters be reused in the future?
-- Can filters know about the page context?
+```tsx title="app/routes/article.$slug.tsx"
+import { ArticleReadPage } from "pages/article-read";
-We just divided the logic according to the scopes of responsibility (layers)
+export { loader, action } from "pages/article-read";
-```tsx title=pages/tasks-list/index.tsx
-import { TasksFilters } from "features/tasks-filters";
-...
-
+
+
+
+
+ {article.article.title}
+ +
+
+ +
+
+
+
+
+
+ {article.article.body}
+-
+ {article.article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+ +
+
+
+
+
+
+ {currentUser !== null ? (
+
+ ) : (
+
+ );
+}
+```
-```tsx title=pages/task-details/index.tsx
-import { ToggleTask } from "features/toggle-task";
-import { TaskCard, taskModel } from "entities/task";
-import { Layout, Button } from "antd"; // ~ "shared/ui/{...}"
-import styles from "./styles.module.scss";
+And with that our article reader is also complete! The buttons to follow the author, like a post, and leave a comment should now function as expected.
-const TaskDetailsPage = (props: Props) => {
- const taskId = Number(props.match?.params.taskId);
- const task = taskModel.useTask(taskId);
- const isLoading = useStore(taskModel.$taskDetailsLoading);
+
+
+ )}
+
+ {comments.comments.map((comment) => (
+
+
+ + Sign in + or + Sign up + to add comments on this article. +
+
+
+ ))}
+
+
+
+ {comment.body}
+
+
+ 
+
+
+
+ {comment.author.username}
+
+ {comment.createdAt}
+ {comment.author.username === currentUser?.username && (
+
+
+
+ )}
+
+
+
+ );
+}
```
-### 2.7 What's next?
+This page gets the current article (unless we’re writing from scratch) and fills in the corresponding form fields. We’ve seen this before. The interesting part is `FormErrors`, because it will receive the validation result and display it to the user. Let’s take a look:
+
+```tsx title="pages/article-edit/ui/FormErrors.tsx"
+import { useActionData } from "@remix-run/react";
+import type { action } from "../api/action";
+
+export function FormErrors() {
+ const actionData = useActionData
+
+
+
+
+
+ -
+ {actionData.errors.map((error) => (
+
- {error} + ))} +
+ {tagListState.map((tag) => (
+
+
+ [" ", "Enter"].includes(e.key) && removeTag(tag)
+ }
+ onClick={() => removeTag(tag)}
+ >{" "}
+ {tag}
+
+ ))}
+
+
+ );
+}
+```
-#### Did you need to change the filtering logic?
+Now, for the API part. The loader should look at the URL, and if it contains an article slug, that means we’re editing an existing article, and its data should be loaded. Otherwise, return nothing. Let’s create that loader:
-=> Changing the processing at the `entities` or `pages` level, depending on the scale
+```ts title="pages/article-edit/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
-#### Do you need to add more features to the task card, but at the same time, so that it can be used in the old way?
+import { GET, requireUser } from "shared/api";
-=> Add features and insert them into the card only on the desired **page**
+async function throwAnyErrors
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+```ts title="shared/ui/layout/useThemeSwitcher.ts"
+export function useThemeSwitcher() {
+ const [theme, setTheme] = useState("light");
+
+ function toggleTheme() {
+ setTheme(theme === "light" ? "dark" : "light");
+ }
+
+ useEffect(() => {
+ document.body.classList.remove("light", "dark");
+ document.body.classList.add(theme);
+ }, [theme]);
+
+ return [theme, toggleTheme] as const;
+}
+```
+
+The code of sidebars is left as an exercise for the reader 😉.
+
+## Using widgets in the layout
+
+Sometimes you want to include certain business logic in the layout, especially if you're using deeply nested routes with a router like [React Router][ext-react-router]. Then you can't store the layout in Shared or in Widgets due to [the import rule on layers][import-rule-on-layers]:
+
+> A module in a slice can only import other slices when they are located on layers strictly below.
+
+Before we discuss solutions, we need to discuss if it's even a problem in the first place. Do you _really need_ that layout, and if so, does it _really need_ to be a Widget? If the block of business logic in question is reused on 2-3 pages, and the layout is simply a small wrapper for that widget, consider one of these two options:
+
+1. **Write the layout inline on the App layer, where you configure the routing**
+ This is great for routers that support nesting, because you can group certain routes and apply the layout only to them.
+
+2. **Just copy-paste it**
+ The urge to abstract code is often very overrated. It is especially the case for layouts, which rarely change. At some point, if one of these pages will need to change, you can simply do the change without needlessly affecting other pages. If you're worried that someone might forget to update the other pages, you can always leave a comment that describes the relationship between the pages.
+
+If none of the above are applicable, there are two solutions to include a widget in the layout:
+
+1. **Use render props or slots**
+ Most frameworks allow you to pass a piece of UI externally. In React, it's called [render props][ext-render-props], in Vue it's called [slots][ext-vue-slots].
+2. **Move the layout to the App layer**
+ You can also store your layout on the App layer, for example, in `app/layouts`, and compose any widgets you want.
+
+## Further reading
+
+- There's an example of how to build a layout with authentication with React and Remix (equivalent to React Router) in the [tutorial][tutorial].
+
+[tutorial]: /docs/get-started/tutorial
+[import-rule-on-layers]: /docs/reference/layers#import-rule-on-layers
+[ext-react-router]: https://reactrouter.com/
+[ext-render-props]: https://www.patterns.dev/react/render-props-pattern/
+[ext-vue-slots]: https://vuejs.org/guide/components/slots
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/guides/examples/page-layout.mdx b/i18n/en/docusaurus-plugin-content-docs/current/guides/examples/page-layout.mdx
deleted file mode 100644
index 994141ea52..0000000000
--- a/i18n/en/docusaurus-plugin-content-docs/current/guides/examples/page-layout.mdx
+++ /dev/null
@@ -1,28 +0,0 @@
----
-sidebar_position: 2
-sidebar_class_name: sidebar-item--wip
----
-
-import WIP from '@site/src/shared/ui/wip/tmpl.mdx'
-
-# PageLayout
-
--
+
-
+ ++
📁 actions
+-
+
- 📁 product +
- 📁 order +
+ - 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
-
+ ++
📁 routes
+-
+
- 📁 products.jsx +
- 📄 products.[id].jsx +
+ - 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
- 📄 App.jsx +
- 📄 index.js +
+
+
+## Step 3. Tackle cross-imports between pages {#tackle-cross-imports-between-pages}
+
+
+
+
+Find all instances where one page is importing from the other and do one of the two things:
+
+1. Copy-paste the imported code into the depending page to remove the dependency
+2. Move the code to a proper segment in Shared:
+ - if it's a part of the UI kit, move it to `📁 shared/ui`;
+ - if it's a configuration constant, move it to `📁 shared/config`;
+ - if it's a backend interaction, move it to `📁 shared/api`.
+
+:::note
+
+**Copy-pasting isn't architecturally wrong**, in fact, sometimes it may be more correct to duplicate than to abstract into a new reusable module. The reason is that sometimes the shared parts of pages start drifting apart, and you don't want dependencies getting in your way in these cases.
+
+However, there is still sense in the DRY ("don't repeat yourself") principle, so make sure you're not copy-pasting business logic. Otherwise you will need to remember to fix bugs in several places at once.
+
+:::
+
+## Step 4. Unpack the Shared layer {#unpack-shared-layer}
+
+You might have a lot of stuff in the Shared layer on this step, and you generally want to avoid that. The reason is that the Shared layer may be a dependency for any other layer in your codebase, so making changes to that code is automatically more prone to unintended consequences.
+
+Find all the objects that are only used on one page and move it to the slice of that page. And yes, _that applies to actions, reducers, and selectors, too_. There is no benefit in grouping all actions together, but there is benefit in colocating relevant actions close to their usage.
+
+You should end up with a file structure like this:
+
+📁 src
+-
+
-
+ ++
📁 app
+-
+
-
+ ++
📁 routes
+-
+
- 📄 products.jsx +
- 📄 products.[id].jsx +
+ - 📄 App.jsx +
- 📄 index.js +
+ -
+
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
-
+ ++
📁 ui
+-
+
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ -
+
- 📁 catalog +
+ -
+
-
+ ++
📁 shared
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
+
+
+## Step 5. Organize code by technical purpose {#organize-by-technical-purpose}
+
+In FSD, division by technical purpose is done with _segments_. There are a few common ones:
+
+- `ui` — everything related to UI display: UI components, date formatters, styles, etc.
+- `api` — backend interactions: request functions, data types, mappers, etc.
+- `model` — the data model: schemas, interfaces, stores, and business logic.
+- `lib` — library code that other modules on this slice need.
+- `config` — configuration files and feature flags.
+
+You can create your own segments, too, if you need. Make sure not to create segments that group code by what it is, like `components`, `actions`, `types`, `utils`. Instead, group the code by what it's for.
+
+Reorganize your pages to separate code by segments. You should already have a `ui` segment, now it's time to create other segments, like `model` for your actions, reducers, and selectors, or `api` for your thunks and mutations.
+
+Also reorganize the Shared layer to remove these folders:
+- `📁 components`, `📁 containers` — most of it should become `📁 shared/ui`;
+- `📁 helpers`, `📁 utils` — if there are some reused helpers left, group them together by function, like dates or type conversions, and move theses groups to `📁 shared/lib`;
+- `📁 constants` — again, group by function and move to `📁 shared/config`.
+
+## Optional steps {#optional-steps}
+
+### Step 6. Form entities/features from Redux slices that are used on several pages {#form-entities-features-from-redux}
+
+Usually, these reused Redux slices will describe something relevant to the business, for example, products or users, so these can be moved to the Entities layer, one entity per one folder. If the Redux slice is related to an action that your users want to do in your app, like comments, then you can move it to the Features layer.
+
+Entities and features are meant to be independent from each other. If your business domain contains inherent connections between entities, refer to the [guide on business entities][business-entities-cross-relations] for advice on how to organize these connections.
+
+The API functions related to these slices can stay in `📁 shared/api`.
+
+### Step 7. Refactor your modules {#refactor-your-modules}
+
+The `📁 modules` folder is commonly used for business logic, so it's already pretty similar in nature to the Features layer from FSD. Some modules might also be describe large chunks of the UI, like an app header. In that case, you should migrate them to the Widgets layer.
+
+### Step 8. Form a clean UI foundation in `shared/ui` {#form-clean-ui-foundation}
+
+`📁 shared/ui` should ideally contain a set of UI elements that don't have any business logic encoded in them. They should also be highly reusable.
+
+Refactor the UI components that used to be in `📁 components` and `📁 containers` to separate out the business logic. Move that business logic to the higher layers. If it's not used in too many places, you could even consider copy-pasting.
+
+## See also {#see-also}
+
+- [(Talk in Russian) Ilya Klimov — Крысиные бега бесконечного рефакторинга: как не дать техническому долгу убить мотивацию и продукт](https://youtu.be/aOiJ3k2UvO4)
+
+[ext-steiger]: https://github.com/feature-sliced/steiger
+[business-entities-cross-relations]: /docs/guides/examples/types#business-entities-and-their-cross-references
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/guides/migration/from-legacy.mdx b/i18n/en/docusaurus-plugin-content-docs/current/guides/migration/from-legacy.mdx
deleted file mode 100644
index 67ee065c12..0000000000
--- a/i18n/en/docusaurus-plugin-content-docs/current/guides/migration/from-legacy.mdx
+++ /dev/null
@@ -1,120 +0,0 @@
----
-sidebar_position: 3
-sidebar_class_name: sidebar-item--wip
----
-
-import WIP from '@site/src/shared/ui/wip/tmpl.mdx'
-
-# Migration from legacy
-
-📁 src
+-
+
- 📁 app (unchanged) +
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
- 📁 actions +
- 📁 reducers +
- 📁 selectors +
-
+ ++
📁 ui
+-
+
- 📄 Component.jsx +
- 📄 Container.jsx +
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ - 📁 catalog +
+ -
+
-
+ ++
📁 shared (only objects that are reused)
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
Loading...
;
+ }
+
+ if (isError || !post) {
+ return <>{error?.message};
+ }
+
+ return (
+
+
+ );
+};
+```
+
+### Benefits of using a Query Factory
+- **Request structuring:** A factory allows you to organize all API requests in one place, making your code more readable and maintainable.
+- **Convenient access to queries and keys:** The factory provides convenient methods for accessing different types of queries and their keys.
+- **Query Refetching Ability:** The factory allows easy refetching without the need to change query keys in different parts of the application.
+
+## Pagination
+
+In this section, we'll look at an example of the `getPosts` function, which makes an API request to retrieve post entities using pagination.
+
+### 1. Creating a function `getPosts`
+The getPosts function is located in the `get-posts.ts` file, which is located in the `api` segment
+
+```tsx title="@/pages/post-feed/api/get-posts.ts"
+import { apiClient } from "@/shared/api/base";
+
+import { PostWithPaginationDto } from "./dto/post-with-pagination.dto";
+import { PostQuery } from "./query/post.query";
+import { mapPost } from "./mapper/map-post";
+import { PostWithPagination } from "../model/post-with-pagination";
+
+const calculatePostPage = (totalCount: number, limit: number) =>
+ Math.floor(totalCount / limit);
+
+export const getPosts = async (
+ page: number,
+ limit: number,
+): PromisePost id: {post.id}
+
+
+ {post.title}
+
+
+ {post.body}
+Owner: {post.userId}
+
- {Header}
-
-)
-
-```
-
-#### Using the composition
-
-This allows you to **reuse and independently change** components with different Header and list Items. Header and Items components can have both their own local state and their binding to the general state of the application - the List component will not know anything about it, and therefore will not depend on it
-
-```tsx
--
- {Items}
-
-
+![A file system tree, with a single root folder called src and then seven subfolders: app, processes, pages, widgets, features, entities, shared. The processes folder is slightly faded out.]({useBaseUrl("/img/layers/folders-graphic-light.svg#light-mode-only")})
+![A file system tree, with a single root folder called src and then seven subfolders: app, processes, pages, widgets, features, entities, shared. The processes folder is slightly faded out.]({useBaseUrl("/img/layers/folders-graphic-dark.svg#dark-mode-only")})
1. App
2. Processes (deprecated)
@@ -28,133 +22,107 @@ There are **7 layers** in total, arranged from most responsibility and depe
6. Entities
7. Shared
-You don't have to use every layer in your project — only add them if you think it brings value to your project.
+You don't have to use every layer in your project — only add them if you think it brings value to your project. Typically, most frontend projects will have at least the Shared, Pages, and App layers.
+
+In practice, layers are folders with lowercase names (for example, `📁 shared`, `📁 pages`, `📁 app`). Adding new layers is _not recommended_ because their semantics are standardized.
## Import rule on layers
-Layers are made up of _slices_ — highly cohesive groups of modules. Feature-Sliced Design promotes low coupling, which is why dependencies between slices are regulated by **the import rule on layers**:
+Layers are made up of _slices_ — highly cohesive groups of modules. Dependencies between slices are regulated by **the import rule on layers**:
+
+> _A module (file) in a slice can only import other slices when they are located on layers strictly below._
-> _A module in a slice can only import other slices when they are located on layers strictly below._
+For example, the folder `📁 ~/features/aaa` is a slice with the name "aaa". A file inside of it, `~/features/aaa/api/request.ts`, cannot import code from any file in `📁 ~/features/bbb`, but can import code from `📁 ~/entities` and `📁 ~/shared`, as well as any sibling code from `📁 ~/features/aaa`, for example, `~/features/aaa/lib/cache.ts`.
-For example, in `~/features/aaa`, `aaa` is the slice, so a file `~/features/aaa/api/request.ts` cannot import code from any module in `~/features/bbb`, but can import code from `~/entities` and `~/shared`, as well as any sibling code from `~/features/aaa`.
+Layers App and Shared are **exceptions** to this rule — they are both a layer and a slice at the same time. Slices partition code by business domain, and these two layers are exceptions because Shared does not have business domains, and App combines all business domains.
+
+In practice, this means that layers App and Shared are made up of segments, and segments can import each other freely.
## Layer definitions
+This section describes the semantic meaning of each layer to create an intuition for what kind of code belongs there.
+
### Shared
-Isolated modules, components and abstractions that are detached from the specifics of the project or business.
-Warning: not to be treated like [a utility dump][ext--sova-utility-dump]!
+This layer forms a foundation for the rest of the app. It's a place to create connections with the external world, for example, backends, third-party libraries, the environment. It is also a place to define your own highly contained libraries.
-This layer, unlike others, does not consist of slices, and instead consists of segments directly.
+This layer, like the App layer, _does not contain slices_. Slices are intended to divide the layer into business domains, but business domains do not exist in Shared. This means that all files in Shared can reference and import from each other.
-**Content examples**:
+Here are the segments that you can typically find in this layer:
-* UI kit
-* API client
-* Code working with browser APIs
+- `📁 api` — the API client and potentially also functions to make requests to specific backend endpoints.
+- `📁 ui` — the application's UI kit.
+ Components on this layer should not contain business logic, but it's okay for them to be business-themed. For example, you can put the company logo and page layout here. Components with UI logic are also allowed (for example, autocomplete or a search bar).
+- `📁 lib` — a collection of internal libraries.
+ This folder should not be treated as helpers or utilities ([read here why these folders often turn into a dump][ext-sova-utility-dump]). Instead, every library in this folder should have one area of focus, for example, dates, colors, text manipulation, etc. That area of focus should be documented in a README file. The developers in your team should know what can and cannot be added to these libraries.
+- `📁 config` — environment variables, global feature flags and other global configuration for your app.
+- `📁 routes` — route constants or patterns for matching routes.
+- `📁 i18n` — setup code for translations, global translation strings.
+
+You are free to add more segments, but make sure that the name of these segments describes the purpose of the content, not its essence. For example, `components`, `hooks`, and `types` are bad segment names because they aren't that helpful when you're looking for code.
### Entities
-Concepts from the real world that form together the essence of the project. Commonly, these are the terms that the business uses to describe the product.
+Slices on this layer represent concepts from the real world that the project is working with. Commonly, they are the terms that the business uses to describe the product. For example, a social network might work with business entities like User, Post, and Group.
-Each slice in this layer contains static UI elements, data stores and CRUD operations.
+An entity slice might contain the data storage (`📁 model`), data validation schemas (`📁 model`), entity-related API request functions (`📁 api`), as well as the visual representation of this entity in the interface (`📁 ui`). The visual representation doesn't have to produce a complete UI block — it is primarily meant to reuse the same appearance across several pages in the app, and different business logic may be attached to it through props or slots.
-**Slice examples**:
+#### Entity relationships
-| For a social network | For a Git frontend (e.g., GitHub) |
|---|---|
|
|
| For a social network | For a Git frontend (e.g., GitHub) | Actions on behalf of users |
|---|---|---|
|
|
|
| For a social network | For a Git frontend (e.g., GitHub) |
|---|---|
|
|
| For a social network | For a Git frontend (e.g., GitHub) |
|---|---|
|
|
![Three files importing each other in a circle]({useBaseUrl("/img/circular-import-light.svg#light-mode-only")})
+ ![Three files importing each other in a circle]({useBaseUrl("/img/circular-import-dark.svg#dark-mode-only")})
+ ![]({useBaseUrl("/img/coupling-cohesion-light.svg#light-mode-only")})
+ ![]({useBaseUrl("/img/coupling-cohesion-dark.svg#dark-mode-only")})
+ If you need to use individual helpers, consider using utility libraries such as [`lodash-es`][ext--lodash]. | Rudimentary API client with additional features like authentication or caching. | -| Entities | Skeleton of a business entity with slots for interactive elements | Data storage of instances of this entity as well as functions for manipulating that data.
This segment is most fit for storing server-side data. If you use [TanStack Query][ext--tanstack-query] or other methods of implicit storage, you may choose to omit this segment. | Functions for manipulating instances of this entity that aren't related to storage | API methods using the API client from Shared for easy communication with the backend | -| Features | Interactive elements that enable users to use this feature | Business logic and infrastructure data storage, if needed (e.g., current app theme). This is the code that actually produces value for the user. | Infrastructural code that helps to concisely describe the business logic in the `model` segment | API methods that represent this feature on the backend.
May compose API methods from Entities. | -| Widgets | Composition of Entities and Features into self-contained UI blocks.
Can also contain error boundaries and loading states. | Infrastructure data storage, if needed | Non-business interactions (e.g., gestures) and other necessary code for the block to function on a page | Usually not used, but can contain data loaders in nested routing contexts (e.g., [Remix][ext--remix]) | -| Pages | Composition of Entities, Features and Widgets into complete pages.
Can also contain error boundaries and loading states. | Usually not used | Non-business interactions (e.g., gestures) and other necessary code for the page to deliver a complete user experience | Data loaders for SSR-oriented frameworks | +You can also create custom segments. The most common places for custom segments are the App layer and the Shared layer, where slices don't make sense. -[ref--public-api]: /docs/reference/public-api +Make sure that the name of these segments describes the purpose of the content, not its essence. For example, `components`, `hooks`, and `types` are bad segment names because they aren't that helpful when you're looking for code. -[ext--lodash]: https://www.npmjs.com/package/lodash-es -[ext--tanstack-query]: https://tanstack.com/query/latest -[ext--remix]: https://remix.run +[layers--layer-definitions]: /docs/reference/layers#layer-definitions +[layers--import-rule]: /docs/reference/layers#import-rule-on-layers +[ref-public-api]: /docs/reference/public-api diff --git a/i18n/en/docusaurus-theme-classic/footer.json b/i18n/en/docusaurus-theme-classic/footer.json index 4b930976dc..b9e10f3101 100644 --- a/i18n/en/docusaurus-theme-classic/footer.json +++ b/i18n/en/docusaurus-theme-classic/footer.json @@ -20,21 +20,17 @@ "description": "The label of footer link with label=Discussions linking to https://github.com/feature-sliced/documentation/discussions" }, "link.item.label.Community": { - "message": "Community", - "description": "The label of the footer link with label=Community linking to /community" + "message": "Community", + "description": "The label of the footer link with label=Community linking to /community" }, "link.item.label.Help": { - "message": "Help", - "description": "The label of the footer link with label=Help linking to /nav" + "message": "Help", + "description": "The label of the footer link with label=Help linking to /nav" }, "link.item.label.License": { "message": "License", "description": "The label of footer link with label=License linking to LICENSE" }, - "link.item.label.Privacy": { - "message": "Privacy", - "description": "The label of footer link with label=Privacy linking to /docs/privacy" - }, "link.item.label.Contribution Guide (RU)": { "message": "Contribution Guide (RU)", "description": "The label of footer link with label=Contribution Guide (RU) linking to CONTRIBUTING.md" @@ -64,7 +60,7 @@ "description": "The label of footer link with label=GitHub linking to https://github.com/feature-sliced" }, "copyright": { - "message": "Copyright © 2018-2023 Feature-Sliced Design", + "message": "Copyright © 2018-2025 Feature-Sliced Design", "description": "The footer copyright" } } diff --git a/i18n/ja/code.json b/i18n/ja/code.json new file mode 100644 index 0000000000..738036b4d7 --- /dev/null +++ b/i18n/ja/code.json @@ -0,0 +1,410 @@ +{ + "pages.home.features.title": { + "message": "利点", + "description": "Features" + }, + "pages.home.features.logic.title": { + "message": "明確なビジネスロジック", + "description": "Feature title" + }, + "pages.home.features.logic.description": { + "message": "アーキテクチャはドメインモジュールで構成されているため、習得が容易である", + "description": "Feature description" + }, + "pages.home.features.adaptability.title": { + "message": "適応性", + "description": "Feature title" + }, + "pages.home.features.adaptability.description": { + "message": "アーキテクチャのコンポーネントは柔軟に交換したり、新しい条件に応じて追加したりすることができる", + "description": "Feature description" + }, + "pages.home.features.debt.title": { + "message": "技術的負債", + "description": "Feature title" + }, + "pages.home.features.debt.description": { + "message": "各モジュールは副作用なしに独立して変更/再作成できる", + "description": "Feature description" + }, + "pages.home.features.shared.title": { + "message": "明確な再利用性", + "description": "Feature title" + }, + "pages.home.features.shared.description": { + "message": "DRYとローカルカスタマイズのバランスが保たれている", + "description": "Feature description" + }, + "pages.home.concepts.title": { + "message": "コンセプト", + "description": "Concepts" + }, + "pages.home.concepts.public.title": { + "message": "公開API", + "description": "Concept title" + }, + "pages.home.concepts.public.description": { + "message": "各モジュールはその公開APIをトップレベルで宣言する必要がある", + "description": "Concept description" + }, + "pages.home.concepts.isolation.title": { + "message": "分離", + "description": "Concept title" + }, + "pages.home.concepts.isolation.description": { + "message": "モジュールは同じレイヤーや上層レイヤーの他のモジュールに直接依存してはいけない", + "description": "Concept description" + }, + "pages.home.concepts.needs.title": { + "message": "ニーズの理解", + "description": "Concept title" + }, + "pages.home.concepts.needs.description": { + "message": "ビジネスとユーザーのニーズに焦点を当てる", + "description": "Concept description" + }, + "pages.home.scheme.title": { + "message": "構造", + "description": "Scheme" + }, + "pages.home.companies.using": { + "message": "FSDを使用している企業", + "description": "Companies using methodology" + }, + "pages.home.companies.add_me": { + "message": "あなたの会社でFSDが使用されていますか？", + "description": "Methodology is used in your company?" + }, + "pages.home.companies.tell_us": { + "message": "教えてください", + "description": "Tell us" + }, + "pages.examples.title": { + "message": "実装例", + "description": "Page title" + }, + "pages.examples.subtitle": { + "message": "FSDを使って作られたプロジェクト一覧", + "description": "Page subtitle" + }, + "pages.examples.add_me.title": { + "message": "実装例を追加", + "description": "Request to add example" + }, + "pages.examples.repo.title": { + "message": "リポジトリ", + "description": "Examples repository label" + }, + "pages.examples.versions": { + "message": "バージョン一覧も参照してください", + "description": "Versions reminder" + }, + "pages.versions.title": { + "message": "Feature-Sliced Designのバージョン", + "description": "Feature-Sliced Design versions" + }, + "pages.versions.current": { + "message": "ここで現在公開されているバージョンのドキュメントを見つけることができます", + "description": "Description for current version" + }, + "pages.versions.legacy": { + "message": "ここで古いバージョンのドキュメントを見つけることができます", + "description": "Description for legacy version" + }, + "pages.nav.title": { + "message": "🧭 ナビゲーション", + "description": "NavPage title" + }, + "pages.nav.legacy.title": { + "message": "古いリンク", + "description": "NavPage section=legacy title" + }, + "pages.nav.legacy.details": { + "message": "ドキュメントの再構成後、一部の記事リンクが変更されました。以下に探しているページが見つかるかもしれません。", + "description": "NavPage section=legacy details" + }, + "pages.nav.legacy.subdetails": { + "message": "互換性のために古いリンクからのリダイレクトがあります", + "description": "NavPage section=legacy subdetails" + }, + "features.feedback-badge.label": { + "message": "ドキュメントのフィードバックを共有する 🤙", + "description": "Feedback share button label" + }, + "features.feedback-badge.url": { + "message": "https://forms.gle/7p4anU2shHAzmfqc8", + "description": "Feedback share form url" + }, + "features.feedback-doc.thanks": { + "message": "フィードバックありがとうございます！", + "description": "DocFeedback block=Thanks" + }, + "features.feedback-doc.title": { + "message": "このページは役に立ちましたか？", + "description": "DocFeedback block=Title" + }, + "features.feedback-doc.subtitle": { + "message": "あなたのフィードバックはドキュメントの改善に役立ちます", + "description": "DocFeedback block=Subtitle" + }, + "features.feedback-doc.button-text": { + "message": "フィードバックを送る", + "description": "The text on a floating button to leave feedback about the docs" + }, + "features.feedback-doc.email-placeholder": { + "message": "メールアドレスを入力してください（任意）", + "description": "The placeholder for email input" + }, + "features.feedback-doc.error-message": { + "message": "後でもう一度お試しください。", + "description": "The error message displayed when feedback form submission fails" + }, + "features.feedback-doc.modal-title-error-403": { + "message": "リクエストURLがこのプロジェクトのPushFeedbackに指定されたURLと一致しません。", + "description": "The title of the modal displayed when the feedback form submission fails with 403 error" + }, + "features.feedback-doc.modal-title-error-404": { + "message": "提供されたプロジェクトIDをPushFeedbackで見つけることができませんでした。", + "description": "The title of the modal displayed when the feedback form submission fails with 404 error" + }, + "features.feedback-doc.message-placeholder": { + "message": "ここにフィードバックを書いてください…", + "description": "The placeholder for message input" + }, + "features.feedback-doc.modal-title": { + "message": "あなたの意見を共有してください", + "description": "The title of the modal displayed when the feedback form is opened" + }, + "features.feedback-doc.modal-title-error": { + "message": "おっと！", + "description": "The title of the modal displayed when the feedback form submission fails" + }, + "features.feedback-doc.modal-title-success": { + "message": "フィードバックありがとうございます！", + "description": "The title of the modal displayed when the feedback form submission is successful" + }, + "features.feedback-doc.rating-placeholder": { + "message": "このページは役に立ちましたか？", + "description": "The placeholder for rating input" + }, + "features.feedback-doc.rating-stars-placeholder": { + "message": "このページをどう評価しますか", + "description": "The placeholder for rating stars input" + }, + "features.feedback-doc.screenshot-button-text": { + "message": "スクリーンショットを撮る", + "description": "The text on a button to take a screenshot" + }, + "features.feedback-doc.screenshot-topbar-text": { + "message": "ページ上の要素を選択してください", + "description": "The text displayed in the top bar of the screenshot tool" + }, + "features.feedback-doc.send-button-text": { + "message": "送信", + "description": "The text on a button to send feedback" + }, + "features.hero.tagline": { + "message": "フロントエンドアーキテクチャの設計方法論", + "description": "Architectural methodology for frontend projects" + }, + "features.hero.get_started": { + "message": "始める", + "description": "Get Started" + }, + "features.hero.examples": { + "message": "実装例", + "description": "Examples" + }, + "features.hero.previous": { + "message": "前のバージョン", + "description": "Previous version" + }, + "shared.wip.title": { + "message": "この記事は執筆中です", + "description": "Admonition title" + }, + "shared.wip.subtitle": { + "message": "その公開を早めるために、以下の方法があります。", + "description": "Admonition subtitle" + }, + "shared.wip.var.feedback.base": { + "message": "📢 フィードバックを共有する ", + "description": "Variant for contribute (base)" + }, + "shared.wip.var.feedback.link": { + "message": "（チケットでのコメント/絵文字リアクション）", + "description": "Variant for contribute (link)" + }, + "shared.wip.var.material.base": { + "message": "💬 チャットでの議論結果をチケットにまとめる ", + "description": "Variant for contribute (base)" + }, + "shared.wip.var.material.link": { + "message": "（チャットURL）", + "description": "Variant for contribute (link)" + }, + "shared.wip.var.contribute.base": { + "message": "⚒️ 他の方法で", + "description": "Variant for contribute (base)" + }, + "shared.wip.var.contribute.link": { + "message": "貢献する", + "description": "Variant for contribute (link)" + }, + "theme.NotFound.title": { + "message": "ページが見つかりません", + "description": "The title of the 404 page" + }, + "theme.NotFound.p1": { + "message": "申し訳ありませんが、リクエストされたページが見つかりませんでした。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "リンク元のサイトの所有者に連絡して、リンクが機能しないことを知らせてください。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "閉じる", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "ブログリストページのナビゲーション", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "次のエントリ", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "前のエントリ", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.readingTime.plurals": { + "message": "{readingTime} 分の読書", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.tags.tagsListLabel": { + "message": "タグ：", + "description": "The label alongside a tag list" + }, + "theme.blog.post.readMore": { + "message": "続きを読む", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "ブログ投稿ページのナビゲーション", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "次の投稿", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "前の投稿", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.tags.tagsPageTitle": { + "message": "タグ", + "description": "The title of the tag list page" + }, + "theme.blog.post.plurals": { + "message": "{count} 投稿|{count} 投稿|{count} 投稿", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} のタグ \"{tagName}\"", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "すべてのタグを見る", + "description": "The label of the link targeting the tag list page" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "クリップボードにコピー", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copied": { + "message": "コピーしました", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copy": { + "message": "コピー", + "description": "The copy button label on code blocks" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "サイドバーを展開", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "サイドバーを展開", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "ドキュメントページのナビゲーション", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "前のページ", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "次のページ", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "サイドバーを折りたたむ", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "サイドバーを折りたたむ", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.responsiveCloseButtonLabel": { + "message": "メニューを閉じる", + "description": "The ARIA label for close button of mobile doc sidebar" + }, + "theme.docs.sidebar.responsiveOpenButtonLabel": { + "message": "メニューを開く", + "description": "The ARIA label for open button of mobile doc sidebar" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "これは{siteTitle} {versionLabel}の将来のバージョンのドキュメントです。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "これは{siteTitle}の{versionLabel}バージョンのドキュメントで、現在はサポートされていません。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新のドキュメントは{latestVersionLink}（{versionLabel}）にあります。", + "description": "The label userd to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新バージョン", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "このページを編集", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "この見出しへの直接リンク", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": " {date}", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": " {user}", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最終更新{atDate}{byUser}", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.common.skipToMainContent": { + "message": "メインコンテンツにスキップ", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + } +} diff --git a/i18n/ja/docusaurus-plugin-content-docs/community/index.mdx b/i18n/ja/docusaurus-plugin-content-docs/community/index.mdx new file mode 100644 index 0000000000..713ae1b412 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/community/index.mdx @@ -0,0 +1,40 @@ +--- +hide_table_of_contents: true +--- + +# 💫 コミュニティ + +
+コミュニティリソースと追加資料 +
+ +## メイン {#main} + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { StarOutlined, SearchOutlined, TeamOutlined, VerifiedOutlined } from "@ant-design/icons"; + ++FSD設計方法論、チーム、コミュニティ、そして発展の歴史に関する一般情報 +
+ +## 主な内容 {#main} + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { StarOutlined, TrophyOutlined, BulbOutlined, TeamOutlined } from "@ant-design/icons"; + +| テーマ | +ロゴ (Ctrl/Cmd + Clickでダウンロード) | +使用法 | +
| primary (#29BEDC, #517AED) |
+ |
+ ほとんどの場合に推奨されます | +
| flat (#3193FF) |
+ |
+ 単色コンテキスト用 | +
| monochrome (#FFF) |
+ |
+ 白黒コンテキスト用 | +
| square (#3193FF) |
+ |
+ 正方形サイズ用 | +
+
+
+## ソーシャルプレビュー
+
+作業中...
+
+## プレゼンテーションテンプレート {#presentation-template}
+
+作業中...
+
+## 参照 {#see-also}
+
+- [ディスカッション (github)](https://github.com/feature-sliced/documentation/discussions/399)
+- [リブランディングの歴史と参考資料 (figma)](https://www.figma.com/file/RPphccpoeasVB0lMpZwPVR/FSD-Brand?node-id=0%3A1)
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
new file mode 100644
index 0000000000..d5d502f9b4
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
@@ -0,0 +1,28 @@
+---
+# sidebar_position: 3
+unlisted: true
+---
+
+# 分解のチートシート
+
+インターフェースをレイヤーに分割する際の参考書として使用してください。以下にPDFバージョンもあり、印刷して枕の下に置いておくことができます。
+
+## レイヤーの選択 {#choosing-a-layer}
+
+[PDFをダウンロード](/files/choosing-a-layer-en.pdf)
+
+
+
+## 例 {#examples}
+
+### ツイート
+
+
+
+### GitHub
+
+
+
+## 参照 {#see-also}
+
+- [(記事) ロジックの分解におけるさまざまなアプローチ](https://www.pluralsight.com/resources/blog/guides/how-to-organize-your-react--redux-codebase)
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/faq.md
new file mode 100644
index 0000000000..8d24ada9e0
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/faq.md
@@ -0,0 +1,68 @@
+---
+sidebar_position: 20
+pagination_next: guides/index
+---
+
+# FAQ
+
+:::info
+
+質問は、[Discordコミュニティ][discord]、[GitHub Discussions][github-discussions]、および[Telegramチャット][telegram]で聞くことができます。
+
+:::
+
+### ツールキットやリンターはありますか？ {#is-there-a-toolkit-or-a-linter}
+
+はい！CLI または IDE を通じてプロジェクトのアーキテクチャと [フォルダー ジェネレーター][ext-tools] をチェックするための [Steiger][ext-steiger] というリンターがあります。
+
+### ページのレイアウト/テンプレートはどこに保存すればよいですか？ {#where-to-store-the-layouttemplate-of-pages}
+
+シンプルなレイアウトテンプレートが必要な場合は、`shared/ui`に保存できます。より上層のレイヤーを使用する必要がある場合、いくつかのオプションがあります。
+
+- レイアウトが本当に必要ですか？レイアウトが数行で構成されている場合、各ページにコードを重複させる方が合理的です。
+- レイアウトが必要な場合は、個別のウィジェットやページとして保存し、App層のルーター設定にそれらを組み合わせることができます。ネストされたルーティングも一つのオプションです。
+
+### フィーチャーとエンティティの違いは何ですか？ {#what-is-the-difference-between-feature-and-entity}
+
+エンティティはアプリケーションが扱う現実世界の概念です。フィーチャーはユーザーに実際の価値を提供するインタラクションであり、ユーザーがエンティティで行いたいことです。
+
+詳細および例については、参考書セクションの[スライスについてのページ][reference-entities]を参照してください。
+
+### ページ/フィーチャー/エンティティを相互に埋め込むことはできますか？ {#can-i-embed-pagesfeaturesentities-into-each-other}
+
+はい、しかし、この埋め込みはより上層のレイヤーで行う必要があります。例えば、ウィジェット内で両方のフィーチャーをインポートし、プロップス/子要素として一方のフィーチャーを他方に挿入することができます。
+
+一方のフィーチャーを他方のフィーチャーからインポートすることはできません。これは[**レイヤーのインポートルール**][import-rule-layers]で禁止されています。
+
+### Atomic Designはどうですか？ {#what-about-atomic-design}
+
+現在、アトミックデザインをFeature-Sliced Designと一緒に使用することを義務付けていませんが、禁止もしていません。
+
+アトミックデザインは、モジュールの`ui`セグメントにうまく適用できます。
+
+### FSDに関する有用なリソース/記事などはありますか？ {#are-there-any-useful-resourcesarticlesetc-about-fsd}
+
+はい！ https://github.com/feature-sliced/awesome
+
+### なぜFeature-Sliced Designが必要なのですか？ {#why-do-i-need-feature-sliced-design}
+
+FSDは、プロジェクトの主要な価値を提供するコンポーネントの観点から、あなたとあなたのチームが迅速にプロジェクトを把握するのに役立ちます。標準化されたアーキテクチャは、オンボーディングを迅速化し、コード構造に関する議論を解決するのに役立ちます。FSDが作成された理由については、[モチベーション][motivation]のページを参照してください。
+
+### 初心者の開発者にFSDのアーキテクチャ/設計方法論は必要ですか？ {#does-a-novice-developer-need-an-architecturemethodology}
+
+おそらく必要です。
+
+*通常、一人でプロジェクトを設計・開発する場合、すべてが順調に進みます。しかし、開発に中断が生じたり、新しい開発者がチームに加わると問題が発生します。*
+
+### 認証コンテキストをどのように扱えばよいですか？ {#how-do-i-work-with-the-authorization-context}
+
+[こちら](/docs/guides/examples/auth)で回答しています。
+
+[ext-steiger]: https://github.com/feature-sliced/steiger
+[ext-tools]: https://github.com/feature-sliced/awesome?tab=readme-ov-file#tools
+[import-rule-layers]: /docs/reference/layers#import-rule-on-layers
+[reference-entities]: /docs/reference/layers#entities
+[motivation]: /docs/about/motivation
+[telegram]: https://t.me/feature_sliced
+[discord]: https://discord.gg/S8MzWTUsmp
+[github-discussions]: https://github.com/feature-sliced/documentation/discussions
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/index.mdx
new file mode 100644
index 0000000000..75b532c1b0
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/get-started/index.mdx
@@ -0,0 +1,38 @@
+---
+hide_table_of_contents: true
+pagination_prev: intro
+---
+
+import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx"
+import { RocketOutlined, PlaySquareOutlined, QuestionCircleOutlined } from "@ant-design/icons";
+
+# 🚀 クイックスタート
+
++ようこそ！このセクションでは、Feature-Sliced Designの適用方法とその基礎知識が簡単に紹介されます。また、FSDの主な利点とその作成理由についての内容も記載されています。 +
+ +上の図には、左から右に「レイヤー」、「スライス」、「セグメント」とラベル付けされた3つの列があります。
+「レイヤー」列には、上から下に「app」、「processes」、「pages」、「widgets」、「features」、「entities」、「shared」とラベル付けされた7つの区分があります。「processes」区分は取り消し線が引かれています。「entities」区分は2番目の列「スライス」と接続されていて、2番目の列が「entities」の内容であることを示しています。
+「スライス」列には、上から下に「user」、「post」、「comment」とラベル付けされた3つの区分があります。「post」区分は「セグメント」列と同様に接続されていて、「post」の内容であることを示しています。
+「セグメント」列には、上から下に「ui」、「model」、「api」とラベル付けされた3つの区分があります。
+
+
+ );
+}
+```
+
+次に、このコンポーネントをフィードページの公開APIに再エクスポートします。
+
+```tsx title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+```
+
+次に、ルートに接続します。Remixでは、ルーティングはファイルに基づいていて、ルートファイルは`app/routes`フォルダーにあります。これはFeature-Sliced Designとよく組み合っています。
+
+`app/routes/_index.tsx`で`FeedPage`コンポーネントを使用します。
+
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
+
+export default FeedPage;
+```
+
+これで、devサーバーを起動し、アプリケーションを開くと、Conduitのバナーが表示されるはずです！
+
+
+
+### APIクライアント
+
+RealWorldのバックエンドと通信するために、Shared層内に便利なAPIクライアントを作成しましょう。クライアント用の`api`セグメントと、バックエンドの基本URLなどの変数用の`config`セグメントを作成します。
+
+```bash
+npx fsd shared --segments api config
+```
+
+次に、`shared/config/backend.ts`を作成します。
+
+```tsx title="shared/config/backend.ts"
+export const backendBaseUrl = "https://api.realworld.io/api";
+```
+
+```tsx title="shared/config/index.ts"
+export { backendBaseUrl } from "./backend";
+```
+
+RealWorldプロジェクトは[OpenAPI仕様](https://github.com/gothinkster/realworld/blob/main/api/openapi.yml)を提供しているため、APIクライアントの型を自動的に生成できます。私たちは[`openapi-fetch`パッケージ](https://openapi-ts.pages.dev/openapi-fetch/)を使用します。このパッケージにはTypeScriptの型を自動生成するツールも含まれています。
+
+次のコマンドを実行して、APIの最新の型を生成しましょう。
+
+```bash
+npm run generate-api-types
+```
+
+その結果、`shared/api/v1.d.ts`ファイルが作成されます。このファイルを使用して、`shared/api/client.ts`で型付きAPIクライアントを作成します。
+
+```tsx title="shared/api/client.ts"
+import createClient from "openapi-fetch";
+
+import { backendBaseUrl } from "shared/config";
+import type { paths } from "./v1";
+
+export const { GET, POST, PUT, DELETE } = createClient
+
+
+
+ conduit
+知識を共有する場
+
+
+ );
+}
+```
+
+「いいね」ボタンはまだ機能していません。それは記事の読み取りページに移動して、「いいね」機能を実装するときに修正します。
+
+これで、記事を取得して、たくさんのプレビューカードを表示できます。Remixでは、データの取得は*ローダー*を使用して行われます。ローダーは、ページに必要なデータを収集するサーバー関数です。ローダーはページの代わりにAPIとやり取りをするため、`api`セグメントに配置します。
+
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+
+import { GET } from "shared/api";
+
+export const loader = async () => {
+ const { data: articles, error, response } = await GET("/articles");
+
+ if (error !== undefined) {
+ throw json(error, { status: response.status });
+ }
+
+ return json({ articles });
+};
+```
+
+これをページに接続するには、ルートファイルから`loader`としてエクスポートする必要があります。
+
+```tsx title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+export { loader } from "./api/loader";
+```
+
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
+
+export { loader } from "pages/feed";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
+
+export default FeedPage;
+```
+
+最後のステップは、これらのカードをフィードに表示することです。`FeedPage`を次のコードで更新します。
+
+```tsx title="pages/feed/ui/FeedPage.tsx"
+import { useLoaderData } from "@remix-run/react";
+
+import type { loader } from "../api/loader";
+import { ArticlePreview } from "./ArticlePreview";
+
+export function FeedPage() {
+ const { articles } = useLoaderData
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ 続きを読む... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
+```
+
+### タグによるフィルタリング
+
+タグに関しては、バックエンドから取得し、ユーザーが選択したタグを記憶する必要があります。私たちはバックエンドからの取得方法はすでに知っています。これはローダー関数からの別のリクエストです。すでにインストールされている`remix-utils`パッケージの便利な`promiseHash`関数を使用します。
+
+`pages/feed/api/loader.ts`のローダーを次のコードで更新します。
+
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+知識を共有する場
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+ );
+}
+```
+
+次に、タグの検索パラメータをローダーで使用する必要があります。`pages/feed/api/loader.ts`の`loader`関数を次のように変更します。
+
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+知識を共有する場
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ 人気のタグ
+ + +
+
+ );
+}
+```
+
+よし、これも実現しました。タグ一覧も同様に実装できますが、認証を実装するまで待ちましょう。ところで、認証についてですが！
+
+### 認証
+
+認証には、ログイン用のページと登録用のページの2つがあります。これらは主に非常に似ているため、必要に応じてコードを再利用できるように、1つの`sign-in`セグメントに保持するのが理にかなっています。
+
+`pages/sign-in`の`ui`セグメントに`RegisterPage.tsx`を作成し、次の内容を配置します。
+
+```tsx title="pages/sign-in/ui/RegisterPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
+
+import type { register } from "../api/register";
+
+export function RegisterPage() {
+ const registerData = useActionData
+
+
+
+
+ conduit
+知識を共有する場
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ 人気のタグ
+ + +
+
+ );
+}
+```
+
+これからは壊れたインポートを修正する必要があります。インポートが新しいセグメントにアクセスしているため、次のコマンドでそのセグメントを作成しましょう。
+
+```bash
+npx fsd pages sign-in -s api
+```
+
+ただし、登録のバックエンド部分を実装する前に、Remixのセッション処理のためのインフラコードが必要です。これは他のページでも必要になる可能性があるため、Shared層に配置します。
+
+次のコードを`shared/api/auth.server.ts`に配置しましょう。このコードはRemixに特有のものであり、すべてが理解できなくても心配しないでください。単にコピーして貼り付けてください。
+
+```tsx title="shared/api/auth.server.ts"
+import { createCookieSessionStorage, redirect } from "@remix-run/node";
+import invariant from "tiny-invariant";
+
+import type { User } from "./models";
+
+invariant(
+ process.env.SESSION_SECRET,
+ "SESSION_SECRET must be set for authentication to work",
+);
+
+const sessionStorage = createCookieSessionStorage<{
+ user: User;
+}>({
+ cookie: {
+ name: "__session",
+ httpOnly: true,
+ path: "/",
+ sameSite: "lax",
+ secrets: [process.env.SESSION_SECRET],
+ secure: process.env.NODE_ENV === "production",
+ },
+});
+
+export async function createUserSession({
+ request,
+ user,
+ redirectTo,
+}: {
+ request: Request;
+ user: User;
+ redirectTo: string;
+}) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ session.set("user", user);
+
+ return redirect(redirectTo, {
+ headers: {
+ "Set-Cookie": await sessionStorage.commitSession(session, {
+ maxAge: 60 * 60 * 24 * 7, // 7日間
+ }),
+ },
+ });
+}
+
+export async function getUserFromSession(request: Request) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ return session.get("user") ?? null;
+}
+
+export async function requireUser(request: Request) {
+ const user = await getUserFromSession(request);
+
+ if (user === null) {
+ throw redirect("/login");
+ }
+
+ return user;
+}
+```
+
+また、`models.ts`ファイルから`User`モデルをエクスポートしてください。
+
+```tsx title="shared/api/models.ts"
+import type { components } from "./v1";
+
+export type Article = components["schemas"]["Article"];
+export type User = components["schemas"]["User"];
+```
+
+このコードが動作する前に、`SESSION_SECRET`環境変数を設定する必要があります。プロジェクトのルートに`.env`ファイルを作成し、`SESSION_SECRET=`を記述してから、適当にランダムな文字列を記入します。次のようになります。
+
+```bash title=".env"
+SESSION_SECRET=これをコピーしないでください
+```
+
+最後に、公開APIにいくつかのエクスポートを追加します。
+
+```tsx title="shared/api/index.ts"
+export { GET, POST, PUT, DELETE } from "./client";
+
+export type { Article } from "./models";
+
+export { createUserSession, getUserFromSession, requireUser } from "./auth.server";
+```
+
+これで、RealWorldのバックエンドと通信するコードを書くことができます。これを`pages/sign-in/api`に保存します。`register.ts`ファイルを作成して、中に次のコードを配置しましょう。
+
+```tsx title="pages/sign-in/api/register.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+
+import { POST, createUserSession } from "shared/api";
+
+export const register = async ({ request }: ActionFunctionArgs) => {
+ const formData = await request.formData();
+ const username = formData.get("username")?.toString() ?? "";
+ const email = formData.get("email")?.toString() ?? "";
+ const password = formData.get("password")?.toString() ?? "";
+
+ const { data, error } = await POST("/users", {
+ body: { user: { email, password, username } },
+ });
+
+ if (error) {
+ return json({ error }, { status: 400 });
+ } else {
+ return createUserSession({
+ request: request,
+ user: data.user,
+ redirectTo: "/",
+ });
+ }
+};
+```
+
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+```
+
+ほぼ完成です！残りの部分は、`/register`ルートにアクションとページを接続することだけです。`app/routes`で`register.tsx`を作成します。
+
+```tsx title="app/routes/register.tsx"
+import { RegisterPage, register } from "pages/sign-in";
+
+export { register as action };
+
+export default RegisterPage;
+```
+
+これで、[http://localhost:3000/register](http://localhost:3000/register)にアクセスすると、ユーザーを作成できます！アプリケーションの残りの部分は、まだ反応しませんが、近々対処します。
+
+同様に、ログインページを実装することもできます。自分で実装してみるか、下記のコードをコピペするか、次に進みましょう。
+
+```tsx title="pages/sign-in/api/sign-in.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+
+import { POST, createUserSession } from "shared/api";
+
+export const signIn = async ({ request }: ActionFunctionArgs) => {
+ const formData = await request.formData();
+ const email = formData.get("email")?.toString() ?? "";
+ const password = formData.get("password")?.toString() ?? "";
+
+ const { data, error } = await POST("/users/login", {
+ body: { user: { email, password } },
+ });
+
+ if (error) {
+ return json({ error }, { status: 400 });
+ } else {
+ return createUserSession({
+ request: request,
+ user: data.user,
+ redirectTo: "/",
+ });
+ }
+};
+```
+
+```tsx title="pages/sign-in/ui/SignInPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
+
+import type { signIn } from "../api/sign-in";
+
+export function SignInPage() {
+ const signInData = useActionData
+
+
+
+
+
+ 登録
++ アカウントをお持ちですか？ +
+ + {registerData?.error && ( +-
+ {registerData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
+```
+
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+export { SignInPage } from './ui/SignInPage';
+export { signIn } from './api/sign-in';
+```
+
+```tsx title="app/routes/login.tsx"
+import { SignInPage, signIn } from "pages/sign-in";
+
+export { signIn as action };
+
+export default SignInPage;
+```
+
+これで、ユーザーがこれらのページにアクセスできるようになりました。
+
+### ヘッダー
+
+前章で説明されたように、アプリケーションのヘッダーは通常Widgets層、またはShared層に配置されます。ヘッダーは非常にシンプルで、すべてのビジネスロジックを外部に保持できるので、Shared層に配置しましょう。ヘッダー用のフォルダーを作成します。
+
+```bash
+npx fsd shared ui
+```
+
+次に、`shared/ui/Header.tsx`を作成し、次の内容を配置します。
+
+```tsx title="shared/ui/Header.tsx"
+import { useContext } from "react";
+import { Link, useLocation } from "@remix-run/react";
+
+import { CurrentUser } from "../api/currentUser";
+
+export function Header() {
+ const currentUser = useContext(CurrentUser);
+ const { pathname } = useLocation();
+
+ return (
+
+ );
+}
+```
+
+このコンポーネントを`shared/ui`からエクスポートします。
+
+```tsx title="shared/ui/index.ts"
+export { Header } from "./Header";
+```
+
+ヘッダーで`shared/api`にあるコンテキストを使っているので、それを作成しましょう。
+
+```tsx title="shared/api/currentUser.ts"
+import { createContext } from "react";
+
+import type { User } from "./models";
+
+export const CurrentUser = createContext
+
+
+
+
+
+ サインイン
++ アカウントが必要ですか？ +
+ + {signInData?.error && ( +-
+ {signInData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
+```
+
+```tsx title="pages/feed/ui/Pagination.tsx"
+import { Form, useLoaderData, useSearchParams } from "@remix-run/react";
+import { ExistingSearchParams } from "remix-utils/existing-search-params";
+
+import { LIMIT, type loader } from "../api/loader";
+
+export function Pagination() {
+ const [searchParams] = useSearchParams();
+ const { articles } = useLoaderData人気のタグ
+ + +
+
+ );
+}
+```
+
+ローダー関数にも新しいタブを考慮する必要があります。
+
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET, requireUser } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+知識を共有する場
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+このコードは、`/article/:slug`にPOSTリクエストを送信し、`_action=favorite`を使用して記事をお気に入りにします。今は機能していませんが、記事リーダーの作成を始めると、これも実装します。
+
+これで、フィードの作成が完了しました！やったね！
+
+### 記事リーダー
+
+まず、データが必要です。ローダーを作成しましょう。
+
+```bash
+npx fsd pages article-read -s api
+```
+
+```tsx title="pages/article-read/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import invariant from "tiny-invariant";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET, getUserFromSession } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ もっと読む... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
+```
+
+興味深いのは`ArticleMeta`と`Comments`です。これらは、記事を「いいね」したり、コメントを残したりするための操作を含んでいます。これらが機能するためには、まずバックエンド部分を実装する必要があります。このページの`api`セグメントに`action.ts`ファイルを作成します。
+
+```tsx title="pages/article-read/api/action.ts"
+import { redirect, type ActionFunctionArgs } from "@remix-run/node";
+import { namedAction } from "remix-utils/named-action";
+import { redirectBack } from "remix-utils/redirect-back";
+import invariant from "tiny-invariant";
+
+import { DELETE, POST, requireUser } from "shared/api";
+
+export const action = async ({ request, params }: ActionFunctionArgs) => {
+ const currentUser = await requireUser(request);
+
+ const authorization = { Authorization: `Token ${currentUser.token}` };
+
+ const formData = await request.formData();
+
+ return namedAction(formData, {
+ async delete() {
+ invariant(params.slug, "スラッグパラメータが必要です");
+ await DELETE("/articles/{slug}", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirect("/");
+ },
+ async favorite() {
+ invariant(params.slug, "スラッグパラメータが必要です");
+ await POST("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfavorite() {
+ invariant(params.slug, "スラッグパラメータが必要です");
+ await DELETE("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async createComment() {
+ invariant(params.slug, "スラッグパラメータが必要です");
+ const comment = formData.get("comment");
+ invariant(typeof comment === "string", "コメントパラメータが必要です");
+ await POST("/articles/{slug}/comments", {
+ params: { path: { slug: params.slug } },
+ headers: { ...authorization, "Content-Type": "application/json" },
+ body: { comment: { body: comment } },
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async deleteComment() {
+ invariant(params.slug, "スラッグパラメータが必要です");
+ const commentId = formData.get("id");
+ invariant(typeof commentId === "string", "idパラメータが必要です");
+ const commentIdNumeric = parseInt(commentId, 10);
+ invariant(
+ !Number.isNaN(commentIdNumeric),
+ "数値のidパラメータが必要です",
+ );
+ await DELETE("/articles/{slug}/comments/{id}", {
+ params: { path: { slug: params.slug, id: commentIdNumeric } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async followAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "ユーザーネームパラメータが必要です",
+ );
+ await POST("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfollowAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "ユーザーネームパラメータが必要です",
+ );
+ await DELETE("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ });
+};
+```
+
+これをスライスから再エクスポートし、ルートから再エクスポートします。ここにいる間に、ページ自体も接続しましょう。
+
+```tsx title="pages/article-read/index.ts"
+export { ArticleReadPage } from "./ui/ArticleReadPage";
+export { loader } from "./api/loader";
+export { action } from "./api/action";
+```
+
+```tsx title="app/routes/article.$slug.tsx"
+import { ArticleReadPage } from "pages/article-read";
+
+export { loader, action } from "pages/article-read";
+
+export default ArticleReadPage;
+```
+
+これで、記事リーダーの「いいね」ボタンはまだ実装されていないにも関わらず、フィードの「いいね」ボタンは機能し始めます！それは、フィードの「いいね」ボタンもそのルートにリクエストを送っているからです。何かを「いいね」してみてください！
+
+`ArticleMeta`と`Comments`は、単なるフォームです。以前にこれを行ったので、コードをコピペして先に進みましょう。
+
+```tsx title="pages/article-read/ui/ArticleMeta.tsx"
+import { Form, Link, useLoaderData } from "@remix-run/react";
+import { useContext } from "react";
+
+import { CurrentUser } from "shared/api";
+import type { loader } from "../api/loader";
+
+export function ArticleMeta() {
+ const currentUser = useContext(CurrentUser);
+ const { article } = useLoaderData
+
+
+
+
+ {article.article.title}
+ +
+
+ +
+
+
+
+
+
+ {article.article.body}
+-
+ {article.article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+ +
+
+
+
+
+
+ {currentUser !== null ? (
+
+ ) : (
+
+ );
+}
+```
+
+これで、記事リーダーが完成しました！「著者をフォローする」ボタン、「いいね」ボタン、「コメントを残す」ボタンがすべて正常に機能するはずです。
+
+
+
+ )}
+
+ {comments.comments.map((comment) => (
+
+
+ + サインイン + または + 登録 + して記事にコメントを追加しましょう！ +
+
+
+ ))}
+
+
+
+ {comment.body}
+
+
+
+
+
+
+ {comment.author.username}
+
+ {comment.createdAt}
+ {comment.author.username === currentUser?.username && (
+
+
+
+ )}
+
+
+
+ );
+}
+```
+
+このページは、存在する記事を取得し（新しい記事を作成する場合を除く）、対応するフォームフィールドを埋めます。これは以前に見たものです。着目すべき部分は`FormErrors`で、これは検証結果を取得し、ユーザーに表示します。
+
+```tsx title="pages/article-edit/ui/FormErrors.tsx"
+import { useActionData } from "@remix-run/react";
+import type { action } from "../api/action";
+
+export function FormErrors() {
+ const actionData = useActionData
+
+
+
+
+
+ -
+ {actionData.errors.map((error) => (
+
- {error} + ))} +
+ {tagListState.map((tag) => (
+
+
+ [" ", "Enter"].includes(e.key) && removeTag(tag)
+ }
+ onClick={() => removeTag(tag)}
+ >{" "}
+ {tag}
+
+ ))}
+
+
+ );
+}
+```
+
+次に、API部分に移ります。ローダーはURLを確認し、記事へのリンクがある場合、既存の記事を編集していることを意味し、そのデータをロードする必要があります。そうでない場合は、何も返しません。このローダーを作成しましょう。
+
+```tsx title="pages/article-edit/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+
+import { GET, requireUser } from "shared/api";
+
+async function throwAnyErrors+小さな実践的な例を通じて、FSDの適用方法を示します。 +
+ +## 主要 {#main} + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { UserSwitchOutlined, LayoutOutlined, FontSizeOutlined } from "@ant-design/icons"; + +
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+```ts title="shared/ui/layout/useThemeSwitcher.ts"
+export function useThemeSwitcher() {
+ const [theme, setTheme] = useState("light");
+
+ function toggleTheme() {
+ setTheme(theme === "light" ? "dark" : "light");
+ }
+
+ useEffect(() => {
+ document.body.classList.remove("light", "dark");
+ document.body.classList.add(theme);
+ }, [theme]);
+
+ return [theme, toggleTheme] as const;
+}
+```
+
+
+サイドバーのコードは読者に課題として残されています！
+
+## レイアウトでのウィジェットの使用
+
+時には、特定のビジネスロジックをレイアウトに組み込む必要があります。特に、[React Router][ext-react-router]のような深くネストされたルートを使用している場合、Shared層やWidgets層にレイアウトを保存することはできません。これは[レイヤーのインポートルール][import-rule-on-layers]に違反しています。
+
+> スライス内のモジュールは、下層にあるスライスのみをインポートできる。
+
+解決策を議論する前に、これが実際に問題かどうかを確認する必要があります。このレイアウトは本当に必要なのか？もしそうなら、ウィジェットとして実装することが最適なのかも再考する必要があるでしょう。もしビジネスロジックのブロックが2〜3ページで使用され、レイアウトがそのウィジェットの小さなラッパーに過ぎない場合、次の2つのオプションを検討してください。
+
+1. **レイアウトをApp層のルーターで直接作成する**
+ これは、ネストをサポートするルーターに最適です。特定のルートをグループ化し、必要なレイアウトをそれらにのみ適用できます。
+
+2. **単にコピーする**
+ コードを抽象化する欲求はしばしば過大評価されます。特にレイアウトに関しては、変更がほとんどないためです。ある時点で、これらのページの1つが変更を必要とする場合、他のページに影響を与えずに変更を加えることができます。他のページを更新することを忘れるかもしれないと心配している場合は、ページ間の関係を説明するコメントを残すことができます。
+
+上記のいずれのオプションも適用できない場合、ウィジェットをレイアウトに組み込むための2つの解決策があります。
+
+1. **レンダープロップまたはスロットを使用する**
+ ほとんどのフレームワークは、UIの一部を外部から渡すことを許可しています。Reactではこれを[レンダープロップ][ext-render-props]と呼び、Vueでは[スロット][ext-vue-slots]と呼びます。
+
+2. **レイアウトをApp層に移動する**
+ レイアウトをApp層に保存し、必要なウィジェットを組み合わせることもできます。
+
+## 追加資料
+
+- ReactとRemixを使用した認証付きレイアウトの作成例は[チュートリアル][tutorial]で見つけることができます（React Routerに類似する）。
+
+[tutorial]: /docs/get-started/tutorial
+[import-rule-on-layers]: /docs/reference/layers#import-rule-on-layers
+[ext-react-router]: https://reactrouter.com/
+[ext-render-props]: https://www.patterns.dev/react/render-props-pattern/
+[ext-vue-slots]: https://jp.vuejs.org/guide/components/slots
\ No newline at end of file
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/examples/platforms.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/examples/platforms.mdx
new file mode 100644
index 0000000000..79f3389bb6
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/examples/platforms.mdx
@@ -0,0 +1,10 @@
+---
+sidebar_class_name: sidebar-item--wip
+unlisted: true
+---
+
+import WIP from '@site/src/shared/ui/wip/tmpl.mdx'
+
+# デスクトップ/タッチプラットフォーム
+
++Feature-Sliced Designの適用に関する実践的なガイドと例です。このセクションでは、移行ガイドや悪習のハンドブックも説明されています。具体的な何かを実現しようとしているときや、FSDを「実戦」で見たいときに最も役立ちます。 +
+ +## 主な内容 {#main} + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { ToolOutlined, ImportOutlined, BugOutlined, FunctionOutlined } from "@ant-design/icons"; + +
+
+
+## 開始前に {#before-you-start}
+
+Feature-Sliced Designへの移行を検討する際に、チームに最も重要な質問は「本当に必要か？」です。私たちはFeature-Sliced Designが好きですが、いくつかのプロジェクトはそれなしでうまくいけることを認めています。
+
+移行を検討すべき理由はいくつかあります。
+
+1. 新しいチームメンバーが生産的なレベルに達するのが難しいと不満を言う。
+2. コードの一部を変更すると、**しばしば**他の無関係な部分が壊れる。
+3. 巨大なコードベースのため、新しい機能を追加するのが難しい。
+
+**同僚の意に反してFSDに移行することは避けてください**。たとえあなたがチームリーダーであっても、まずは同僚を説得し、移行の利点がコストを上回ることを理解させる必要があります。
+
+また、アーキテクチャの変更は、瞬時には経営陣には見えないことを覚えておいてください。始める前に、経営陣が移行を支持していることを確認し、この移行がプロジェクトにどのように役立つかを説明してください。
+
+:::tip
+
+プロジェクトマネージャーをFSDの有用性に納得させるためのアイデアをいくつか紹介します。
+
+1. FSDへの移行は段階的に行えるため、新機能の開発を止めることはありません。
+2. 良いアーキテクチャは、新しい開発者が生産性を達成するのにかかる時間を大幅に短縮できます。
+3. FSDは文書化されたアーキテクチャであるため、チームは独自の文書を維持するために常に時間を費やす必要がありません。
+
+:::
+
+---
+
+もし移行を始める決断をした場合、最初に行うべきことは`📁 src`のエイリアスを設定することです。これは、後で上位フォルダを参照するのに便利です。以降のテキストでは、`@`を`./src`のエイリアスとして扱います。
+
+## ステップ１。コードをページごとに分割する {#divide-code-by-pages}
+
+ほとんどのカスタムアーキテクチャは、ロジックのサイズに関係なく、すでにページごとに分割されています。もし`📁 pages`がすでに存在する場合は、このステップをスキップできます。
+
+もし`📁 routes`しかない場合は、`📁 pages`を作成し、できるだけ多くのコンポーネントコードを`📁 routes`から移動させてみてください。理想的には、小さなルートファイルと大きなページファイルがあることです。コードを移動させる際には、各ページのためのフォルダを作成し、その中にインデックスファイルを追加します。
+
+:::note
+
+現時点では、ページ同士が互いにインポートすることは問題ありません。後でこれらの依存関係を解消するための別のステップがあります。今はページごとの明確な分割を確立することに集中します。
+
+:::
+
+ルートファイル
+
+```js title="src/routes/products.[id].js"
+export { ProductPage as default } from "@/pages/product"
+```
+
+ページのインデックスファイル
+
+```js title="src/pages/product/index.js"
+export { ProductPage } from "./ProductPage.jsx"
+```
+
+ページコンポーネントファイル
+
+```jsx title="src/pages/product/ProductPage.jsx"
+export function ProductPage(props) {
+ return ;
+}
+```
+
+## ステップ２。 ページ以外のすべてを分離する {#separate-everything-else-from-pages}
+
+`📁 src/shared`フォルダを作成し、`📁 pages`や`📁 routes`からインポートされないすべてをそこに移動します。`📁 src/app`フォルダを作成し、ページやルートをインポートするすべてをそこに移動します。
+
+Shared層にはスライスがないことを覚えておいてください。したがって、セグメントは互いにインポートできます。
+
+最終的には、次のようなファイル構造になるはずです。
+
+📁 src
+-
+
-
+ ++
📁 actions
+-
+
- 📁 product +
- 📁 order +
+ - 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
-
+ ++
📁 routes
+-
+
- 📁 products.jsx +
- 📄 products.[id].jsx +
+ - 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
- 📄 App.jsx +
- 📄 index.js +
+
+
+## ステップ３。 ページ間のクロスインポートを解消する {#tackle-cross-imports-between-pages}
+
+あるページが他のページから何かをインポートしているすべての箇所を見つけ、次のいずれかを行います。
+
+1. インポートされているコードを依存するページにコピーして、依存関係を取り除く。
+2. コードをShared層の適切なセグメントに移動する
+ - UIキットの一部であれば、`📁 shared/ui`に移動。
+ - 設定の定数であれば、`📁 shared/config`に移動。
+ - バックエンドとのやり取りであれば、`📁 shared/api`に移動。
+
+:::note
+
+**コピー自体はアーキテクチャの問題ではありません**。実際、時には新しい再利用可能なモジュールに何かを抽象化するよりも、何かを複製する方が正しい場合もあります。ページの共通部分が異なってくることがあるため、その場合、依存関係が妨げにならないようにする必要があります。
+
+ただし、DRY（"don't repeat yourself" — "繰り返さない"）の原則には意味があるため、ビジネスロジックをコピーしないようにしてください。そうしないと、バグを複数の箇所で修正することになることを頭に入れておく必要があります。
+
+:::
+
+## ステップ４。 Shared層を分解する {#unpack-shared-layer}
+
+この段階では、Shared層に多くのものが入っているかもしれませんが、一般的にはそのような状況を避けるべきです。理由は、Shared層に依存している他の層にあるコードが存在している可能性があるため、そこに変更を加えることは予期しない結果を引き起こす可能性が高くなります。
+
+特定のページでのみ使用されるすべてのオブジェクトを見つけ、それらをそのページのスライスに移動します。そして、_これにはアクション、リデューサー、セレクターも含まれます_。すべてのアクションを一緒にグループ化することには意味がありませんが、関連するアクションをその使用場所の近くに置くことには意味があります。
+
+最終的には、次のようなファイル構造になるはずです。
+
+📁 src
+-
+
-
+ ++
📁 app
+-
+
-
+ ++
📁 routes
+-
+
- 📄 products.jsx +
- 📄 products.[id].jsx +
+ - 📄 App.jsx +
- 📄 index.js +
+ -
+
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
-
+ ++
📁 ui
+-
+
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ -
+
- 📁 catalog +
+ -
+
-
+ ++
📁 shared
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
+
+
+## ステップ５。 コードを技術的な目的に基づいて整理する {#organize-by-technical-purpose}
+
+FSDでは、技術的な目的に基づく分割がセグメントによって行われます。よく見られるセグメントはいくつかあります。
+
+- `ui` — インターフェースの表示に関連するすべて: UIコンポーネント、日付のフォーマット、スタイルなど。
+- `api` — バックエンドとのやり取り: リクエスト関数、データ型、マッパーなど。
+- `model` — データモデル: スキーマ、インターフェース、ストレージ、ビジネスロジック。
+- `lib` — 他のモジュールに必要なライブラリコード。
+- `config` — 設定ファイルやフィーチャーフラグ。
+
+必要に応じて独自のセグメントを作成できます。ただし、コードをその性質によってグループ化するセグメント（例: `components`、`actions`、`types`、`utils`）を作成しないようにしてください。代わりに、コードの目的に基づいてグループ化してください。
+
+ページのコードをセグメントに再分配します。すでに`ui`セグメントがあるはずなので、今は他のセグメント（例えば、アクション、リデューサー、セレクターのための`model`や、サンクやミューテーションのための`api`）を作成するときです。
+
+また、Shared層を再分配して、次のフォルダを削除します。
+
+- `📁 components`、`📁 containers` — その内容のほとんどは`📁 shared/ui`になるべきです。
+- `📁 helpers`、`📁 utils` — 再利用可能なヘルパー関数が残っている場合は、目的に基づいてグループ化し、これらのグループを`📁 shared/lib`に移動します。
+- `📁 constants` — 同様に、目的に基づいてグループ化し、`📁 shared/config`に移動します。
+
+## 任意のステップ {#optional-steps}
+
+### ステップ６。 複数のページで使用されるReduxスライスからエンティティ/フィーチャーを形成する {#form-entities-features-from-redux}
+
+通常、これらの再利用可能なReduxスライスは、ビジネスに関連する何かを説明します（例えば、プロダクトやユーザーなど）。したがって、それらをエンティティ層に移動できます。1つのエンティティにつき1つのフォルダです。Reduxスライスが、ユーザーがアプリケーションで実行したいアクションに関連している場合（例えば、コメントなど）、それをフィーチャー層に移動できます。
+
+エンティティとフィーチャーは互いに独立している必要があります。ビジネス領域に組み込まれたエンティティ間の関係がある場合は、[ビジネスエンティティに関するガイド][business-entities-cross-relations]を参照して、これらの関係を整理する方法を確認してください。
+
+これらのスライスに関連するAPI関数は、`📁 shared/api`に残すことができます。
+
+### ステップ７。 モジュールをリファクタリングする {#refactor-your-modules}
+
+`📁 modules`フォルダは通常、ビジネスロジックに使用されるため、すでにFSDのフィーチャー層に似た性質を持っています。一部のモジュールは、アプリケーションの大きな部分（例えば、アプリのヘッダーなど）を説明することもあります。この場合、それらをウィジェット層に移動できます。
+
+### ステップ8。 `shared/ui`にUI基盤を正しく形成する {#form-clean-ui-foundation}
+
+理想的には、`📁 shared/ui`にはビジネスロジックが含まれていないUI要素のセットが含まれるべきです。また、非常に再利用可能である必要があります。
+
+以前`📁 components`や`📁 containers`にあったUIコンポーネントをリファクタリングして、ビジネスロジックを分離します。このビジネスロジックを上位層に移動します。あまり多くの場所で使用されていない場合は、コピーを検討することもできます。
+
+[ext-steiger]: https://github.com/feature-sliced/steiger
+[business-entities-cross-relations]: /docs/guides/examples/types#business-entities-and-their-cross-references
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md
new file mode 100644
index 0000000000..282faaecdc
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md
@@ -0,0 +1,154 @@
+---
+sidebar_position: 2
+---
+
+# v1からv2への移行
+
+## なぜv2なのか？ {#why-v2}
+
+初期の**feature-slices**の概念は、2018年に提唱されました。
+
+それ以来、FSD方法論は多くの変革を経てきましたが、基本的な原則は保持されています。
+
+- *標準化された*フロントエンドプロジェクト構造の使用
+- アプリケーションを*ビジネスロジック*に基づいて分割
+- *孤立した機能*の使用により、暗黙の副作用や循環依存を防止
+- モジュールの「内部」にアクセスすることを禁止する*公開API*の使用
+
+しかし、以前のバージョンのFSD方法論には依然として**弱点が残っていました**。
+
+- ボイラープレートの発生
+- コードベースの過剰な複雑化と抽象化間の明確でないルール
+- プロジェクトのメンテナンスや新しいメンバーのオンボーディングを妨げていた暗黙のアーキテクチャ的決定
+
+新しいバージョンのFSD方法論（[v2][ext-v2]）は、**これらの欠点を解消しつつ、既存の利点を保持することを目的としています**。
+
+2018年以降、[**feature-driven**][ext-fdd]という別の類似の方法論が[発展してきました][ext-fdd-issues]。それを最初に提唱したのは[Oleg Isonen][ext-kof]でした。
+
+2つのアプローチの統合により、**既存のプラクティスが改善され、柔軟性、明確さ、効率が向上しました**。
+
+> 結果として、方法論の名称も「feature-slice**d**」に変更されました。
+
+## なぜプロジェクトをv2に移行する意味があるのか？ {#why-does-it-make-sense-to-migrate-the-project-to-v2}
+
+> `WIP:` 現在の方法論のバージョンは開発中であり、一部の詳細は*変更される可能性があります*。
+
+#### 🔍 より透明でシンプルなアーキテクチャ {#-more-transparent-and-simple-architecture}
+
+FSD（v2）は、**より直感的で、開発者の間で広く受け入れられている抽象化とロジックの分割方法を提供しています**。
+
+これにより、新しいメンバーの参加やプロジェクトの現状理解、アプリケーションのビジネスロジック分配に非常に良い影響を与えます。
+
+#### 📦 より柔軟で誠実なモジュール性 {#-more-flexible-and-honest-modularity}
+
+FSD（v2）は、**より柔軟な方法でロジックを分配することを可能にしています**。
+
+- 孤立した部分をゼロからリファクタリングできる
+- 同じ抽象化に依存しつつ、余計な依存関係の絡みを避けられる
+- 新しいモジュールの配置をよりシンプルにできる *(layer → slice → segment)*
+
+#### 🚀 より多くの仕様、計画、コミュニティ {#-more-specifications-plans-community}
+
+`core-team`は最新の（v2）バージョンのFSD方法論に積極的に取り組んでいます。
+
+したがって、以下のことが期待できます。
+
+- より多くの記述されたケース/問題
+- より多くの適用ガイド
+- より多くの実例
+- 新しいメンバーのオンボーディングや方法論概念の学習のための全体的な文書の増加
+- 方法論の概念とアーキテクチャに関するコンベンションを遵守するためのツールキットのさらなる発展
+
+> もちろん、初版に対するユーザーサポートも行われますが、私たちにとっては最新のバージョンが最優先です。
+
+> 将来的には、次のメジャーアップデートの際に、現在のバージョン（v2）へのアクセスが保持され、**チームやプロジェクトにリスクをもたらすことはありません**。
+
+## Changelog
+
+### `BREAKING` Layers
+
+FSD方法論は上位レベルでの層の明示的な分離を前提としています。
+
+- `/app` > `/processes` > **`/pages`** > **`/features`** > `/entities` > `/shared`
+- *つまり、すべてがフィーチャーやページとして解釈されるわけではない*
+- このアプローチにより、層のルールを明示的に設定することが可能になる
+ - モジュールの**層が高いほど**、より多くの**コンテキスト**を持つことができる
+
+ *(言い換えれば、各層のモジュールは、下層のモジュールのみをインポートでき、上層のモジュールはインポートできない)*
+ - モジュールの**層が低いほど**、変更を加える際の**危険性と責任**が増す
+
+ *(一般的に、再利用されるのは下層のモジュールらからである)*
+
+### `BREAKING` Shared層
+
+以前はプロジェクトのsrcルートにあったインフラストラクチャの `/ui`, `/lib`, `/api` 抽象化は、現在 `/src/shared` という別のディレクトリに分離されています。
+
+- `shared/ui` - アプリケーションの共通UIキット（オプション）
+ - *ここで`Atomic Design`を使用することは引き続き許可されている*
+- `shared/lib` - ロジックを実装するための補助ライブラリセット
+ - *引き続き、ヘルパー関数の「ごみ屋敷」を作らずに*
+- `shared/api` - APIへのアクセスのための共通エントリポイント
+ - *各フィーチャー/ページにローカルに記述することも可能だが、推奨されない*
+- 以前と同様に、`shared`にはビジネスロジックへの明示的な依存関係があってはならない
+ - *必要に応じて、この依存関係は`entities`、またはそれ以上の層に移動する必要がある*
+
+### `新規` Entities層, Processes層
+
+v2では、**ロジックの複雑さと強い結合の問題を解消するために、新しい抽象化が追加されました**。
+
+- `/entities` - **ビジネスエンティティ**の層で、ビジネスモデルやフロントエンド専用の合成エンティティに関連するスライスを含む
+ - *例：`user`, `i18n`, `order`, `blog`*
+- `/processes` - アプリケーション全体にわたる**ビジネスプロセス**の層
+ - **この層はオプションであり、通常は*ロジックが拡大し、複数のページにまたがる場合に使用が推奨される***
+ - *例：`payment`, `auth`, `quick-tour`*
+
+### `BREAKING` 抽象化と命名
+
+具体的な抽象化とその命名に関する[明確なガイドライン][refs-adaptability]が定義されています。
+
+#### Layers
+
+- `/app` — **アプリケーションの初期化層**
+ - *以前のバリエーション: `app`, `core`, `init`, `src/index`*
+- `/processes` — **ビジネスプロセスの層**
+ - *以前のバリエーション: `processes`, `flows`, `workflows`*
+- `/pages` — **アプリケーションのページ層**
+ - *以前のバリエーション: `pages`, `screens`, `views`, `layouts`, `components`, `containers`*
+- `/features` — **機能部分の層**
+ - *以前のバリエーション: `features`, `components`, `containers`*
+- `/entities` — **ビジネスエンティティの層**
+ - *以前のバリエーション: `entities`, `models`, `shared`*
+- `/shared` — **再利用可能なインフラストラクチャコードの層** 🔥
+ - *以前のバリエーション: `shared`, `common`, `lib`*
+
+#### Segments
+
+- `/ui` — **UIセグメント** 🔥
+ - *以前のバリエーション：`ui`, `components`, `view`*
+- `/model` — **ビジネスロジックのセグメント** 🔥
+ - *以前のバリエーション：`model`, `store`, `state`, `services`, `controller`*
+- `/lib` — **補助コードのセグメント**
+ - *以前のバリエーション：`lib`, `libs`, `utils`, `helpers`*
+- `/api` — **APIセグメント**
+ - *以前のバリエーション：`api`, `service`, `requests`, `queries`*
+- `/config` — **アプリケーション設定のセグメント**
+ - *以前のバリエーション：`config`, `env`, `get-env`*
+
+### `REFINED` 低結合
+
+新しいレイヤーのおかげで、モジュール間の[低結合の原則][refs-low-coupling]を遵守することがはるかに簡単になりました。
+
+*それでも、モジュールを「切り離す」ことが非常に難しい場合は、できるだけ避けることが推奨されます*。
+
+## 参照 {#see-also}
+
+- [React Berlin Talk - Oleg Isonen "Feature Driven Architecture"][ext-kof-fdd]
+
+[refs-low-coupling]: /docs/reference/slices-segments#zero-coupling-high-cohesion
+[refs-adaptability]: /docs/about/understanding/naming
+
+[ext-fdd]: https://github.com/feature-sliced/documentation/tree/rc/feature-driven
+[ext-fdd-issues]: https://github.com/kof/feature-driven-architecture/issues
+[ext-v2]: https://github.com/feature-sliced/documentation
+[ext-kof]: https://github.com/kof
+[ext-kof-fdd]: https://www.youtube.com/watch?v=BWAeYuWFHhs
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md
new file mode 100644
index 0000000000..a29c7f7d2f
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 3
+---
+
+# v2.0からv2.1への移行
+
+v2.1の主な変更点は、インターフェースを分解するための「ページファースト」という新しいメンタルモデルです。
+
+v2.0では、FSDは分解のためにエンティティ表現やインタラクティビティの最小部分まで考慮し、インターフェース内のエンティティとフィーチャーを特定することを推奨していました。そうしてから、エンティティとフィーチャーからウィジェットやページが構築されていきました。この分解モデルでは、ほとんどのロジックはエンティティとフィーチャーにあり、ページはそれ自体にはあまり重要性のない構成層に過ぎませんでした。
+
+v2.1では、分解をページから始めること、または場合によってはページで止めることを推奨します。ほとんどの人はすでにアプリを個々のページに分ける方法を知っており、ページはコードベース内のコンポーネントを見つける際の一般的な出発点でもあります。この新しい分解モデルでは、各個別のページにほとんどのUIとロジックを保持し、Sharedに再利用可能な基盤を維持します。複数のページでビジネスロジックを再利用する必要が生じた場合は、それを下層のレイヤーに移動できます。
+
+Feature-Sliced Designへのもう一つの追加は、`@x`表記を使用したエンティティ間のクロスインポートの標準化です。
+
+## 移行方法 {#how-to-migrate}
+
+v2.1には破壊的な変更はなく、FSD v2.0で書かれたプロジェクトもFSD v2.1の有効なプロジェクトです。しかし、新しいメンタルモデルがチームや特に新しい開発者のオンボーディングにとってより有益であると考えているため、分解に対して小さな調整を行うことを推奨します。
+
+### スライスのマージ
+
+移行を始めるための簡単な方法は、プロジェクトでFSDのリンターである[Steiger][steiger]を実行することです。Steigerは新しいメンタルモデルで構築されており、最も役立つルールは次のとおりです。
+
+- [`insignificant-slice`][insignificant-slice] — エンティティ、またはフィーチャーが1ページでのみ使用されている場合、このルールはそのエンティティ、またはフィーチャーをページに完全にマージすることを提案します。
+- [`excessive-slicing`][excessive-slicing] — レイヤーにスライスが多すぎる場合、通常は分解が細かすぎるサインです。このルールは、プロジェクトのナビゲーションを助けるためにいくつかのスライスをマージ、またはグループ化することを提案します。
+
+```bash
+npx steiger src
+```
+
+これにより、1回だけ使用されるスライスを特定できるため、それらが本当に必要か再考することができます。そのような考慮において、レイヤーはその内部のすべてのスライスのための何らかのグローバル名前空間を形成することを念頭に置いてください。1回だけ使用される変数でグローバル名前空間を汚染しないようにするのと同様に、レイヤーの名前空間内の場所を貴重なものとして扱い、慎重に使用するべきです。
+
+### クロスインポートの標準化
+
+以前にプロジェクト内でクロスインポートがあった場合、Feature-Sliced Designでのクロスインポートのための新しい表記法`@x`を活用できます。これは次のようになります。
+
+```ts title="entities/B/some/file.ts"
+import type { EntityA } from "entities/A/@x/B";
+```
+
+詳細については、リファレンスの[クロスインポートの公開API][public-api-for-cross-imports]セクションを参照してください。
+
+[insignificant-slice]: https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/insignificant-slice
+[steiger]: https://github.com/feature-sliced/steiger
+[excessive-slicing]: https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/excessive-slicing
+[public-api-for-cross-imports]: /docs/reference/public-api#public-api-for-cross-imports
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/_category_.yaml b/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/_category_.yaml
new file mode 100644
index 0000000000..b4c34b26eb
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/_category_.yaml
@@ -0,0 +1,2 @@
+label: 技術
+position: 3
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx
new file mode 100644
index 0000000000..67de70dec4
--- /dev/null
+++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx
@@ -0,0 +1,109 @@
+---
+sidebar_position: 10
+---
+# NextJSとの併用
+
+NextJSプロジェクトでFSDを実装することは可能ですが、プロジェクトの構造に関するNextJSの要件とFSDの原則の間に2つの点で対立が生じます。
+
+- `pages`のファイルルーティング
+- NextJSにおける`app`の対立、または欠如
+
+## `pages`におけるFSDとNextJSの対立 {#pages-conflict}
+
+NextJSは、アプリケーションのルートを定義するために`pages`フォルダーを使用することを提案しています。`pages`フォルダー内のファイルがURLに対応することを期待しています。このルーティングメカニズムは、FSDの概念に**適合しません**。なぜなら、このようなルーティングメカニズムでは、スライスの平坦な構造を維持することができないからです。
+
+### NextJSの`pages`フォルダーをプロジェクトのルートフォルダーに移動する（推奨）
+
+このアプローチは、NextJSの`pages`フォルダーをプロジェクトのルートフォルダーに移動し、FSDのページをNextJSの`pages`フォルダーにインポートすることにあります。これにより、`src`フォルダー内でFSDのプロジェクト構造を維持できます。
+
+```sh
+├── pages # NextJSのpagesフォルダー
+├── src
+│ ├── app
+│ ├── entities
+│ ├── features
+│ ├── pages # FSDのpagesフォルダー
+│ ├── shared
+│ ├── widgets
+```
+
+### FSD構造における`pages`フォルダーの名前変更
+
+もう一つの解決策は、FSD構造内の`pages`層の名前を変更して、NextJSの`pages`フォルダーとの名前衝突を避けることです。
+FSDの`pages`層を`views`層に変更することができます。
+このようにすることで、`src`フォルダー内のプロジェクト構造は、NextJSの要件と矛盾することなく保持されます。
+
+
+```sh
+├── app
+├── entities
+├── features
+├── pages # NextJSのpagesフォルダー
+├── views # 名前が変更されたFSDのページフォルダー
+├── shared
+├── widgets
+```
+
+この場合、プロジェクトのREADMEや内部ドキュメントなど、目立つ場所にこの名前変更を文書化することをお勧めします。この名前変更は、[「プロジェクト知識」][project-knowledge]の一部です。
+
+## NextJSにおける`app`フォルダーの欠如 {#app-absence}
+
+NextJSのバージョン13未満では、明示的な`app`フォルダーは存在せず、代わりにNextJSは`_app.tsx`ファイルを提供しています。このファイルは、プロジェクトのすべてのページのラッピングコンポーネントとして機能しています。
+
+### `pages/_app.tsx`ファイルへの機能のインポート
+
+NextJSの構造における`app`フォルダーの欠如の問題を解決するために、`app`層内に`App`コンポーネントを作成し、NextJSがそれを使用できるように`pages/_app.tsx`に`App`コンポーネントをインポートすることができます。例えば
+
+
+```tsx
+// app/providers/index.tsx
+
+const App = ({ Component, pageProps }: AppProps) => {
+ return (
+ 📁 src
+-
+
- 📁 app (変更なし) +
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
- 📁 actions +
- 📁 reducers +
- 📁 selectors +
-
+ ++
📁 ui
+-
+
- 📄 Component.jsx +
- 📄 Container.jsx +
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ - 📁 catalog +
+ -
+
-
+ ++
📁 shared (再利用されるオブジェクトのみ)
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
Loading...
;
+ }
+
+ if (isError || !post) {
+ return <>{error?.message};
+ }
+
+ return (
+
+
+ );
+};
+```
+
+### クエリファクトリーを使用する利点
+- **クエリの構造化:** ファクトリーはすべてのAPIクエリを1か所に整理し、コードをより読みやすく、保守しやすくしている
+- **クエリとキーへの便利なアクセス:** ファクトリーはさまざまなタイプのクエリとそのキーへの便利なメソッドを提供している
+- **クエリの再フェッチ機能:** ファクトリーは、アプリケーションのさまざまな部分でクエリキーを変更することなく、簡単に再フェッチを行うことを可能にしている
+
+## ページネーション
+
+このセクションでは、ページネーションを使用して投稿エンティティを取得するためのAPIクエリを行う`getPosts`関数の例を挙げます。
+
+### 1. `getPosts`関数の作成
+
+`getPosts`関数は、APIセグメント内の`get-posts.ts`ファイルにあります。
+
+```tsx title="@/pages/post-feed/api/get-posts.ts"
+import { apiClient } from "@/shared/api/base";
+
+import { PostWithPaginationDto } from "./dto/post-with-pagination.dto";
+import { PostQuery } from "./query/post.query";
+import { mapPost } from "./mapper/map-post";
+import { PostWithPagination } from "../model/post-with-pagination";
+
+const calculatePostPage = (totalCount: number, limit: number) =>
+ Math.floor(totalCount / limit);
+
+export const getPosts = async (
+ page: number,
+ limit: number,
+): PromisePost id: {post.id}
+
+
+ {post.title}
+
+
+ {post.body}
+Owner: {post.userId}
+ + +
+FSDの重要な概念に関するセクション +
+ +
+
+
+
+1. App (アップ)
+2. Processes (プロセス、非推奨)
+3. Pages (ページ)
+4. Widgets (ウィジェット)
+5. Features (フィーチャー)
+6. Entities (エンティティ)
+7. Shared (シェアード)
+
+プロジェクトにすべてのレイヤーを使用する必要はありません。プロジェクトに価値をもたらすと思う場合のみ追加してください。通常、ほとんどのフロントエンドプロジェクトには、少なくともShared、Page、Appのレイヤーがあります。
+
+実際には、レイヤーは小文字の名前のフォルダーです（例えば、`📁 shared`、`📁 pages`、`📁 app`）。新しいレイヤーを追加することは推奨されていません。なぜなら、その意味は標準化されているからです。
+
+## レイヤーに関するインポートルール
+
+レイヤーは _スライス_ で構成されており、これは非常に凝集性の高いモジュールのグループです。スライス間の依存関係は、**レイヤーに関するインポートルール**によって規制されています。
+
+> _スライス内のモジュール（ファイル）は、下位のレイヤーにある他のスライスのみをインポートできます。_
+
+例えば、フォルダー `📁 ~/features/aaa` は「aaa」という名前のスライスです。その中のファイル `~/features/aaa/api/request.ts` は、`📁 ~/features/bbb` 内のファイルからコードをインポートすることはできませんが、`📁 ~/entities` や `📁 ~/shared` からコードをインポートすることができ、例えば `~/features/aaa/lib/cache.ts` などの同じスライス内の隣接コードもインポートできます。
+
+AppとSharedのレイヤーは、このルールの**例外**です。これらは同時にレイヤーとスライスの両方です。スライスはビジネスドメインによってコードを分割しますが、これらの2つのレイヤーは例外です。なぜなら、Sharedはビジネスドメインを持たず、Appはすべてのビジネスドメインを統合しているからです。
+
+実際には、AppとSharedのレイヤーはセグメントで構成されており、セグメントは自由に互いにインポートできます。
+
+## レイヤーの定義
+
+このセクションでは、各レイヤーの意味を説明し、どのようなコードがそこに属するかの直感を得るためのものです。
+
+### Shared
+
+このレイヤーは、アプリの残りの部分の基盤を形成します。外部世界との接続を作成する場所であり、例えばバックエンド、サードパーティライブラリ、環境などです。また、特定のタスクに集中した自分自身のライブラリを作成する場所でもあります。
+
+このレイヤーは、Appレイヤーと同様に、_スライスを含みません_。スライスはビジネスドメインによってレイヤーを分割することを目的としていますが、Sharedにはビジネスドメインが存在しないため、Shared内のすべてのファイルは互いに参照し、インポートすることができます。
+
+このレイヤーで通常見られるセグメントは次のとおりです。
+
+- `📁 api` — APIクライアントおよび特定のバックエンドエンドポイントへのリクエストを行う関数
+- `📁 ui` — アプリケーションのUIキット
+ このレイヤーのコンポーネントはビジネスロジックを含むべきではありませんが、ビジネスに関連することは許可されています。例えば、会社のロゴやページレイアウトをここに置くことができます。UIロジックを持つコンポーネントも許可されています（例えば、オートコンプリートや検索バー）
+- `📁 lib` — 内部ライブラリのコレクション
+ このフォルダーはヘルパーやユーティリティとして扱うべきではありません（[なぜこれらのフォルダーがしばしばダンプに変わるか][ext-sova-utility-dump]）。このフォルダー内の各ライブラリは、日付、色、テキスト操作など、1つの焦点を持つべきです。その焦点はREADMEファイルに文書化されるべきです。チームの開発者は、これらのライブラリに何を追加でき、何を追加できないかを知っているべきです
+- `📁 config` — 環境変数、グローバルフィーチャーフラグ、アプリの他のグローバル設定
+- `📁 routes` — ルート定数、またはルートをマッチさせるためのパターン
+- `📁 i18n` — 翻訳のセットアップコード、グローバル翻訳文字列
+
+さらにセグメントを追加することは自由ですが、これらのセグメントの名前は内容の目的を説明するものでなければなりません。例えば、`components`、`hooks`、`types` は、コードを探しているときにあまり役立たないため、悪いセグメント名です。
+
+### Entities
+
+このレイヤーのスライスは、プロジェクトが扱う現実世界の概念を表します。一般的には、ビジネスがプロダクトを説明するために使用する用語です。例えば、SNSは、ユーザー、投稿、グループなどのビジネスエンティティを扱うかもしれません。
+
+エンティティスライスには、データストレージ（`📁 model`）、データ検証スキーマ（`📁 model`）、エンティティ関連のAPIリクエスト関数（`📁 api`）、およびインターフェース内のこのエンティティの視覚的表現（`📁 ui`）が含まれる場合があります。視覚的表現は、完全なUIブロックを生成する必要はなく、アプリ内の複数のページで同じ外観を再利用することを主に目的としています。異なるビジネスロジックは、プロップスやスロットを通じてそれに付加されることがあります。
+
+#### エンティティの関係
+
+FSDにおけるエンティティはスライスであり、デフォルトではスライスは互いに知ることができません。しかし、現実の世界では、エンティティはしばしば互いに相互作用し、一方のエンティティが他のエンティティを所有、または含むことがあります。そのため、これらの相互作用のビジネスロジックは、フィーチャーやページのような上位のレイヤーに保持されるのが望ましいです。
+
+一つのエンティティのデータオブジェクトが他のデータオブジェクトを含む場合、通常はエンティティ間の接続を明示的にし、`@x`表記を使用してスライスの隔離を回避するのが良いアイデアです。理由は、接続されたエンティティは一緒にリファクタリングする必要があるため、その接続を見逃すことができないようにするのが最善です。
+
+例：
+
+```ts title="entities/artist/model/artist.ts"
+import type { Song } from "entities/song/@x/artist";
+
+export interface Artist {
+ name: string;
+ songs: Array
+
+
+
+ +커뮤니티 리소스, 추가 자료 +
+ +## Main + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { StarOutlined, SearchOutlined, TeamOutlined, VerifiedOutlined } from "@ant-design/icons"; + ++ +*향후 어떤 도구가 추가되더라도, 시니어나 리더 개발자들만 이해할 수 있는 방법론이라면 충분하지 않습니다.* + +### 일상적인 문제 해결 + +방법론은 개발 프로젝트에서 일상적으로 발생하는 문제에 대해 명확한 이유와 해결책을 제시해야 합니다. + +**이를 위해 CLI와 린터(linter) 같은 도구들도 함께 제공해야 합니다.** + +이를 통해 개발자들은 아키텍처와 개발상의 오랜 문제를 우회할 수 있는 검증된 접근 방식을 활용할 수 있습니다. + +> *@sergeysova: 방법론을 기반으로 코드를 작성하는 개발자는 이미 많은 문제에 대한 해결책이 마련되어 있기 때문에, 문제 발생 빈도가 10배 정도 줄어들 것이라고 상상해보세요.* + +## 한계 + +우리는 *특정 관점을 강요하고* 싶지 않으며, 개발자로서의 *여러 습관이 문제 해결을 방해할 수 있다는 점도 이해합니다.* + +모든 개발자의 시스템을 설계하거나 개발하는 데 경험 수준이 다르기 떄문에, **다음 사항을 이해하는 것이 중요합니다:** + +- **모두에게 동일하게 적용되지 않을 수 있음:**: 너무 간단하거나 명확한 접근법이 모든 상황에서 항상 효과적이지는 않습니다. + > *@sergeysova: 어떤 개념들은 문제를 직접 겪고, 오랜 시간을 들여 해결하는 과정을 통해서만 직관적으로 이해할 수 있는 경우가 많습니다. + > + > - *수학: 그래프 이론.* + > - *물리학: 양자 역학.* + > - *프로그래밍: 애플리케이션 아키텍처.* + +- **가능하고 바람직한 방향**: 단순함과 확장 가능성의 조화 + +## 참고 자료 + +- [아키텍쳐 문제들][refs-architecture--problems] + +[refs-architecture--problems]: /docs/about/understanding/architecture#problems diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/about/motivation.md b/i18n/kr/docusaurus-plugin-content-docs/current/about/motivation.md new file mode 100644 index 0000000000..836bfadd20 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/about/motivation.md @@ -0,0 +1,149 @@ +--- +sidebar_position: 2 +--- + +# 동기 + +**Feature-Sliced Design**은 [여러 개발자들의 연구와 경험을 결합하여][ext-discussions] 복잡하고 점점 더 커지는 프로젝트의 개발을 용이하게 하고, 비용을 줄이려는 아이디어에서 출발했습니다. + +물론 이 방법론이 모든 문제를 해결하는 만능은 아니며, [적용 가능한 제한 사항][refs-mission]이 존재합니다. + +그럼에도 불구하고 *이 방법론이 주는 전반적인 효용성*에 대해 많은 개발자들이 관심을 가지고 있습니다. + +:::note + +자세한 논의 내용은 [토론 게시글][disc-src]에서 확인할 수 있습니다. + +::: + +## 기존 솔루션으로는 부족한 이유 + +> 일반적으로 다음과 같은 반문들이 제기됩니다: +> +> - *"이미 `SOLID`, `KISS`, `YAGNI`, `DDD`, `GRASP`, `DRY` 등 오랜 기간 확립된 접근 방식과 설계 원칙들이 있는데, 왜 새로운 방법론이 필요한가?"* +> - *"모든 문제는 적절한 프로젝트 문서화, 테스트, 구조화된 프로세스로 해결될 수 있다."* +> - *"모든 개발자들이 위의 원칙들을 제대로 따른다면 문제가 발생하지 않았을 것이다."* +> - *"이미 필요한 모든 것이 발명되었고, 당신은 단지 그것을 제대로 활용하지 못할 뿐이다."* +> - *"\{프레임워크_이름\}을 사용하라. 거기에는 이미 모든 것이 정해져 있다."* + +### 원칙만으로는 충분하지 않다 + +**좋은 아키텍처를 설계하기 위해 원칙들이 존재하는 것만으로는 충분하지 않습니다.** + +모든 개발자가 이러한 원칙들을 완벽히 알고 있는 것도 아니며, 이해하고 올바르게 적용할 수 있는 사람은 더욱 적습니다. + +*설계 원칙들은 일반적인 지침이기 때문에, "확장 가능하고 유연한 애플리케이션의 구조와 아키텍처를 어떻게 설계해야 하는가?"에 대한 구체적인 답을 제공하지 못합니다.* + +### 프로세스가 항상 작동하지는 않는다 + +*문서화, 테스트, 프로세스* 관리는 분명 중요하지만, 여기에 많은 비용을 들이더라도 **아키텍처 문제나 신규 인력의 프로젝트 적응 문제를 완전히 해결하지는 못합니다.** + +- 문서가 방대해지거나 오래되면 각 개발자가 프로젝트에 빠르게 적응하는 데 큰 도움이 되지 않습니다. +- 모든 구성원이 아키텍처를 동일하게 이해하고 있는지 지속적으로 확인하는 데에도 상당한 리소스가 소모됩니다. +- bus-factor에 대해서도 잊지 말아야 합니다 + +### 기존 프레임워크를 모든 상황에 적용할 수는 없다 + +- 기존 솔루션들은 보통 진입 장벽이 높아 새로운 개발자를 구하기가 어렵습니다. +- 또한 대부분의 경우, 프로젝트 초기에 기술 스택이 이미 결정되기 때문에 **기술에 얽매이지 않고** “주어진 조건에서 작업할 수 있어야” 합니다. + +> Q: "내 프로젝트에서 `React/Vue/Redux/Effector/Mobx/{당신의_기술}`을 사용할 때, 엔티티의 구조와 이들 간의 관계를 어떻게 더 잘 구축할 수 있을까요?" + +### 결과적으로 + +각 프로젝트는 팀원이 오랜 시간 몰입해야 하며, 다른 프로젝트에는 적용하기 어려운 *"눈송이처럼 독특한"* 형태로 남게 됩니다. + +> @sergeysova: *"이것이 바로 현재 프론트엔드 개발 분야에서 일어나고 있는 문제입니다. 각 리드는 각기 다른 아키텍처와 프로젝트 구조를 만들어 내지만, 그 구조가 시간의 시험을 견딜 수 있을지는 보장할 수 없습니다. 결과적으로 두세 명 정도의 개발자만 해당 프로젝트를 유지할 수 있고, 새로운 개발자가 참여할 때마다 다시 긴 적응 기간이 필요해집니다."* + +## 개발자들이 왜 방법론이 필요한가? + +### 개발자의 아키텍처 고민을 줄이고 비즈니스 기능에 집중 + +이 방법론은 아키텍처 설계에 드는 리소스를 줄여 개발자들이 비즈니스 개발에 더 집중할 수 있도록 돕습니다. 동시에 아키텍처 구조는 표준화되어 프로젝트 간에 일관성을 제공합니다. + +*이 방법론이 커뮤니티에서 신뢰를 얻기 위해서는 다른 개발자들이 이 방법론을 쉽게 익히고, 정해진 시간 내에 각자의 프로젝트 문제를 해결하는 데 도움이 되어야 합니다.* + +### 경험으로 입증된 솔루션 제공 + +이 방법론은 복잡한 비즈니스 로직을 설계하는 데 검증된 솔루션이 필요한 개발자들을 위해 만들어졌습니다. + +또한, 이 방법론은 개발 중 발생하는 특정 문제와 사례를 다루는 베스트 프랙티스와 참고 자료들의 모음이기도 하므로, 개발과 설계 과정에서 여러 문제를 겪는 다른 개발자들에게도 유용할 것입니다 + + +### 프로젝트의 장기적인 건강성을 유지 + +이 방법론은 *많은 리소스를 들이지 않고도 프로젝트에서 발생할 수 있는 문제를 사전에 해결하고 추적할 수 있도록* 돕습니다. + +**대부분의 경우 기술 부채는 시간이 지남에 따라 누적되며, 이를 해결하는 책임은 리드와 팀 모두에게 있습니다** + +이 방법론은 프로젝트 확장과 개발 과정에서 생길 수 있는 문제들을 미리 *경고할 수* 있게 해줍니다. + +## 비즈니스에게 왜 방법론이 필요한가? + +### 빠른 온보딩 + +이 방법론을 통해 **이미 이 접근 방식에 익숙한 사람을 프로젝트에 고용할 수 있어 추가 교육이 필요하지 않습니다.** + +*덕분에 팀원들이 프로젝트를 더 빨리 이해하고 기여할 수 있으며, 다음 단계에 필요한 인력을 확보하는 데도 유리한 조건을 갖추게 됩니다.* + +### 검증된 솔루션 제공 + +이 방법론을 통해 비즈니스는 *시스템 개발 중 발생하는 대부분의 문제들에 대한 해결책*을 얻을 수 있습니다. + +대부분의 경우, 비즈니스는 프로젝트 개발 중 발생하는 다양한 문제를 해결할 수 있는 프레임워크나 솔루션을 필요로 하기 때문입니다. + +### 프로젝트의 다양한 단계에 적용 가능 + +이 방법론은 *프로젝트 지원 및 개발 단계뿐만 아니라 MVP 단계에서도* 프로젝트에 도움이 될 수 있습니다. + +네, MVP에서 가장 중요한 것은 *"미래를 위해 설계된 아키텍처가 아닌 기능"*입니다. 하지만 제한된 기한 내에서도 방법론의 베스트 프랙티스를 알고 있다면, 시스템의 MVP 버전을 설계할 때 합리적인 타협점을 찾아 *"적은 희생으로"* 해결할 수 있습니다 +(기능을 "무작위로" 모델링하는 대신). + +*테스팅에 대해서도 같은 말을 할 수 있습니다* + +## 방법론이 필요하지 않은 경우 + +- 프로젝트 수명이 짧은 경우 +- 프로젝트가 지속적인 아키텍처 관리가 필요하지 않은 경우 +- 비즈니스가 코드베이스와 기능 전달 속도 간의 연관성을 충분히 인식하지 못하는 경우 +- 비즈니스가 사후 지원보다 신속한 주문 처리를 우선해야 하는 경우 + +### 비즈니스 규모 + +- **소규모 비즈니스** - 대부분 즉시 사용 가능하며 빠른 솔루션이 필요합니다. 비즈니스가 성장하여 최소한 중간 규모에 가까워질 때, 고객 유지와 더불어 솔루션의 품질과 안정성에 투자할 필요성을 이해하게 됩니다. +- **중간 규모 비즈니스** - 일반적으로 개발 과정에서 발생하는 문제들을 이해하고 있으며, *"기능 경쟁"*이 필요한 상황에서도 품질 개선, 리팩토링, 테스트에 시간을 투자합니다. 물론 확장 가능한 아키텍처 역시 중요하게 고려합니다. +- **대규모 비즈니스** - 대규모 비즈니스는 보통 이미 광범위한 사용자층, 많은 직원, 그리고 자체적인 관행과 아키텍처 접근 방식을 가지고 있습니다. 따라서 외부에서 가져온 새로운 접근 방식을 적용하려는 경우는 드뭅니다. + +## 계획 + +주요 목표는 [여기에 명시되어 있지만][refs-mission--goals], 앞으로의 방법론에 대해 우리가 기대하는 바를 추가로 설명할 필요가 있습니다. + +### 경험 결합 + +현재 우리는 `core-team`의 다양한 경험을 하나로 모아 견고하게 단련된 방법론을 만드는 데 힘쓰고 있습니다. + +물론 그 결과가 Angular 3.0과 같은 결과물일 수도 있겠지만, 여기서 더 중요한 것은 *복잡한 시스템 아키텍처 설계라는 문제를 심도 있게 탐구*하는 것입니다. + +*현재 버전의 방법론에 대해 불만족스러운 점이 있지만, 커뮤니티의 경험도 함께 고려하여 모두가 합의할 수 있는 단일하고 최적의 솔루션에 도달하는 것이 목표입니다.* + +### 사양을 넘어선 생명력 + +모든 것이 계획대로 진행된다면, 이 방법론은 단순히 사양과 툴킷에만 국한되지 않을 것입니다. + +- 보고서나 기사들이 생길 수도 있습니다. +- 방법론에 따라 작성된 프로젝트를 다른 기술로 마이그레이션하기 위한 CODE_MODE가 있을 수 있습니다. +- 이로 인해 대규모 기술 솔루션의 유지보수자들이 이 방법론을 활용할 기회를 가질 수 있습니다. + - *특히 React의 경우, 다른 프레임워크에 비해 특정 문제를 해결하는 구체적인 방안을 제시하지 않는다는 점이 주요 문제로 남아 있습니다.* + +## See also + +- [(토론) 방법론이 필요하지 않나요?][disc-src] +- [방법론의 목표와 한계에 대한 설명][refs-mission] +- [프로젝트에서 다루는 지식의 유형][refs-knowledge] + +[refs-mission]: /docs/about/mission +[refs-mission--goals]: /docs/about/mission#goals +[refs-knowledge]: /docs/about/understanding/knowledge-types + +[disc-src]: https://github.com/feature-sliced/documentation/discussions/27 +[ext-discussions]: https://github.com/feature-sliced/documentation/discussions \ No newline at end of file diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/architecture.md b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/architecture.md new file mode 100644 index 0000000000..f5502053f0 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/architecture.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 1 +--- + +# 아키텍처에 대하여 + +## 문제점들 + +일반적으로 아키텍처에 대한 논의는 프로젝트에서 특정 문제로 인해 개발이 중단될 때 제기됩니다. + +### Bus-factor & 온보딩 + +제한된 인원만이 프로젝트와 그 아키텍처를 이해합니다. + +**예시:** + +- *"개발에 새로운 인력을 추가하기가 어렵습니다"* +- *"문제 해결 방식에 대한 명확한 가이드라인이 없어 개발자마다 각기 다른 접근 방식을 사용합니다"* +- *"이 거대한 모놀리스에서 무슨 일이 일어나고 있는지 이해할 수 없습니다"* + +### 의도치 않은 부작용과 통제되지 않는 영향 + +개발/리팩토링 중 많은 의도치 않은 부작용들이 있습니다 *("모든 것이 모든 것에 의존합니다")* + +**예시:** + +- *"기능 간의 부적절한 의존성이 발생하고 있습니다"* +- *"한 페이지의 상태(store) 변경이 다른 페이지의 기능에 예기치 않은 영향을 미칩니다"* +- *"비즈니스 로직이 애플리케이션 전반에 분산되어 있어 로직의 흐름을 추적하기 어렵습니다"* + +### 통제되지 않는 로직의 재사용 + +기존 로직을 재사용하거나 수정하기 어렵습니다. + +동시에, 보통 [두 가지 극단적인 경우](https://github.com/feature-sliced/documentation/discussions/14)가 나타납니다: + +- 각 모듈에 대해 로직을 완전히 처음부터 작성하거나 *(기존 코드베이스에서 재사용 가능한 부분까지 포함하여)* +- 또는 모든 구현된 모듈을 `shared` 폴더로 이동하려는 경향이 있어, *대부분 단일 사용 목적의 모듈들이 무분별하게 축적되는 현상이 발생합니다.* + +**예시:** + +- *"프로젝트 내에 동일한 비즈니스 로직이 **N**번 중복 구현되어 있어 유지보수 비용이 지속적으로 발생합니다"* +- *"동일한 기능의 버튼/팝업 등 UI 컴포넌트가 여러 버전으로 존재합니다"* +- *"유틸리티 함수들이 체계 없이 누적되어 있습니다"* + +## 요구사항 + +이상적인 아키텍처를 위한 *핵심 요구사항*을 다음과 같이 정의할 수 있습니다. + +:::note +여기서 "쉽다"라는 표현은 "대다수의 개발자들이 합리적인 시간 내에 이해하고 적용할 수 있다"는 의미입니다. [모든 개발자와 상황에 완벽하게 부합하는 솔루션은 현실적으로 불가능하기 때문입니다.](/docs/about/mission#limitations) +::: + +### 명시성 + +- 팀원들이 프로젝트 구조와 아키텍처를 **직관적으로 이해하고 설명할 수 있어야** 합니다. +- 아키텍처는 프로젝트의 **비즈니스 도메인과 가치를 명확히 반영**해야 합니다. +- 추상화 계층 간의 **의존성과 부작용**이 명확히 파악되어야 합니다. +- **중복 로직을 효과적으로 식별**할 수 있어야 합니다. +- 프로젝트 전반에 걸쳐 **로직이 분산**되지 않도록 해야 합니다. +- **불필요한 추상화와 복잡한 규칙**을 최소화해야 합니다. + +### 제어 + +- 효과적인 아키텍처는 **새로운 기능 개발과 문제 해결의 생산성을 향상**시켜야 합니다. +- 프로젝트의 전반적인 개발 흐름을 효율적으로 관리할 수 있어야 합니다. +- **코드의 확장성, 유지보수성, 제거 용이성**을 보장해야 합니다. +- 기능 단위의 **명확한 경계와 격리**가 보장되어야 합니다. +- 각 컴포넌트는 **높은 교체성과 제거 용이성**을 가져야 합니다. + - *[변경을 위한 과도한 최적화는 지양합니다][ext-kof-not-modification] - 미래의 변경사항을 정확히 예측하기 어렵기 때문입니다.* + - *[제거 용이성을 위한 설계가 더 중요합니다][ext-kof-but-removing] - 현재의 컨텍스트를 기반으로 한 의사결정이 더 실용적이기 때문입니다.* + +### 적응성 + +- 효과적인 아키텍처는 **다양한 규모와 유형의 프로젝트**에 적용 가능해야 합니다. + - *기존 시스템 및 인프라와의 원활한 통합이 가능해야 합니다.* + - *프로젝트의 모든 개발 단계에서 일관되게 적용될 수 있어야 합니다.* +- 특정 기술 스택이나 플랫폼에 종속되지 않아야 합니다. +- **병렬 개발과 팀 확장**이 용이해야 합니다. +- **비즈니스 요구사항과 기술 환경의 변화**에 유연하게 대응할 수 있어야 합니다. + +## See also + +- [(React Berlin Talk) Oleg Isonen - Feature Driven Architecture][ext-kof] +- [(React SPB Meetup #1) Sergey Sova - Feature Slices][ext-slices-spb] +- [(Article) 프로젝트 모듈화에 대하여][ext-medium] +- [(Article) 관점 분리와 기능 기반 구조화에 대하여][ext-ryanlanciaux] + +[ext-kof-not-modification]: https://youtu.be/BWAeYuWFHhs?t=1631 +[ext-kof-but-removing]: https://youtu.be/BWAeYuWFHhs?t=1666 + +[ext-slices-spb]: https://t.me/feature_slices +[ext-kof]: https://youtu.be/BWAeYuWFHhs +[ext-medium]: https://alexmngn.medium.com/why-react-developers-should-modularize-their-applications-d26d381854c1 +[ext-ryanlanciaux]: https://ryanlanciaux.com/blog/2017/08/20/a-feature-based-approach-to-react-development/ diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/knowledge-types.md b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/knowledge-types.md new file mode 100644 index 0000000000..19924dbbb8 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/knowledge-types.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 3 +sidebar_label: 프로젝트의 지식 유형 +--- + +# 프로젝트의 지식 유형 + +소프트웨어 프로젝트를 개발할 때 다루게 되는 지식은 크게 세 가지로 나눌 수 있습니다: + +### 기반 지식 (Fundamental Knowledge) +프로그래밍의 기본이 되는 지식으로, 시간이 지나도 크게 변하지 않습니다: +- 알고리즘과 자료구조 +- 컴퓨터 과학의 핵심 개념 +- 프로그래밍 언어의 기본 원리 + +### 기술 스택 (Technical Stack) +프로젝트 개발에 직접적으로 사용되는 도구들에 대한 지식입니다: +- 프로그래밍 언어와 프레임워크 +- 라이브러리와 개발 도구 +- 개발 환경과 배포 도구 + +### 프로젝트 도메인 지식 (Project Domain Knowledge) +특정 프로젝트에만 해당하는 고유한 지식입니다: +- 비즈니스 로직과 규칙 +- 프로젝트만의 아키텍처 결정사항 +- 팀 내 개발 규칙과 관례 + +:::note +**Feature-Sliced Design**은 이러한 지식 유형을 고려하여 설계되었습니다: +- 프로젝트 도메인 지식에 대한 의존도를 최소화 +- 기술 스택 지식을 체계적으로 구조화 +- 새로운 팀원의 적응 과정을 단순화 +::: + +## 참고 자료 {#see-also} + +- [(영상 🇷🇺) Ilya Klimov - 지식 유형에 관하여][ext-klimov] + +[ext-klimov]: https://youtu.be/4xyb_tA-uw0?t=249 + + diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/naming.md b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/naming.md new file mode 100644 index 0000000000..dd52de7e40 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/naming.md @@ -0,0 +1,65 @@ +--- +sidebar_position: 4 +--- + +# 네이밍 (Naming) + +개발자들은 같은 대상을 각자의 경험과 관점에 따라 다르게 부르곤 합니다. 예를 들어: + +- UI 컴포넌트를 "ui", "components", "ui-kit", "views" 등으로 표현 +- 공통 코드를 "core", "shared", "app" 등으로 지칭 +- 비즈니스 로직을 "store", "model", "state" 등으로 명명 + +## Feature-Sliced Design의 표준 네이밍 {#naming-in-fsd} + +FSD는 다음과 같이 명확한 네이밍 규칙을 제시합니다: + +### Layers (계층) +- `app` +- `processes` +- `pages` +- `features` +- `entities` +- `shared` + +### Segments (세그먼트) +- `ui` +- `model` +- `lib` +- `api` +- `config` + +이러한 표준 용어를 사용하면: +- 팀 내 의사소통이 명확해집니다 +- 새로운 팀원의 적응이 쉬워집니다 +- 커뮤니티와의 지식 공유가 용이해집니다 + +## 네이밍 충돌 해결 {#when-can-naming-interfere} + +FSD 용어가 프로젝트의 비즈니스 용어와 중복될 수 있습니다. 예시: + +- `FSD#process` vs 애플리케이션의 시뮬레이션 프로세스, +- `FSD#page` vs 로그 페이지, +- `FSD#model` vs 자동차 모델. + +### 용어 사용 가이드 + +1. 기술적 커뮤니케이션 + - FSD 용어 사용 시 "FSD" 접두어 사용을 권장합니다 + - 예: "이 기능을 FSD features 계층으로 이동하는 것이 좋겠습니다" + +2. 비기술적 커뮤니케이션 + - FSD 관련 용어 사용을 피하고 일반적인 비즈니스 용어 사용 + - 예: 코드 구조 대신 기능이나 목적 중심으로 설명 + +## 참고 {#see-also} + +- [(토론) Naming의 적응성][disc-src] +- [(토론) Entities Naming 설문조사][disc-naming] +- [(토론) "processes" vs "flows" vs ...][disc-processes] +- [(토론) "model" vs "store" vs ...][disc-model] + +[disc-model]: https://github.com/feature-sliced/documentation/discussions/68 +[disc-naming]: https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-464894 +[disc-processes]: https://github.com/feature-sliced/documentation/discussions/20 +[disc-src]: https://github.com/feature-sliced/documentation/discussions/16 diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/needs-driven.md b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/needs-driven.md new file mode 100644 index 0000000000..8fb7de96ed --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/about/understanding/needs-driven.md @@ -0,0 +1,160 @@ +--- +sidebar_position: 2 +--- + +# 필요 중심 + +:::note TL;DR + +— _새로운 Feature의 목표가 불분명하거나 작업 자체가 명확히 정의되지 않았나요? **이 방법론의 핵심은 작업과 목표를 명확히 정의하는 데 있습니다.**_ + +— _프로젝트는 정적인 것이 아닙니다. 요구 사항과 Feature는 계속해서 변화하며, 시간이 지남에 따라 코드는 점점 복잡해지고 관리가 어려워집니다. **우수한 아키텍처는 이러한 변화에 유연하게 적응할 수 있어야 합니다.**_ + +::: + + +## 왜 이런 접근이 필요할까요? + +각 Entity의 이름과 구성을 명확히 하려면, **해당 코드의 목적을 정확히 이해**해야 합니다. + +> _@sergeysova: 개발할 때 각 Entity와 함수의 의도를 이름에 명확히 반영하려고 노력합니다._ + +_명확하지 않은 작업은 테스트 작성을 어렵게 만들고, 오류 처리가 비효율적이 되어 사용자 경험을 저하시킬 수 있습니다._ + +## 우리가 말하는 작업이란? + +프론트엔드는 사용자의 문제를 해결하고 요구사항을 충족하는 인터페이스를 제공합니다. + +사용자는 서비스 사용 시 **자신의 문제를 해결하거나 필요를 충족**하려 합니다. + +_관리자와 분석가는 이러한 요구사항을 명확히 정의하고, 개발자가 웹의 특성(네트워크 지연, 오류, 사용자 실수 등)을 고려하여 구현할 수 있도록 지원합니다._ + +**사용자의 목표가 곧 개발자의 작업**입니다. + +> _Feature-Sliced Design의 핵심 철학 중 하나는 — 프로젝트의 전체 작업을 더 작은 목표 단위로 나누는 것입니다._ + +## 이것이 개발에 어떤 영향을 미치는가? + +### 작업 분해 + +개발자는 코드의 유지보수성을 위해 작업을 **단계적으로 분해**합니다: + +* _최상위 Entity로 분할_ +* _더 작은 단위로 세분화_ +* _각 Entity에 명확한 이름 부여_ + +_개발자는 코드가 해결하는 작업의 본질을 반영하도록 각 Entity와 구성 요소에 명확한 이름을 부여합니다._ +_이 과정에서 모든 작업이 사용자의 문제 해결에 기여해야 함을 항상 고려합니다._ + + +### 작업의 본질 이해 + +Entity에 명확한 이름을 부여하려면 **개발자가 해당 Entity의 목적과 역할을 충분히 이해**해야 합니다: + +* Entity의 구체적인 사용 목적 +* 구현하는 사용자 작업의 범위 +* 다른 작업과의 연관성 + +결론적으로, **개발자가 Entity의 이름을 고민하는 과정에서 불명확한 작업을 미리 발견할 수 있습니다.** + +> Entity의 이름을 정의하려면 해당 Entity가 해결할 작업을 정확히 이해해야 합니다. + +## 어떻게 정의할 것인가? + +**Feature가 해결할 작업을 정의하려면 그 본질을 이해해야 합니다. 이는 주로 프로젝트 관리자와 분석가의 역할입니다.** + +_방법론은 개발자에게 작업의 방향성을 제시할 뿐입니다._ + +> _@sergeysova: 프론트엔드는 정보 표시에 초점을 맞추지만, 단순히 "무엇을 보여준다"는 것은 충분한 가치를 가지지 못합니다. "왜 이것을 보여줘야 하는가?"라는 질문을 통해 사용자의 실제 필요를 이해해야 합니다._ +> +> _이는 프론트엔드의 기술적 측면을 넘어서, 사용자의 문제와 필요를 정확히 이해할 때까지 지속적으로 탐구해야 하는 과정입니다._ + +사용자의 필요를 이해한 후에는 **제품이 어떻게 사용자의 목표 달성을 도울 수 있는지 구체화**할 수 있습니다. + +모든 새로운 작업은 비즈니스와 사용자의 문제를 동시에 해결하는 것을 목표로 합니다. 각 작업은 명시적이지 않더라도 분명한 목적을 가집니다. + +_**개발자는 작업의 목표를 명확히 이해**해야 합니다. 완벽한 프로세스가 없더라도, 관리자와의 소통을 통해 이를 파악하고 효과적으로 구현할 수 있어야 합니다._ + +## 이점 + +전체 Process를 통해 얻을 수 있는 이점을 살펴보겠습니다. + +### 1. 사용자 작업 이해 + +개발자가 사용자의 문제와 비즈니스 해결방안을 이해하면, 기술적 제약 내에서도 더 나은 솔루션을 제안할 수 있습니다. + +> _이는 개발자가 자신의 역할과 목표에 관심을 가질 때만 가능합니다. 그렇지 않다면, 방법론 자체가 의미를 잃습니다._ + +### 2. 구조화 및 정리 + +작업을 이해하면 **사고 과정, 작업, 코드가 자연스럽게 체계화**됩니다. + +### 3. 기능과 그 구성 요소 이해 + +**하나의 Feature는 사용자에게 명확한 가치를 제공해야 합니다.** + +* 여러 기능이 섞이면 **경계 위반**입니다 +* Feature는 분리와 확장이 가능합니다. **이는 자연스러운 것입니다** +* **핵심은** _"이 Feature가 사용자에게 제공하는 가치가 무엇인가?"_ 입니다 +* 예시: + * ❌ "지도-사무실" (모호한 Feature) + * ⭕ `회의실-예약`, `직원-검색`, `근무지-변경` (**명확한 Feature**) + +> _@sergeysova: Feature는 핵심 구현 코드만 포함해야 합니다. +> +> **관련 없는 코드는 제외하고, 해당 Feature의 핵심 로직만 담아야 합니다.**_ + +### 4. 유지보수성 + +비즈니스 방향은 쉽게 바뀌지 않습니다. **따라서 비즈니스 로직을 코드에 명확히 반영하면 장기적인 이점이 있습니다.** + +_그 결과, 새로운 팀원이 합류할 때마다 코드가 무엇을 하고, 왜 추가되었는지 따로 설명할 필요가 없습니다. **코드 자체에 반영된 비즈니스 작업을 통해 모든 것이 설명될 것입니다.**_ + +> [도메인 주도 설계에서 "비즈니스 언어"라고 불리는 개념입니다.][ext-ubiq-lang] + +--- + +## 현실적 고려사항 + +비즈니스 Process가 명확하고 설계가 잘 되었다면, _이를 코드로 구현하는 것은 비교적 쉽습니다._ + +**하지만 현실에서는,** 작업과 Feature가 충분한 설계 시간 없이 반복적으로 처리되는 경우가 많습니다. + +**결과적으로, 현재는 적절해 보이는 Feature가 한 달 후 확장 과정에서 전체 프로젝트 구조를 변경해야 할 수도 있습니다.** + +> *[토론에서][disc-src]: 개발자는 보통 2~3단계 앞의 요구사항을 예측하려 노력하며, 이는 경험에 크게 좌우됩니다.* +> +> _숙련된 개발자는 약 10단계 앞까지 예측할 수 있어서, Feature의 분할 지점과 통합 방식을 더 잘 이해합니다._ +> +> _그러나 때로는 경험으로도 해결하기 어려운 복잡한 상황이 발생하며, 이때는 피해를 최소화하면서 문제를 적절히 분해하기가 매우 어렵습니다._ + +## 방법론의 역할 + +**방법론은 개발자가 사용자의 문제를 더 효과적으로 해결할 수 있도록 돕는 것이 목적입니다.** + +방법론은 단순히 개발자를 위한 것이 아닙니다. + +개발자가 좋은 결과를 내려면, **사용자의 문제와 요구사항을 정확히 이해해야 합니다.** 사용자의 문제를 모르면 좋은 해결책을 만들 수 없습니다. + +### 방법론 요구 사항 + +**Feature-Sliced Design**이 충족해야 할 두 가지 요구사항: + +1. **Feature, Process, Entity를 구성하는 명확한 방법 제시** + * _코드 분할 기준과 명명 규칙을 구체적으로 정의_ + +2. **[변화하는 요구사항에 유연한 아키텍처 제공][refs-arch--adaptability]** + +## 참고 자료 + +* [(포스트) 명확한 작업 정의 가이드 (+ 토론)][disc-src] + > _**이 문서는 해당 토론을 바탕**으로 작성되었습니다. 원문은 링크를 참고하세요._ +* [(토론) Feature 분해 방법론][tg-src] +* [(아티클) "효과적인 애플리케이션 구조화"][ext-medium] + +[refs-arch--adaptability]: architecture#adaptability + +[ext-medium]: https://alexmngn.medium.com/how-to-better-organize-your-react-applications-2fd3ea1920f1 +[disc-src]: https://t.me/sergeysova/318 +[tg-src]: https://t.me/atomicdesign/18972 +[ext-ubiq-lang]: https://thedomaindrivendesign.io/developing-the-ubiquitous-language diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/kr/docusaurus-plugin-content-docs/current/get-started/faq.md new file mode 100644 index 0000000000..4b1d8468f4 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/get-started/faq.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 20 +pagination_next: guides/index +--- + +# FAQ + +:::info + +여러분은 [Telegram chat][telegram], [Discord community][discord] 그리고 [GitHub Discussions][github-discussions]에서 질문을 할 수 있습니다. + +::: + +### toolkit이나 linter가 있나요? + +네! 우리는 CLI 또는 IDE를 통해 프로젝트의 아키텍처와 [폴더 생성기][ext-tools]를 확인하기 위한 [Steiger][ext-steiger]라는 linter를 가지고 있습니다. + +### Where to store the layout/template of pages? + +순수한 마크업 레이아웃이 필요하다면 `shared/ui`에 보관할 수 있습니다. 상위 계층을 사용해야 한다면 몇 가지 옵션이 있습니다. + +- 레이아웃이 필요 없을 수도 있습니다. 레이아웃이 몇 줄밖에 안 된다면, 추상화하려고 하기보다는 각 페이지에서 코드를 중복하는 것이 합리적일 수 있습니다. +- 레이아웃이 필요하다면, 별도의 위젯이나 페이지로 만들고 App의 라우터 설정에서 조합할 수 있습니다. 중첩 라우팅도 다른 옵션입니다. + +### feature와 entity의 차이점이 무엇인가요? + +*entity*는 앱이 다루는 실제 개념입니다. *feature*는 앱 사용자에게 실제 가치를 제공하는 상호작용, 즉 사람들이 entity로 하고 싶어하는 것입니다. + +더 자세한 정보와 예시는 [slices][reference-entities] 참조 페이지를 확인하세요. + +### pages/features/entities를 서로 포함시킬 수 있나요? + +네, 하지만 이런 포함은 상위 계층에서 이루어져야 합니다. 예를 들어, 위젯 내부에서 여러 기능을 가져와서 하나의 기능을 다른 기능의 props/children으로 삽입할 수 있습니다. + +한 기능을 다른 기능에서 가져올 수는 없습니다. 이는 [**계층에 대한 가져오기 규칙**][import-rule-layers]에 의해 금지됩니다. + +### 아토믹 디자인은 어떤가요? + +현재 버전의 방법론은 Feature-Sliced Design과 함께 아토믹 디자인을 사용하는 것을 요구하지도, 금지하지도 않습니다. + +예를 들어, 아토믹 디자인은 모듈의 `ui` 세그먼트에 [잘 적용될 수 있습니다](https://t.me/feature_sliced/1653). + +### FSD에 대한 유용한 리소스/기사 등이 있나요? + +네! https://github.com/feature-sliced/awesome 를 참조하세요. + +### Feature-Sliced Design이 왜 필요한가요? + +프로젝트를 주요 가치 창출 구성 요소 측면에서 빠르게 개요를 파악하는 데 도움이 됩니다. 표준화된 아키텍처는 온보딩 속도를 높이고 코드 구조에 대한 논쟁을 해결합니다. FSD가 만들어진 이유에 대해 더 자세히 알아보려면 [동기][motivation] 페이지를 참조하세요. + +### 초보 개발자에게 아키텍처/방법론이 필요한가요? + +그렇다고 볼 수 있습니다. + +*보통 한 사람이 프로젝트를 설계하고 개발할 때는 모든 것이 순조롭게 진행됩니다. 하지만 개발에 중단이 있거나 새로운 개발자가 팀에 합류하면 문제가 발생합니다* + + +### 인증 컨텍스트는 어떻게 다루나요? + +[여기](/docs/guides/examples/auth)에서 답변했습니다. + +[ext-steiger]: https://github.com/feature-sliced/steiger +[ext-tools]: https://github.com/feature-sliced/awesome?tab=readme-ov-file#tools +[import-rule-layers]: /docs/reference/layers#import-rule-on-layers +[reference-entities]: /docs/reference/layers#entities +[motivation]: /docs/about/motivation +[telegram]: https://t.me/feature_sliced +[discord]: https://discord.gg/S8MzWTUsmp +[github-discussions]: https://github.com/feature-sliced/documentation/discussions diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/kr/docusaurus-plugin-content-docs/current/get-started/index.mdx new file mode 100644 index 0000000000..39f2ac22a7 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -0,0 +1,38 @@ +--- +hide_table_of_contents: true +pagination_prev: intro +--- + +import { PlaySquareOutlined, QuestionCircleOutlined, RocketOutlined } from "@ant-design/icons"; +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx"; + +# 🚀 Get Started + +
+환영합니다! 이 섹션은 Feature-Sliced Design의 적용과 방법론의 기본을 익히는 데 도움을 줍니다. 또한 이 방법론의 주요 장점과 그것이 만들어진 이유를 이해하게 될 것입니다. +
+ +위 그림: 세 개의 수직 구조가 있으며, 왼쪽부터 오른쪽으로 각각 "레이어", "슬라이스", "세그먼트"로 표시되어 있습니다.
+"레이어"에는 위에서 아래로 7개의 구분이 있으며, "app", "processes", "pages", "widgets", "features", "entities", "shared"로 표시되어 있습니다. "processes" 구분은 취소선이 그어져 있습니다. "entities" 구분은 두 번째 기둥인 "슬라이스"와 연결되어 있어, 두 번째 기둥이 "entities"의 내용이라는 것을 나타냅니다.
+"슬라이스"에는 위에서 아래로 3개의 구분이 있으며, "user", "post", "comment"로 표시되어 있습니다. "post" 구분은 세 번째 기둥인 "세그먼트"와 연결되어 있어, 세 번째 기둥이 "post"의 내용임을 나타냅니다.
+"세그먼트"에는 위에서 아래로 3개의 구분이 있으며, "ui", "model", "api"로 표시되어 있습니다.
+
+
+ );
+}
+```
+
+그런 다음 피드 페이지의 공개 API인 `pages/feed/index.ts` 파일에서 이 컴포넌트를 다시 내보내세요.
+
+```ts title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+```
+
+이제 루트 경로에 연결합니다. Remix에서 라우팅은 파일 기반이며, 라우트 파일은 `app/routes` 폴더에 있어 Feature-Sliced Design과 잘 맞습니다.
+
+`app/routes/_index.tsx`에서 `FeedPage` 컴포넌트를 사용하세요.
+
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
+
+export default FeedPage;
+```
+
+그런 다음 개발 서버를 실행하고 애플리케이션을 열면 Conduit 배너가 보일 것입니다!
+
+
+
+### API 클라이언트
+
+RealWorld 백엔드와 통신하기 위해 Shared에 편리한 API 클라이언트를 만들어 봅시다. 클라이언트를 위한 `api`와 백엔드 기본 URL과 같은 변수를 위한 `config`, 두 개의 세그먼트를 만드세요.
+
+
+```bash
+npx fsd shared --segments api config
+```
+
+그런 다음 `shared/config/backend.ts`를 만드세요.
+
+```tsx title="shared/config/backend.ts"
+export const backendBaseUrl = "https://api.realworld.io/api";
+```
+
+```tsx title="shared/config/index.ts"
+export { backendBaseUrl } from "./backend";
+```
+
+RealWorld 프로젝트는 편리하게 [OpenAPI 사양](https://github.com/gothinkster/realworld/blob/main/api/openapi.yml)을 제공하므로, 클라이언트를 위한 자동 생성 타입을 활용할 수 있습니다. 추가 타입 생성기가 포함된 [`openapi-fetch` 패키지](https://openapi-ts.pages.dev/openapi-fetch/)를 사용할 것입니다.
+
+다음 명령을 실행하여 최신 API 타입을 생성하세요.
+
+```bash
+npm run generate-api-types
+```
+
+이렇게 하면 `shared/api/v1.d.ts` 파일이 생성됩니다. 이 파일을 사용하여 `shared/api/client.ts`에 타입이 지정된 API 클라이언트를 만들 것입니다.
+
+```tsx title="shared/api/client.ts"
+import createClient from "openapi-fetch";
+
+import { backendBaseUrl } from "shared/config";
+import type { paths } from "./v1";
+
+export const { GET, POST, PUT, DELETE } = createClient
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+ );
+}
+```
+
+좋아요 버튼은 지금은 아무 작업도 하지 않습니다. 글 읽기 페이지를 만들고 좋아요 기능을 구현할 때 수정하겠습니다.
+
+이제 글을 가져와서 이러한 카드를 여러 개 렌더링할 수 있습니다. Remix에서 데이터 가져오기는 *로더* — 페이지가 필요로 하는 것을 정확히 가져오는 서버 측 함수 — 를 통해 수행됩니다. 로더는 페이지를 대신하여 API와 상호 작용하므로 페이지의 `api` 세그먼트에 넣을 것입니다:
+
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+
+import { GET } from "shared/api";
+
+export const loader = async () => {
+ const { data: articles, error, response } = await GET("/articles");
+
+ if (error !== undefined) {
+ throw json(error, { status: response.status });
+ }
+
+ return json({ articles });
+};
+```
+
+페이지에 연결하려면 라우트 파일에서 `loader`라는 이름으로 내보내야 합니다.
+
+```tsx title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+export { loader } from "./api/loader";
+```
+
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
+
+export { loader } from "pages/feed";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
+
+export default FeedPage;
+```
+
+마지막 단계는 피드에 이러한 카드를 렌더링하는 것입니다. `FeedPage`를 다음 코드로 업데이트하세요.
+
+```tsx title="pages/feed/ui/FeedPage.tsx"
+import { useLoaderData } from "@remix-run/react";
+
+import type { loader } from "../api/loader";
+import { ArticlePreview } from "./ArticlePreview";
+
+export function FeedPage() {
+ const { articles } = useLoaderData
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ Read more... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
+```
+
+### 태그로 필터링
+
+태그와 관련해서는 백엔드에서 태그를 가져오고 현재 선택된 태그를 저장해야 합니다. 가져오기 방법은 이미 알고 있습니다 — 로더에서 또 다른 요청을 하면 됩니다. `remix-utils` 패키지에서 `promiseHash`라는 편리한 함수를 사용할 것입니다. 이 패키지는 이미 설치되어 있습니다.
+
+로더 파일인 `pages/feed/api/loader.ts`를 다음 코드로 업데이트하세요.
+
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+ );
+}
+```
+
+그런 다음 로더에서 `tag` 검색 매개변수를 사용해야 합니다. `pages/feed/api/loader.ts`의 `loader` 함수를 다음과 같이 변경하세요.
+
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
+```
+
+이것으로 완료되었습니다. 탭 목록도 비슷하게 구현할 수 있지만, 인증을 구현할 때까지 잠시 보류하겠습니다. 그런데 말이 나왔으니!
+
+### 인증
+
+인증에는 두 개의 페이지가 관련됩니다 - 로그인과 회원가입입니다. 이들은 대부분 동일하므로 필요한 경우 코드를 재사용할 수 있도록 `sign-in`이라는 동일한 슬라이스에 유지하는 것이 합리적입니다.
+
+`pages/sign-in`의 `ui` 세그먼트에 다음 내용으로 `RegisterPage.tsx`를 만드세요.
+
+```tsx title="pages/sign-in/ui/RegisterPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
+
+import type { register } from "../api/register";
+
+export function RegisterPage() {
+ const registerData = useActionData
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
+```
+
+이제 고쳐야 할 깨진 import가 있습니다. 새로운 세그먼트가 필요하므로 다음과 같이 만드세요.
+
+```bash
+npx fsd pages sign-in -s api
+```
+
+그러나 등록의 백엔드 부분을 구현하기 전에 Remix가 세션을 처리할 수 있도록 일부 인프라 코드가 필요합니다. 다른 페이지에서도 필요할 수 있으므로 이는 Shared로 갑니다.
+
+다음 코드를 `shared/api/auth.server.ts`에 넣으세요. 이는 Remix에 매우 특화된 것이므로 너무 걱정하지 마세요. 그냥 복사-붙여넣기 하세요.
+
+```tsx title="shared/api/auth.server.ts"
+import { createCookieSessionStorage, redirect } from "@remix-run/node";
+import invariant from "tiny-invariant";
+
+import type { User } from "./models";
+
+invariant(
+ process.env.SESSION_SECRET,
+ "SESSION_SECRET must be set for authentication to work",
+);
+
+const sessionStorage = createCookieSessionStorage<{
+ user: User;
+}>({
+ cookie: {
+ name: "__session",
+ httpOnly: true,
+ path: "/",
+ sameSite: "lax",
+ secrets: [process.env.SESSION_SECRET],
+ secure: process.env.NODE_ENV === "production",
+ },
+});
+
+export async function createUserSession({
+ request,
+ user,
+ redirectTo,
+}: {
+ request: Request;
+ user: User;
+ redirectTo: string;
+}) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ session.set("user", user);
+
+ return redirect(redirectTo, {
+ headers: {
+ "Set-Cookie": await sessionStorage.commitSession(session, {
+ maxAge: 60 * 60 * 24 * 7, // 7 days
+ }),
+ },
+ });
+}
+
+export async function getUserFromSession(request: Request) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ return session.get("user") ?? null;
+}
+
+export async function requireUser(request: Request) {
+ const user = await getUserFromSession(request);
+
+ if (user === null) {
+ throw redirect("/login");
+ }
+
+ return user;
+}
+```
+
+그리고 바로 옆에 있는 `models.ts` 파일에서 `User` 모델도 내보내세요.
+
+```tsx title="shared/api/models.ts"
+import type { components } from "./v1";
+
+export type Article = components["schemas"]["Article"];
+export type User = components["schemas"]["User"];
+```
+
+이 코드가 작동하려면 `SESSION_SECRET` 환경 변수를 설정해야 합니다. 프로젝트 루트에 `.env` 파일을 만들고 `SESSION_SECRET=`을 작성한 다음 키보드에서 무작위로 키를 눌러 긴 무작위 문자열을 만드세요. 다음과 같은 결과가 나와야 합니다.
+
+
+```bash title=".env"
+SESSION_SECRET=dontyoudarecopypastethis
+```
+
+마지막으로 이 코드를 사용하기 위해 공개 API에 일부 내보내기를 추가하세요.
+
+```tsx title="shared/api/index.ts"
+export { GET, POST, PUT, DELETE } from "./client";
+
+export type { Article } from "./models";
+
+export { createUserSession, getUserFromSession, requireUser } from "./auth.server";
+```
+
+이제 RealWorld 백엔드와 실제로 통신하여 등록을 수행하는 코드를 작성할 수 있습니다. 그것을 `pages/sign-in/api`에 유지할 것입니다. `register.ts`라는 파일을 만들고 다음 코드를 넣으세요.
+
+
+```tsx title="pages/sign-in/api/register.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+
+import { POST, createUserSession } from "shared/api";
+
+export const register = async ({ request }: ActionFunctionArgs) => {
+ const formData = await request.formData();
+ const username = formData.get("username")?.toString() ?? "";
+ const email = formData.get("email")?.toString() ?? "";
+ const password = formData.get("password")?.toString() ?? "";
+
+ const { data, error } = await POST("/users", {
+ body: { user: { email, password, username } },
+ });
+
+ if (error) {
+ return json({ error }, { status: 400 });
+ } else {
+ return createUserSession({
+ request: request,
+ user: data.user,
+ redirectTo: "/",
+ });
+ }
+};
+```
+
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+```
+
+거의 다 왔습니다! 페이지와 액션을 `/register` 라우트에 연결하기만 하면 됩니다. `app/routes`에 `register.tsx`를 만드세요.
+
+```tsx title="app/routes/register.tsx"
+import { RegisterPage, register } from "pages/sign-in";
+
+export { register as action };
+
+export default RegisterPage;
+```
+
+이제 [http://localhost:3000/register](http://localhost:3000/register)로 가면 사용자를 생성할 수 있어야 합니다! 애플리케이션의 나머지 부분은 아직 이에 반응하지 않을 것입니다. 곧 그 문제를 해결하겠습니다.
+
+매우 유사한 방식으로 로그인 페이지를 구현할 수 있습니다. 직접 시도해 보거나 그냥 코드를 가져와서 계속 진행하세요.
+
+```tsx title="pages/sign-in/api/sign-in.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
+
+import { POST, createUserSession } from "shared/api";
+
+export const signIn = async ({ request }: ActionFunctionArgs) => {
+ const formData = await request.formData();
+ const email = formData.get("email")?.toString() ?? "";
+ const password = formData.get("password")?.toString() ?? "";
+
+ const { data, error } = await POST("/users/login", {
+ body: { user: { email, password } },
+ });
+
+ if (error) {
+ return json({ error }, { status: 400 });
+ } else {
+ return createUserSession({
+ request: request,
+ user: data.user,
+ redirectTo: "/",
+ });
+ }
+};
+```
+
+```tsx title="pages/sign-in/ui/SignInPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
+
+import type { signIn } from "../api/sign-in";
+
+export function SignInPage() {
+ const signInData = useActionData
+
+
+
+
+
+ Sign up
++ Have an account? +
+ + {registerData?.error && ( +-
+ {registerData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
+```
+
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+export { SignInPage } from './ui/SignInPage';
+export { signIn } from './api/sign-in';
+```
+
+```tsx title="app/routes/login.tsx"
+import { SignInPage, signIn } from "pages/sign-in";
+
+export { signIn as action };
+
+export default SignInPage;
+```
+
+이제 사용자가 이 페이지에 실제로 접근할 수 있는 방법을 제공해 봅시다.
+
+### 헤더
+
+1부에서 논의했듯이, 앱 헤더는 일반적으로 Widgets나 Shared에 배치됩니다. 매우 간단하고 모든 비즈니스 로직을 외부에 유지할 수 있기 때문에 Shared에 넣을 것입니다. 이를 위한 장소를 만들어 봅시다.
+
+```bash
+npx fsd shared ui
+```
+
+이제 다음 내용으로 `shared/ui/Header.tsx`를 만드세요.
+
+```tsx title="shared/ui/Header.tsx"
+import { useContext } from "react";
+import { Link, useLocation } from "@remix-run/react";
+
+import { CurrentUser } from "../api/currentUser";
+
+export function Header() {
+ const currentUser = useContext(CurrentUser);
+ const { pathname } = useLocation();
+
+ return (
+
+ );
+}
+```
+
+이 컴포넌트를 `shared/ui`에서 내보내세요.
+
+```tsx title="shared/ui/index.ts"
+export { Header } from "./Header";
+```
+
+헤더에서는 `shared/api`에 유지되는 컨텍스트에 의존합니다. 그것도 만드세요.
+
+```tsx title="shared/api/currentUser.ts"
+import { createContext } from "react";
+
+import type { User } from "./models";
+
+export const CurrentUser = createContext
+
+
+
+
+
+ Sign in
++ Need an account? +
+ + {signInData?.error && ( +-
+ {signInData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
+```
+
+```tsx title="pages/feed/ui/Pagination.tsx"
+import { Form, useLoaderData, useSearchParams } from "@remix-run/react";
+import { ExistingSearchParams } from "remix-utils/existing-search-params";
+
+import { LIMIT, type loader } from "../api/loader";
+
+export function Pagination() {
+ const [searchParams] = useSearchParams();
+ const { articles } = useLoaderDataPopular Tags
+ + +
+
+ );
+}
+```
+
+마지막으로 로더를 업데이트하여 새로운 필터를 처리하세요.
+
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET, requireUser } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+이 코드는 글에 좋아요를 표시하기 위해 `/article/:slug`로 `_action=favorite`과 함께 POST 요청을 보냅니다. 아직 작동하지 않겠지만, 글 읽기 페이지 작업을 시작하면서 이것도 구현할 것입니다.
+
+이것으로 피드가 공식적으로 완성되었습니다! 야호!
+
+### 글 읽기 페이지
+
+먼저 데이터가 필요합니다. 로더를 만들어 봅시다.
+
+```bash
+npx fsd pages article-read -s api
+```
+
+```tsx title="pages/article-read/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import invariant from "tiny-invariant";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
+
+import { GET, getUserFromSession } from "shared/api";
+
+async function throwAnyErrors
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ Read more... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
+```
+
+더 흥미로운 것은 `ArticleMeta`와 `Comments`입니다. 이들은 글 좋아요, 댓글 작성 등과 같은 쓰기 작업을 포함합니다. 이들을 작동시키려면 먼저 백엔드 부분을 구현해야 합니다. 페이지의 `api` 세그먼트에 `action.ts`를 만드세요:
+
+```tsx title="pages/article-read/api/action.ts"
+import { redirect, type ActionFunctionArgs } from "@remix-run/node";
+import { namedAction } from "remix-utils/named-action";
+import { redirectBack } from "remix-utils/redirect-back";
+import invariant from "tiny-invariant";
+
+import { DELETE, POST, requireUser } from "shared/api";
+
+export const action = async ({ request, params }: ActionFunctionArgs) => {
+ const currentUser = await requireUser(request);
+
+ const authorization = { Authorization: `Token ${currentUser.token}` };
+
+ const formData = await request.formData();
+
+ return namedAction(formData, {
+ async delete() {
+ invariant(params.slug, "Expected a slug parameter");
+ await DELETE("/articles/{slug}", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirect("/");
+ },
+ async favorite() {
+ invariant(params.slug, "Expected a slug parameter");
+ await POST("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfavorite() {
+ invariant(params.slug, "Expected a slug parameter");
+ await DELETE("/articles/{slug}/favorite", {
+ params: { path: { slug: params.slug } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async createComment() {
+ invariant(params.slug, "Expected a slug parameter");
+ const comment = formData.get("comment");
+ invariant(typeof comment === "string", "Expected a comment parameter");
+ await POST("/articles/{slug}/comments", {
+ params: { path: { slug: params.slug } },
+ headers: { ...authorization, "Content-Type": "application/json" },
+ body: { comment: { body: comment } },
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async deleteComment() {
+ invariant(params.slug, "Expected a slug parameter");
+ const commentId = formData.get("id");
+ invariant(typeof commentId === "string", "Expected an id parameter");
+ const commentIdNumeric = parseInt(commentId, 10);
+ invariant(
+ !Number.isNaN(commentIdNumeric),
+ "Expected a numeric id parameter",
+ );
+ await DELETE("/articles/{slug}/comments/{id}", {
+ params: { path: { slug: params.slug, id: commentIdNumeric } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async followAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "Expected a username parameter",
+ );
+ await POST("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ async unfollowAuthor() {
+ const authorUsername = formData.get("username");
+ invariant(
+ typeof authorUsername === "string",
+ "Expected a username parameter",
+ );
+ await DELETE("/profiles/{username}/follow", {
+ params: { path: { username: authorUsername } },
+ headers: authorization,
+ });
+ return redirectBack(request, { fallback: "/" });
+ },
+ });
+};
+```
+
+그 슬라이스에서 이를 내보내고 라우트에서도 내보내세요. 그리고 페이지 자체도 연결하겠습니다.
+
+```tsx title="pages/article-read/index.ts"
+export { ArticleReadPage } from "./ui/ArticleReadPage";
+export { loader } from "./api/loader";
+export { action } from "./api/action";
+```
+
+```tsx title="app/routes/article.$slug.tsx"
+import { ArticleReadPage } from "pages/article-read";
+
+export { loader, action } from "pages/article-read";
+
+export default ArticleReadPage;
+```
+
+이제 독자 페이지에서 좋아요 버튼을 아직 구현하지 않았지만, 피드의 좋아요 버튼이 작동하기 시작할 것입니다! 이 라우트로 "좋아요" 요청을 보내고 있었기 때문입니다. 한번 시도해 보세요.
+
+`ArticleMeta`와 `Comments`는 다시 한번 폼들의 모음입니다. 이전에 이미 해봤으니, 코드를 가져와서 넘어가겠습니다.
+
+```tsx title="pages/article-read/ui/ArticleMeta.tsx"
+import { Form, Link, useLoaderData } from "@remix-run/react";
+import { useContext } from "react";
+
+import { CurrentUser } from "shared/api";
+import type { loader } from "../api/loader";
+
+export function ArticleMeta() {
+ const currentUser = useContext(CurrentUser);
+ const { article } = useLoaderData
+
+
+
+
+ {article.article.title}
+ +
+
+ +
+
+
+
+
+
+ {article.article.body}
+-
+ {article.article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+ +
+
+
+
+
+
+ {currentUser !== null ? (
+
+ ) : (
+
+ );
+}
+```
+
+이것으로 우리의 글 읽기 페이지도 완성되었습니다! 이제 작성자를 팔로우하고, 글에 좋아요를 누르고, 댓글을 남기는 버튼들이 예상대로 작동해야 합니다.
+
+
+
+ )}
+
+ {comments.comments.map((comment) => (
+
+
+ + Sign in + or + Sign up + to add comments on this article. +
+
+
+ ))}
+
+
+
+ {comment.body}
+
+
+
+
+
+
+ {comment.author.username}
+
+ {comment.createdAt}
+ {comment.author.username === currentUser?.username && (
+
+
+
+ )}
+
+
+
+ );
+}
+```
+
+이 페이지는 현재 글(새로 작성하는 경우가 아니라면)을 가져와서 해당하는 폼 필드를 채웁니다. 이전에 본 적이 있습니다. 흥미로운 부분은 `FormErrors`인데, 이는 검증 결과를 받아 사용자에게 표시할 것입니다. 한번 살펴보겠습니다.
+
+```tsx title="pages/article-edit/ui/FormErrors.tsx"
+import { useActionData } from "@remix-run/react";
+import type { action } from "../api/action";
+
+export function FormErrors() {
+ const actionData = useActionData
+
+
+
+
+
+ -
+ {actionData.errors.map((error) => (
+
- {error} + ))} +
+ {tagListState.map((tag) => (
+
+
+ [" ", "Enter"].includes(e.key) && removeTag(tag)
+ }
+ onClick={() => removeTag(tag)}
+ >{" "}
+ {tag}
+
+ ))}
+
+
+ );
+}
+```
+
+이제 API 부분입니다. 로더는 URL을 살펴보고, 글 슬러그가 포함되어 있다면 기존 글을 수정하는 것이므로 해당 데이터를 로드해야 합니다. 그렇지 않으면 아무것도 반환하지 않습니다. 그 로더를 만들어 봅시다.
+
+```ts title="pages/article-edit/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+
+import { GET, requireUser } from "shared/api";
+
+async function throwAnyErrors+ +이중 인증을 처리하기 위해서는 `login()` 함수와 유사한 또 다른 요청 함수가 필요할 것입니다. 이러한 함수들은 `Shared`나 로그인 페이지의 `api` 세그먼트에 함께 배치할 수 있습니다. + +## 인증된 요청의 토큰 저장 방법 {#how-to-store-the-token-for-authenticated-requests} + +인증 방식이 로그인/비밀번호, OAuth, 2단계 인증 등 어떤 것이든, 결국 토큰이 발급됩니다. 이 토큰은 이후 요청에서 사용자 식별을 위해 저장되어야 합니다. + +웹 애플리케이션에서는 **쿠키**를 사용해 토큰을 저장하는 것이 가장 일반적이고 이상적인 방법입니다. 쿠키를 사용하면 토큰을 수동으로 관리할 필요가 없으며, 복잡한 처리를 줄일 수 있습니다. 만약 서버 사이드 렌더링을 지원하는 프레임워크(예: [Remix][ext-remix])를 사용 중이라면, 서버 사이드 쿠키 인프라를 `shared/api`에 저장하는 것이 좋습니다. Remix를 사용하는 예시는 튜토리얼의 [인증 섹션][tutorial-authentication]에서 확인할 수 있습니다. + +그러나 쿠키를 사용할 수 없는 상황에서는, 토큰을 직접 관리해야 합니다. 이 경우, 토큰 만료 시 갱신 로직을 함께 구현해야 할 수도 있습니다. 이 경우, 토큰 만료 시 갱신 로직을 함께 구현해야 합니다. FSD에서는 토큰을 저장할 수 있는 다양한 방법이 있습니다. + +### Shared에 저장하기 + +`shared/api`에 저장하는 접근 방식은 API 클라이언트와 잘 맞아떨어집니다. 인증이 필요한 다른 요청 함수에서 이 토큰을 쉽게 사용할 수 있기 때문입니다. API 클라이언트에서 반응형 스토어나 모듈 수준 변수를 사용해 토큰을 저장하고, `login()/logout()` 함수에서 해당 상태를 업데이트할 수 있습니다. + +토큰 자동 갱신은 API 클라이언트에서 미들웨어 형태로 구현할 수 있습니다. 모든 요청마다 실행되며, 아래와 같은 방식으로 동작합니다: + +- 사용자가 로그인하면 액세스 토큰과 갱신 토큰을 저장합니다. +- 인증이 필요한 요청을 수행합니다. +- 토큰이 만료되어 요청이 실패하면, 갱신 토큰을 사용해 새로운 토큰을 요청하고 저장한 후, 원래 요청을 다시 시도합니다. + +이 방법의 단점 중 하나는 토큰 관리 로직이 요청 로직과 같은 위치에 있어, 복잡해질 수 있다는 점입니다. 간단한 경우에는 문제가 없겠지만, 토큰 관리 로직이 복잡한 경우에는 요청과 관리 로직을 분리하는 것이 좋습니다. 요청 및 API 클라이언트는 `shared/api`에 두고, 토큰 관리 로직은 `shared/auth`에 두는 방식으로 나눌 수 있습니다. + +또 다른 단점은 백엔드가 토큰과 함께 현재 사용자 정보를 반환하는 경우, 이 정보를 별도로 저장하거나 `/me` 또는 `/users/current`와 같은 엔드포인트에서 다시 요청해야 한다는 점입니다. + +### Entities에 저장하기 + +FSD 프로젝트에서는 사용자 엔티티 또는 현재 사용자 엔티티를 사용하는 것이 일반적입니다. 두 엔티티는 같은 것을 가리킬 수도 있습니다. + +:::note + +**현재 사용자**는 "viewer" 또는 "me"라고도 합니다. 이는 권한과 개인 정보를 가진 단일 인증 사용자와 공개적으로 접근 가능한 정보로 구성된 모든 사용자 목록을 구별하기 위해 사용됩니다. + +::: + +User 엔티티에 토큰을 저장하려면 `model` 세그먼트에 반응형 스토어를 생성해야 합니다. 이 스토어는 토큰과 사용자 객체를 모두 포함할 수 있습니다. + +API 클라이언트는 일반적으로 `shared/api` 정의되거나 엔티티 전체에 분산되어 있습니다. 따라서 주요 과제는 레이어의 임포트 규칙([import rule on layers][import-rule-on-layers])을 위반하지 않으면서 다른 요청에서도 토큰을 사용할 수 있도록 하는 것입니다. + +> 레이어 규칙: 슬라이스의 모듈은 자기보다 낮은 레이어에 위치한 다른 슬라이스만 임포트할 수 있습니다. + +이 문제를 해결하기 위한 몇 가지 방법은 다음과 같습니다: + +1. **요청 시마다 토큰 수동 전달** + 이 방법은 가장 간단하지만, 번거롭고 타입 안전성이 보장되지 않으면 실수가 발생할 가능성이 큽니다. 또한 Shared의 API 클라이언트에 미들웨어 패턴을 적용하기 어렵습니다. +2. **앱 전역에서 글로벌 스토어로 토큰 관리** + 토큰을 context나 `localStorage`에 저장하고, `shared/api`에 토큰 접근 키를 보관합니다. 토큰의 반응형 저장소는 User 엔터티에서 내보내며, 필요한 경우 context Provider는 App 레이어에서 설정합니다. 이 방법은 API 클라이언트 설계를 유연하게 만들지만, 상위 레이어에 context 제공이 필요하다는 암묵적인 의존성을 발생시킵니다. 따라서 context나 `localStorage`가 제대로 설정되지 않았을 경우, 유용한 오류 메시지를 제공하는 것이 좋습니다. +3. **토큰 변경 시 API 클라이언트 업데이트** + 반응형 스토어를 활용해 엔티티의 스토어가 변경될 때마다 API 클라이언트의 토큰 스토어를 업데이트하는 구독(subscribe)을 생성할 수 있습니다. 이 방법은 상위 계층에 암묵적인 의존성을 만든다는 점에서는 이전 해결책과 비슷하지만, 이 방법은 더 "명령형(push)" 접근이고, 이전 방법은 더 "선언형(pull)" 접근입니다. + +엔티티의 `model`에 토큰을 저장하여 문제를 해결하면, 토큰 관리와 관련된 더 많은 비즈니스 로직을 추가할 수 있습니다. 예를 들어, `model` 세그먼트에 토큰 만료 시 갱신하는 로직을 추가하거나, 일정 시간이 지나면 토큰을 무효화하는 로직을 포함할 수 있습니다. +백엔드에 요청을 보내야 하는 경우에는 User 엔티티의 api 세그먼트나 `shared/api`를 사용할 수 있습니다. + +### Pages/Widgets에 저장하기 (권장하지 않음) + +애플리케이션 전역에 적용되는 상태(예: 액세스 토큰)를 페이지나 위젯에 저장하는 것은 권장되지 않습니다. 예를 들어, 로그인 페이지의 `model` 세그먼트에 토큰 스토어를 배치하는 대신, 이 아티클에서 제시한 처음 두 해결책인 Shared나 Entities를 사용하는 것이 권장됩니다. + +## 로그아웃 및 토큰 무효화 + +로그아웃 기능은 애플리케이션에서 중요한 기능이지만, 이를 위한 별도의 페이지는 없는 경우가 많습니다. 이 기능은 백엔드에 인증된 요청을 보내고, 토큰 스토어를 업데이트하는 작업으로 구성됩니다. + +모든 요청을 `shared/api`에 보관했다면, 로그인 함수 근처에 로그아웃 요청 함수를 두는 것이 좋습니다. 그렇지 않은 경우, 로그아웃 버튼이 있는 위치 근처에 로그아웃 요청 함수를 배치할 수 있습니다. 예를 들어, 모든 페이지에 나타나는 헤더 위젯에 로그아웃 링크가 있다면, 해당 요청을 그 위젯의 `api` 세그먼트에 배치하는 것이 좋습니다. + +토큰 스토어에 대한 업데이트는 로그아웃 버튼이 위치한 곳(예: 헤더 위젯)에서 트리거되어야 합니다. 이 요청과 스토어 업데이트를 해당 위젯의 `model` 세그먼트에서 결합할 수 있습니다. + +### 자동 로그아웃 + +로그아웃 요청 실패나 로그인 토큰 갱신 실패 시를 대비해 안전장치를 마련하는 것도 중요합니다. 이 두 경우 모두 토큰 스토어를 비워야 합니다. 토큰을 Entities에 저장하는 경우, 이 로직은 `model` 세그먼트에 배치할 수 있습니다. 토큰을 Shared에 저장하는 경우, 이 로직을 `shared/api`에 포함하면 세그먼트가 너무 복잡해질 수 있습니다. 따라서 토큰 관리 로직을 별도의 세그먼트(예: `shared/auth`)로 분리하는 것도 고려해볼 만합니다. + +[tutorial-authentication]: /docs/get-started/tutorial#authentication +[import-rule-on-layers]: /docs/reference/layers#import-rule-on-layers +[ext-remix]: https://remix.run +[ext-zod]: https://zod.dev diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/index.mdx b/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/index.mdx new file mode 100644 index 0000000000..1714b089c7 --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/index.mdx @@ -0,0 +1,36 @@ +--- +hide_table_of_contents: true +--- + +# Examples + +
+방법론 적용에 대한 예시들 +
+ +## Main + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { UserSwitchOutlined, LayoutOutlined, FontSizeOutlined } from "@ant-design/icons"; + +
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+```ts title="shared/ui/layout/useThemeSwitcher.ts"
+export function useThemeSwitcher() {
+ const [theme, setTheme] = useState("light");
+
+ function toggleTheme() {
+ setTheme(theme === "light" ? "dark" : "light");
+ }
+
+ useEffect(() => {
+ document.body.classList.remove("light", "dark");
+ document.body.classList.add(theme);
+ }, [theme]);
+
+ return [theme, toggleTheme] as const;
+}
+```
+
+사이드바의 구체적인 코드는 여러분 상상에 맡기겠습니다 😉.
+
+## layout에 widget 사용하기
+
+상황에 따라 layout에 특정 비즈니스 로직을 추가하고 싶을 때가 있습니다. 특히 [React Router][ext-react-router]와 같은 라우터를 사용해 깊이 중첩된 경로를 다룰 때 이러한 요구가 발생합니다. 이러한 경우 layout을 shared나 widgets 폴더에 두는 것이 어려울 수 있습니다. 이는 [layer에 대한 import 규칙][import-rule-on-layers] 때문입니다:
+
+> slice의 module은 자신보다 하위 layers에 위치한 다른 slice만 import할 수 있습니다.
+
+이 문제가 정말 중요한지 먼저 고려해 봐야 합니다. 레이아웃이 _정말로 필요한가요?_ 그리고 그 레이아웃이 _정말로 widget이어야 할까요?_ 만약 해당 비즈니스 로직이 2-3개의 페이지에서만 사용되고, 레이아웃이 그 widget을 감싸는 역할이라면, 다음 두 가지 방법을 고려해 보세요:
+
+1. **App 레이어에서 인라인으로 레이아웃 작성하기**
+ App 레이어에서 직접 레이아웃을 정의하는 것이 좋습니다. 이렇게 하면 중첩된 라우터를 사용할 때 특정 경로 그룹에만 해당 레이아웃을 적용할 수 있어 유연하게 사용할 수 있습니다.
+
+2. **복사하여 붙여넣기**
+ 코드 추상화는 항상 좋은 선택은 아닙니다. 특히 레이아웃은 자주 변경되지 않기 때문에, 필요한 경우 해당 페이지만 수정하는 것이 더 효율적일 수 있습니다. 이렇게 하면 다른 페이지에 영향을 주지 않고 수정할 수 있습니다. 팀원들이 다른 페이지를 수정하는 걸 잊을까 봐 걱정된다면, 페이지 간의 관계를 주석으로 남겨보세요. 큰 프로젝트에서도 협업이 더 편해질 거예요.
+
+위의 내용이 적절하지 않은 경우, 레이아웃에 widget을 포함하는 두 가지 해결책이 있습니다:
+
+1. **render props나 slots 사용하기**
+ 대부분의 프레임워크에서는 컴포넌트 내부에 표시될 UI 요소를 외부에서 전달할 수 있는 기능을 제공합니다. React에서는 [render props][ext-render-props]라고 하며, Vue에서는 [slots][ext-vue-slots]이라고 부릅니다.
+2. **레이아웃을 App 레이어로 이동하기**
+ 레이아웃을 `app/layouts` 등 App 레이어에 저장하고 원하는 widget을 구성할 수도 있습니다.
+
+## 추가 자료
+
+React 및 Remix(React Router와 유사)의 인증 레이아웃 구축에 대한 예시는 [튜토리얼][tutorial]에서 확인하실 수 있습니다.
+
+
+[tutorial]: /docs/get-started/tutorial
+[import-rule-on-layers]: /docs/reference/layers#import-rule-on-layers
+[ext-react-router]: https://reactrouter.com/
+[ext-render-props]: https://www.patterns.dev/react/render-props-pattern/
+[ext-vue-slots]: https://vuejs.org/guide/components/slots
+
diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/types.md b/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/types.md
new file mode 100644
index 0000000000..0c8a49279a
--- /dev/null
+++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/examples/types.md
@@ -0,0 +1,442 @@
+---
+sidebar_position: 2
+---
+
+# 타입
+
+이 가이드는 Typescript와 같은 정적 타입 언어의 데이터 타입을 다루는 방법과 FSD 구조 내에서 타입이 어떻게 활용되는지 설명합니다.
+
+:::info
+
+이 가이드에서 다루지 않는 질문이 있으신가요? 오른쪽 파란색 버튼을 눌러 피드백을 남겨주세요. 여러분의 의견을 반영해 가이드를 확장해 나가겠습니다!
+
+:::
+
+## 유틸리티 타입
+
+유틸리티 타입은 자체로 큰 의미를 가지지는 않지만, 다른 타입과 자주 사용되는 경우가 많은 타입입니다. 예를 들어, 배열의 값을 나타내는 ArrayValues 타입을 정의할 수 있습니다.
+
++`types`라는 카테고리는 `components`나 `hooks`와 마찬가지로 내용이 무엇인지를 설명할 뿐, 코드의 목적을 명확히 설명하지 않습니다. 슬라이스는 해당 코드의 목적을 정확히 설명할 수 있어야 합니다. + +::: + +## 비즈니스 엔티티 및 상호 참조 관계 + +앱에서 가장 중요한 타입 중 하나는 비즈니스 엔티티, 즉 앱에서 다루는 객체들 입니다. +예를 들어, 음악 스트리밍 앱에서는 _Song_, _Album_ 등이 비즈니스 엔티티가 될 수 있습니다. + +비즈니스 엔티티는 주로 백엔드 바탕이기 떄문에, 백엔드 응답을 타입으로 정의하는 것이 첫 번째 단계입니다. +각 엔드포인트에 대한 요청 함수와 그 응답을 타입으로 지정하는 것이 좋습니다, 추가적인 타입 안정성을 위해 [Zod][ext-zod]와 같은 스키마 검증 라이브러리를 사용해 응답을 검증할 수도 있습니다. + +예를 들어, 모든 요청을 Shared에 보관하는 경우 이렇게 작성할 수 있습니다. + +```ts title="shared/api/songs.ts" +import type { Artist } from "./artists"; + +interface Song { + id: number; + title: string; + artists: Array
+1. 애플리케이션 특성이 없는 제너릭 타입 +2. 애플리케이션 전체에 알고 있어야 하는 타입 + +첫 번째 경우에는 관련 타입을 Shared 폴더 안에 적절한 세그먼트로 배치하면 됩니다. 예를 들어, 분석 전역 변수를 위한 인터페이스가 있다면 `shared/analytics`에 두는 것이 좋습니다. + +:::warning + +경고: `shared/types` 폴더를 생성하지 않는 것이 좋습니다. "타입"이라는 공통된 속성으로 관련 없는 항목들을 그룹화하면, 프로젝트에서 코드를 검색할 때 효율성이 떨어질 수 있습니다. + +::: + +두 번째 경우는 Redux를 사용하지만 RTK가 없는 프로젝트에서 자주 발생합니다. 최종 스토어 타입은 모든 리듀서를 추가한 후에만 사용 가능하지만, 이 스토어 타입은 앱 전체에서 사용하는 셀렉터에 필요합니다. 예를 들어, 일반적인 스토어 정의는 다음과 같습니다: + +```ts title="app/store/index.ts" +import { combineReducers, rootReducer } from "redux"; + +import { songReducer } from "entities/song"; +import { artistReducer } from "entities/artist"; + +const rootReducer = combineReducers(songReducer, artistReducer); + +const store = createStore(rootReducer); + +type RootState = ReturnType
+이러한 타입을 위한 전용 위치를 코드베이스에 만드는 것이 좋습니다. 예를 들어 `shared/api/openapi`와 같은 위치가 적합합니다. 이상적으로는 이러한 파일이 무엇인지, 어떻게 재생성하는지 등을 설명하는 README 파일도 포함하는 것이 좋습니다. + +[import-rule-on-layers]: /docs/reference/layers#import-rule-on-layers +[ext-type-fest]: https://github.com/sindresorhus/type-fest +[ext-zod]: https://zod.dev +[ext-vite]: https://vitejs.dev +[ext-ts-reset]: https://www.totaltypescript.com/ts-reset diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/index.mdx b/i18n/kr/docusaurus-plugin-content-docs/current/guides/index.mdx new file mode 100644 index 0000000000..6d7a02ccda --- /dev/null +++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/index.mdx @@ -0,0 +1,50 @@ +--- +hide_table_of_contents: true +pagination_prev: get-started/index +--- + +# 🎯 Guides + +PRACTICE-ORIENTED + +
+Feature-Sliced Design(FSD)의 적용을 위한 종합 가이드입니다. 구체적인 예시, 마이그레이션 전략, 그리고 FSD 코드에서 발견할 수 있는 흔한 설계상의 문제들을 다룹니다. FSD를 프로젝트에 도입하거나 기존 구조를 개선하고자 할 때 참고하기 좋은 리소스입니다. +
+ +## Main + +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" +import { ToolOutlined, ImportOutlined, BugOutlined, FunctionOutlined } from "@ant-design/icons"; + +
+
+
+## 시작하기 전에 {#before-you-start}
+
+FSD로 전환을 고려할 때 팀에게 가장 중요한 질문은 _정말로 FSD가 필요한가?_ 라는 점입니다. FSD는 훌륭한 방법론이지만, 어떤 프로젝트에서는 굳이 필요하지 않을 수 있습니다.
+
+다음과 같은 이유가 있다면 전환을 고려해 볼 수 있습니다:
+
+1. 신규 팀원이 프로젝트에 적응하기 어려워하는 경우
+2. 코드 일부를 수정할 때, 관련 없는 다른 코드에 오류가 발생하는 경우가 **잦은** 경우
+3. 새 기능을 추가할 때 고려해야 할 사항이 너무 많아 어려움을 겪는 경우
+
+**팀원들의 동의 없이 FSD로 전환을 시도하지 마십시오.** 팀 리더라고 해도 전환의 이점이 비용보다 크다는 점을 먼저 설득하는 것이 중요합니다. 새로운 아키텍처를 도입하는 데는 학습과 전환 비용이 따르므로 충분한 논의가 필요합니다.
+
+또한, 아키텍처 변경은 즉시 관리층에 가시적으로 드러나지 않을 수 있습니다. 프로젝트 전환을 시작하기 전에 관리자의 동의를 얻고, 전환이 프로젝트에 어떤 이점을 줄 수 있는지 설명하는 것이 중요합니다.
+
+:::tip
+
+프로젝트 매니저를 설득해야 한다면, 다음과 같은 점을 고려해 보세요:
+1. FSD로의 전환은 점진적으로 진행될 수 있어 새로운 기능 개발을 중단할 필요가 없습니다.
+2. 체계적인 아키텍처는 새로운 개발자가 업무에 익숙해지는 시간을 크게 줄여줄 수 있습니다.
+3. FSD는 문서화된 아키텍처이기 때문에, 팀이 자체 문서화를 지속적으로 관리할 필요성이 줄어듭니다.
+
+:::
+
+---
+
+마이그레이션을 시작하기로 결정했다면, `📁 src` 폴더에 대한 별칭(alias)을 설정하는 것이 첫 단계입니다. 이후 설명에서는 `@`를 `./src`의 별칭으로 사용하겠습니다.
+
+## 1단계: 페이지별로 코드 분리하기 {#divide-code-by-pages}
+
+대부분의 커스텀(custom) 아키텍처는 어느 정도 페이지별로 코드가 나뉘어 있습니다. 만약 `📁 pages` 폴더가 이미 있다면 이 단계를 건너뛸 수 있습니다.
+
+`📁 routes` 폴더만 있다면, `📁 pages` 폴더를 새로 만들고 `📁 routes`에서 가능한 많은 컴포넌트 코드를 pages로 이동하세요. 이상적인 구조는 작은 라우트 파일과 큰 페이지 파일을 갖추는 것입니다. 코드를 이동할 때는 페이지별로 폴더를 만들고, index 파일을 추가합니다.
+
+:::note
+
+현재는 페이지들이 서로를 참조해도 괜찮습니다. 지금은 페이지별로 구조를 명확하게 구분하는 데 집중하세요. 참조 문제는 나중에 해결할 수 있습니다.
+
+:::
+
+라우트 파일:
+
+```js title="src/routes/products.[id].js"
+export { ProductPage as default } from "@/pages/product"
+```
+
+페이지 index 파일:
+
+```js title="src/pages/product/index.js"
+export { ProductPage } from "./ProductPage.jsx"
+```
+
+페이지 컴포넌트 파일:
+
+```jsx title="src/pages/product/ProductPage.jsx"
+export function ProductPage(props) {
+ return ;
+}
+```
+
+## 2단계: 페이지에서 나머지 코드 분리하기 {#separate-everything-else-from-pages}
+
+`📁 src/shared` 폴더를 만들고 `📁 pages`나 `📁 routes`에 의존하지 않는 코드를 모두 이곳으로 이동합니다. 그다음 `📁 src/app` 폴더를 만들어 pages 또는 routes에 의존하는 코드를 이곳으로 옮깁니다. 라우트 파일도 포함됩니다.
+
+Shared layer 에는 slices가 없으므로, segments끼리 서로 import해도 괜찮습니다.
+
+이제 폴더 구조는 다음과 같아야 합니다:
+
+📁 src
+-
+
-
+ ++
📁 actions
+-
+
- 📁 product +
- 📁 order +
+ - 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
-
+ ++
📁 routes
+-
+
- 📁 products.jsx +
- 📄 products.[id].jsx +
+ - 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
- 📄 App.jsx +
- 📄 index.js +
+
+
+## 3단계: 페이지 간의 cross-imports 해결하기 {#tackle-cross-imports-between-pages}
+
+
+
+
+각 페이지가 다른 페이지를 import하고 있는 경우, 다음 두 가지 방법 중 하나를 선택하여 해결할 수 있습니다:
+
+1. 필요한 코드만 복사하여 붙여넣어 참조를 제거합니다.
+2. 코드를 Shared layer의 적절한 segment로 이동합니다:
+ - UI 키트의 일부라면 `📁 shared/ui`로 이동
+ - 설정 상수라면 `📁 shared/config`로 이동
+ - 백엔드와의 상호작용 코드라면 `📁 shared/api`로 이동
+
+:::note
+
+**코드를 복사해서 붙여넣는 것이 항상 잘못된 것은 아닙니다.** 경우에 따라, 모듈로 재사용하는 것보다 복사하여 독립적으로 사용하는 것이 더 나을 수 있습니다. 특히, 각 페이지에서 코드가 조금씩 달라질 가능성이 있는 경우에는 불필요한 의존성을 만들지 않도록 하는 것이 중요합니다.
+
+다만, 비즈니스 로직을 반복하지 않도록 주의하세요. 비즈니스 로직을 여러 곳에 복사해 둘 경우, 오류 수정 시 여러 위치에서 코드를 수정해야 할 수도 있습니다.
+
+:::
+
+## 4단계: Shared 레이어 정리하기 {#unpack-shared-layer}
+
+이 단계에서는 Shared 레이어에 많은 코드가 남아 있을 수 있지만, 가능하면 이를 피하는 것이 좋습니다. Shared 레이어는 코드베이스 내 다른 모든 레이어에 의존할 수 있으므로, 여기에 변경이 발생하면 예기치 않은 결과를 초래할 가능성이 높아집니다
+
+한 페이지에서만 사용하는 코드가 있다면 해당 페이지의 slice로 이동하세요. _이는 actions, reducers, selectors에도 적용됩니다_. 모든 action을 한 곳에 모을 필요는 없으며, 관련된 action을 사용하는 위치에 가까이 배치하는 것이 더 좋습니다.
+
+최종 폴더 구조는 다음과 같아야 합니다:
+
+📁 src
+-
+
-
+ ++
📁 app
+-
+
-
+ ++
📁 routes
+-
+
- 📄 products.jsx +
- 📄 products.[id].jsx +
+ - 📄 App.jsx +
- 📄 index.js +
+ -
+
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
-
+ ++
📁 ui
+-
+
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ -
+
- 📁 catalog +
+ -
+
-
+ ++
📁 shared
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
+
+
+## 5단계: 기술적 목적에 따른 코드 정리 {#organize-by-technical-purpose}
+
+FSD에서는 코드를 _segments_ 단위로 나누어, 기술적 목적에 따라 구분합니다. 다음은 일반적인 세그먼트 예시입니다:
+
+- `ui` — UI 표시와 관련된 요소들: UI 컴포넌트, 날짜 형식 지정, 스타일 등
+- `api` — 백엔드와의 상호작용: 요청 함수, 데이터 타입, 매퍼 등
+- `model` — 데이터 모델: 스키마, 인터페이스, 스토어 및 비즈니스 로직
+- `lib` — 이 슬라이스의 다른 모듈에서 필요한 라이브러리 코드
+- `config` — 설정 파일과 기능 플래그
+
+필요에 따라 자체적인 segments를 추가할 수도 있습니다. 단, `components`, `actions`, `types`, `utils`처럼 코드의 성격에 따라 그룹화하기보다는, 코드의 목적에 따라 구분하는 것이 좋습니다.
+
+각 페이지에 segments를 나누어 코드를 정리하세요. 이미 `ui` 세그먼트가 있다면, 이제는 actions, reducers, selectors를 위한 `model` 세그먼트를 만들고, thunks와 mutations를 위한 `api` segments도 추가할 차례입니다.
+
+또한, Shared 레이어에 있는 폴더를 다음과 같이 재배치하세요:
+- `📁 components`, `📁 containers` — 대부분은 `📁 shared/ui`로 이동
+- `📁 helpers`, `📁 utils` — 재사용되는 헬퍼들이 남아 있다면 기능에 따라 그룹화하여 `📁 shared/lib`로 이동
+- `📁 constants` — 기능에 따라 그룹화하여 `📁 shared/config`로 이동
+
+
+## 선택 단계 {#optional-steps}
+
+### 6단계: 여러 페이지에서 사용하는 Redux slices를 entities/features으로 정리하기 {#form-entities-features-from-redux}
+
+일반적으로 여러 페이지에서 재사용되는 Redux slices는 제품이나 사용자와 같이 비즈니스와 관련이 깊습니다. 이러한 경우, slice를 Entities layer로 이동하고, 하나의 폴더에 하나의 entity가 있도록 구성합니다. 만약 Redux slice가 사용자의 특정 액션과 관련이 있다면, 이를 Features layer로 이동할 수 있습니다.
+
+Entities와 기능은 서로 독립적으로 사용될 수 있도록 설계됩니다. business domain에 따라 entities 간에 본질적인 연결이 필요한 경우, [business entities 연결 가이드][business-entities-cross-relations]를 참고하여 이러한 연결을 효율적으로 조직하는 방법을 확인하세요.
+
+이 slices와 관련된 API 함수는 `📁 shared/api`에 그대로 두어도 괜찮습니다.
+
+### 7단계: modules 리팩터링 {#refactor-your-modules}
+
+`📁 modules` 폴더는 일반적으로 비즈니스 로직을 담고 있어 FSD의 Features layer와 성격이 비슷합니다. 일부 모듈은 앱 헤더와 같이 큰 UI 요소를 설명하는 역할을 할 수도 있습니다. 이 경우 해당 modules을 Widgets layer로 이동하는 것이 좋습니다.
+
+### 8단계: `shared/ui`에서 UI 기본 요소 정리하기 {#form-clean-ui-foundation}
+
+`📁 shared/ui`는 비즈니스 로직이 포함되지 않고 재사용 가능한 UI 요소들로만 구성되어야 합니다.
+
+이전 `📁 components`와 `📁 containers`에 있던 UI 컴포넌트를 리팩터링하여 비즈니스 로직을 분리하고, 해당 로직을 상위 layers로 이동시키세요. 많은 곳에서 사용되지 않는다면, 코드 복사를 통해 필요한 부분에만 사용해도 좋습니다.
+
+## 추가 참고 자료 {#see-also}
+
+- [(러시아어 영상) Ilya Klimov — "끝없는 리팩터링의 악순환에서 벗어나기: 기술 부채가 동기와 제품에 미치는 영향](https://youtu.be/aOiJ3k2UvO4)
+
+[ext-steiger]: https://github.com/feature-sliced/steiger
+[business-entities-cross-relations]: /docs/guides/examples/types#business-entities-and-their-cross-references
diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md b/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md
new file mode 100644
index 0000000000..a5b32f934c
--- /dev/null
+++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v1.md
@@ -0,0 +1,171 @@
+---
+sidebar_position: 4
+---
+
+# v1에서 v2로의 마이그레이션
+
+## v2로의 전환 이유
+
+**feature-slices**의 원래 개념은 [2018년에 발표되었습니다][ext-tg-spb].
+
+그 이후로 여러 방법론이 발전하면서 개념이 확장되었지만, 기본 원칙은 유지되었습니다 **[기본 원칙 참고][ext-v1]**:
+
+- 표준화된 프론트엔드 프로젝트 구조 사용
+- *비즈니스 로직*에 따라 애플리케이션을 우선적으로 분리
+- 의도하지 않은 부작용과 순환 의존성 방지하기 위해 *독립적인 기능* 단위 사용
+- 모듈 내부로 직접 접근하지 않도록 *공용 API*를 사용하여 구조를 안정화
+
+그러나 이전 버전의 방법론에는 여전히 몇 가지 **개선점**이 필요했습니다.
+
+- 반복적인 코드(보일러플레이트)를 유발하는 경우가 있음
+- 코드베이스가 복잡해지고, 추상화 간의 규칙이 모호해지는 경우가 있음
+- 암묵적인 아키텍처 설계 방식이 프로젝트 확장과 신규 입사자의 온보딩을 어렵게 함
+
+새로운 버전([v2][ext-v2])은 기존 장점을 유지하면서도 **이러한 단점을 해결**하도록 설계되었습니다.
+
+또한 2018년 이후, [또 다른 유사한 방법론][ext-fdd-issues]인 [**feature-driven**][ext-fdd]이 개발되었으며, 이는 [Oleg Isonen][ext-kof]에 의해 처음 발표되었습니다.
+
+두 가지 접근 방식을 통합한 후, **기존의 실무를 개선**하고 발전시켜 애플리케이션을 더 유연하고 명확하며 효율적으로 만들었습니다.
+
+> 이러한 변경 사항은 방법론의 이름에도 영향을 주어, 이제는 "feature-sliced"라고 불리게 되었습니다.
+
+## 프로젝트를 v2로 마이그레이션하는 이유
+
+> `WIP:` 현재 방법론 버전은 개발 중이며 일부 세부 사항이 변경될 수 있습니다.
+
+#### 🔍 더 직관적이고 간단한 아키텍처
+
+v2 방법론은 **더 직관적이고 일반적인 추상화를 제공하여 개발자가 로직 분리를 쉽게 할 수 있게 합니다.**
+
+이를 통해 신규 인력의 온보딩이 수월해지며, 프로젝트 상태를 빠르게 이해하고 애플리케이션의 비즈니스 로직을 효과적으로 분배하는 데 도움이 됩니다.
+
+#### 📦 더 유연하고 실용적인 모듈화
+
+v2 방법론은 **로직을 더 유연하게 배치할 수 있습니다:**
+
+- 독립적인 부분을 처음부터 새로 리팩터링할 수 있는 유연성을 제공합니다.
+- 불필요하게 의존성이 얽히지 않도록 동일한 추상화를 사용할 수 있습니다.
+- 새로운 모듈을 추가할 때 *(layer => slice => segment)* 구조가 더 간단해집니다.
+
+#### 🚀 더 풍부한 명세, 계획, 커뮤니티 지원
+
+현재 `코어 팀`은 최신(v2) 버전의 방법론 개발에 활발히 참여하고 있습니다.
+
+따라서 v2에는 다음과 같은 요소들이 추가로 제공됩니다:
+
+- 더 다양한 사례와 문제 설명
+- 적용에 관한 가이드
+- 실전 예제 추가
+- 신규 인력의 온보딩과 방법론 개념 학습을 위한 풍부한 문서 제공
+- 아키텍처 개념과 규칙을 준수할 수 있도록 지원하는 툴킷
+
+> 물론, 첫 번째 버전에 대한 사용자 지원도 제공될 것입니다. 하지만 최신 버전이 최우선 과제입니다.
+>
+> 향후 주요 업데이트가 있을 때, **팀과 프로젝트에 대한 부담 없이** 최신 버전(v2) 방법론에 접근할 수 있습니다.
+
+## 변경 사항
+
+### `주요 변경` Layers
+
+이제 방법론은 상위 레벨에서 layers를 명확히 구분합니다.
+
+- `/app` > `/processes` > **`/pages`** > **`/features`** > `/entities` > `/shared`
+- *이제 모든 것이 기능/페이지로 취급되지는 않습니다.*
+- 이 접근 방식은 [layers에 대한 명시적인 규칙 설정][ext-tg-v2-draft]을 가능하게 합니다.
+- 모듈의 위치한 **layer가 높을수록** 더 많은 **컨텍스트**를 가집니다.
+
+ *(즉, 각 layer의 모듈은 하위 layer의 모듈만 가져올 수 있으며 상위 layer는 가져올 수 없습니다.)*
+
+- 모듈의 위치한 **layer가 낮을수록** 변경에 따른 **위험과 책임이** 커집니다.
+
+ *(보통 하위 layer가 더 자주 사용되기 때문입니다)*
+
+### `주요 변경` Shared
+
+프로젝트의 src 루트에 있던 `/ui`, `/lib`, `/api`와 같은 인프라 추상화는 이제 `/src/shared`라는 별도 디렉토리에 분리됩니다.
+
+- `shared/ui` - 여전히 애플리케이션의 공통 UI 컴포넌트 모음(선택 사항)
+ - *기존의 `Atomic Design` 사용도 가능합니다.*
+- `shared/lib` - 로직 구현을 위한 보조 라이브러리 모음
+ - *헬퍼 코드가 모여있는 덤프는 지양*
+- `shared/api` - API에 접근하는 공용 진입점
+ - *각 기능/페이지별로 로컬에 등록할 수 있지만, 권장하지 않음*
+- 이전과 마찬가지로 `shared`에 비즈니스 로직에 대한 명시적 결합이 없어야 합니다.
+ - *필요하다면 해당 관계를 `entities` 레벨이나 상위 레벨로 올려야 합니다.*
+
+### `새로 추가된` Entities, Processes
+
+v2에서는 로직 복잡성과 높은 결합을 줄이기 위한 **새로운 추상화**가 추가되었습니다.
+
+- `/entities` - **business entities** layer, 프론트엔드에서 필요한 비즈니스 모델이나 인위적인 entities를 포함하는 slices
+ - *예시: `user`, `i18n`, `order`, `blog`*
+- `/processes` - 애플리케이션 전반에 걸친 **비즈니스 프로세스** layer
+ - **선택적 layer**, 보통 *로직이 확장되어 여러 페이지에 걸쳐 분산되기 시작할 때* 사용을 권장
+ - *예시: `payment`, `auth`, `quick-tour`*
+
+### `주요 변경` 추상화 및 네이밍
+
+이제 특정 추상화 및 [명확한 네이밍 권장사항][refs-adaptability]이 정의되었습니다.
+
+[disc-process]: https://github.com/feature-sliced/documentation/discussions/20
+[disc-features]: https://github.com/feature-sliced/documentation/discussions/23
+[disc-entities]: https://github.com/feature-sliced/documentation/discussions/18#discussioncomment-422649
+[disc-shared]: https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453020
+
+[disc-ui]: https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-453132
+[disc-model]: https://github.com/feature-sliced/documentation/discussions/31#discussioncomment-472645
+[disc-api]: https://github.com/feature-sliced/documentation/discussions/66
+
+#### 레이어
+
+- `/app` — **애플리케이션 초기화 layer**
+ - *이전 명칭: `app`, `core`,`init`, `src/index` (가끔 사용됨)*
+- `/processes` — [**비즈니스 process layer**][disc-process]
+ - *이전 명칭: `processes`, `flows`, `workflows`*
+- `/pages` — **애플리케이션 페이지 layer**
+ - *이전 명칭: `pages`, `screens`, `views`, `layouts`, `components`, `containers`*
+- `/features` — [**기능 모듈 layer**][disc-features]
+ - *이전 명칭: `features`, `components`, `containers`*
+- `/entities` — [**비즈니스 entity layer**][disc-entities]
+ - *이전 명칭: `entities`, `models`, `shared`*
+- `/shared` — [**재사용 가능한 인프라 코드 layer**][disc-shared] 🔥
+ - *이전 명칭: `shared`, `common`, `lib`*
+
+#### 세그먼트
+
+- `/ui` — [**UI segment**][disc-ui] 🔥
+ - *이전 명칭: `ui`, `components`, `view`*
+- `/model` — [**비즈니스 로직 segment**][disc-model] 🔥
+ - *이전 명칭: `model`, `store`, `state`, `services`, `controller`*
+- `/lib` — **보조 코드 segment**
+ - *이전 명칭: `lib`, `libs`, `utils`, `helpers`*
+- `/api` — [**API segment**][disc-api]
+ - *이전 명칭: `api`, `service`, `requests`, `queries`*
+- `/config` — **애플리케이션 설정 segment**
+ - *이전 명칭: `config`, `env`, `get-env`*
+
+### `개선된` 낮은 결합
+
+이제 새로운 layers 덕분에 모듈 간 [낮은 결합 원칙을 준수][refs-low-coupling]하기가 훨씬 쉬워졌습니다.
+
+*동시에, 모듈 간 "결합을 해제"하기 어려운 상황은 가능한 한 피하는 것이 여전히 권장됩니다.*
+
+## 참고 자료
+
+- [React SPB Meetup #1 발표 노트"][ext-tg-spb]
+- [React Berlin Talk - Oleg Isonen "Feature Driven Architecture"][ext-kof-fdd]
+- [v1과의 비교 (커뮤니티 채팅)](https://t.me/feature_sliced/493)
+- [v2에 대한 새로운 아이디어와 설명 (atomicdesign 채팅)][ext-tg-v2-draft]
+- [새로운 버전 방법론 (v2)에 대한 추상화 및 네이밍 논의](https://github.com/feature-sliced/documentation/discussions/31)
+
+[refs-low-coupling]: /docs/reference/slices-segments#zero-coupling-high-cohesion
+[refs-adaptability]: /docs/about/understanding/naming
+
+[ext-v1]: https://feature-sliced.github.io/featureslices.dev/v1.0.html
+[ext-tg-spb]: https://t.me/feature_slices
+[ext-fdd]: https://github.com/feature-sliced/documentation/tree/rc/feature-driven
+[ext-fdd-issues]: https://github.com/kof/feature-driven-architecture/issues
+[ext-v2]: https://github.com/feature-sliced/documentation
+[ext-kof]: https://github.com/kof
+[ext-kof-fdd]: https://www.youtube.com/watch?v=BWAeYuWFHhs
+[ext-tg-v2-draft]: https://t.me/atomicdesign/18708
diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md b/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md
new file mode 100644
index 0000000000..64f0fe16a7
--- /dev/null
+++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/migration/from-v2-0.md
@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# v2.0에서 v2.1로의 마이그레이션
+
+v2.1의 핵심 변화는 페이지 중심(Page-First) 접근 방식을 통한 인터페이스 구조화입니다.
+
+### v2.0 방식
+이전 버전에서는:
+- Entity와 Feature을 최소 단위로 분해
+- 이를 기반으로 Widget과 Page를 구성
+- 대부분의 로직이 Entity와 Feature 계층에 집중
+- Page는 단순 조합 계층으로 취급
+
+### v2.1 방식
+새로운 버전에서는:
+- Page를 시작점으로 설정
+- UI와 비즈니스 로직을 우선적으로 Page 내에 구현
+- Shared 계층은 순수하게 재사용 가능한 기반 코드만 관리
+- 여러 페이지에서 공통으로 사용되는 로직만 하위 계층으로 분리
+
+Feature-Sliced Design(v2.1)에서는 Entity 간 Cross Import를 표준화하기 위해 `@x` 표기법이 도입되었습니다.
+
+## 마이그레이션 프로세스 {#how-to-migrate}
+
+v2.1은 하위 호환성을 보장하므로, v2.0 프로젝트는 수정 없이도 정상 동작합니다. 다만, 새로운 아키텍처 모델의 이점을 활용하기 위해 다음과 같은 단계적 개선을 권장합니다.
+
+### 1. 슬라이스(Slice) 병합
+
+[Steiger][steiger] 린터(Linter)를 활용하여 코드베이스를 분석할 수 있습니다:
+
+주요 린트 규칙:
+- [`insignificant-slice`][insignificant-slice]: 단일 Page에서만 사용되는 Slice 감지
+ - 해당 Slice의 코드를 관련 Page로 이동 권장
+- [`excessive-slicing`][excessive-slicing]: 과도한 Slices 분할 감지
+ - 유지보수성 향상을 위한 Slices 통합 또는 그룹화 제안
+
+```bash
+npx steiger src
+```
+
+Steiger를 사용하면 프로젝트에서 한 번만 사용되는 Slice들을 찾아낼 수 있습니다. 이러한 Slice들이 정말 독립적인 Slice로 존재할 필요가 있는지 검토해야 합니다.
+
+:::tip Slice 관리
+각 계층은 해당 계층에 속한 모든 Slices의 네임스페이스를 관리합니다. 이는 전역 변수를 관리하는 것과 비슷한 개념입니다:
+- 전역 변수는 꼭 필요한 경우에만 사용하듯이
+- Slice도 실제로 재사용되는 경우에만 독립적으로 분리하세요
+- 한 곳에서만 사용되는 코드는 해당 Page나 Feature 내부로 이동하는 것이 좋습니다
+:::
+
+### 2. Cross Import 표준화
+
+새로운 `@x-` 표기법을 사용하여 Entity 간 참조를 표준화합니다:
+
+```ts title="entities/B/some/file.ts"
+// 표준화된 Cross Import 방식
+import type { EntityA } from "entities/A/@x/B";
+```
+
+자세한 내용은 [Cross Import를 위한 Public API][public-api-for-cross-imports] 문서를 참조하세요.
+
+[insignificant-slice]: https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/insignificant-slice
+[steiger]: https://github.com/feature-sliced/steiger
+[excessive-slicing]: https://github.com/feature-sliced/steiger/tree/master/packages/steiger-plugin-fsd/src/excessive-slicing
+[public-api-for-cross-imports]: /docs/reference/public-api#public-api-for-cross-imports
+
+
+
+
diff --git a/i18n/kr/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx b/i18n/kr/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx
new file mode 100644
index 0000000000..1a31af2b7e
--- /dev/null
+++ b/i18n/kr/docusaurus-plugin-content-docs/current/guides/tech/with-nextjs.mdx
@@ -0,0 +1,117 @@
+---
+sidebar_position: 10
+---
+# NextJS와 함께 사용하기
+
+NextJS에서도 FSD(Feature-Sliced Design) 아키텍처를 구현할 수 있지만, 두 가지 점에서 NextJS의 프로젝트 구조 요구사항과 FSD 구조 간에 충돌이 발생합니다:
+
+- `pages` 폴더와의 라우팅 방식 차이
+- NextJS에서 `app` 폴더의 충돌 문제 또는 부재
+
+## FSD와 NextJS의 `페이지` 레이어 간 충돌 {#pages-conflict}
+
+NextJS는 애플리케이션 라우트를 정의하기 위해 `pages` 폴더를 사용하며, `pages` 폴더 내의 파일이 URL과 매핑되도록 설정합니다.
+하지만 이 방식은 FSD(Folder Slice Design) `개념에 맞지는 않습니다`. 특히, NextJS의 라우팅 방식으로는 FSD의 슬라이스 구조를 평평하게 유지하기 어려운 점이 있습니다.
+
+### NextJS의 `pages` 폴더를 프로젝트 루트 폴더로 이동하기 (권장)
+
+프로젝트 루트에 `pages` 폴더를 배치하고, FSD 구조에 맞춘 페이지들을 NextJS의 `pages` 폴더로 옮깁니다.
+이렇게 하면 `src` 폴더 내에서 FSD 구조를 유지할 수 있습니다.
+
+```sh
+├── pages # NextJS 페이지 폴더
+├── src
+│ ├── app
+│ ├── entities
+│ ├── features
+│ ├── pages # FSD 페이지 폴더
+│ ├── shared
+│ ├── widgets
+```
+
+### FSD 구조 내 `pages` 폴더 이름 변경하기
+
+다른 방법으로는 FSD 구조 내에서 `pages` 폴더의 이름을 변경하여 NextJS의 `pages` 폴더와 충돌을 피할 수도 있습니다.
+예를 들어, `pages` 폴더를 `views`로 이름을 변경하면 `src` 폴더 내의 FSD 구조를 유지하면서도 NextJS의 요구 사항과 충돌하지 않게 됩니다.
+
+```sh
+├── app
+├── entities
+├── features
+├── pages # NextJS 페이지 폴더
+├── views # 이름이 변경된 FSD 페이지 폴더
+├── shared
+├── widgets
+```
+
+이름을 변경하는 경우, 이를 프로젝트의 README나 내부 문서에 명확히 기록하여 변경 사항이 잘 전달되도록 하는 것이 좋습니다. 이러한 변경은 ["프로젝트 지식"][project-knowledge]의 일부로 문서화하는 것이 중요합니다.
+
+## NextJS에서 `app` 폴더 부재 문제 {#app-absence}
+
+NextJS 13버전 이하에서는 명시적인 `app` 폴더가 없으며,
+대신 `_app.tsx` 파일이 모든 페이지를 감싸는 컴포넌트 역할을 합니다.
+
+### `pages/_app.tsx` 파일에 app 기능 가져오기
+
+NextJS 구조에서 `app` 폴더가 없는 문제를 해결하려면, `app` 폴더 내에 `App` 컴포넌트를 생성하고, 이를 `pages/_app.tsx`에 가져와 NextJS가 사용할 수 있도록 설정하면 됩니다. 예를 들어:
+
+```tsx
+// app/providers/index.tsx
+
+const App = ({ Component, pageProps }: AppProps) => {
+ return (
+ 📁 src
+-
+
- 📁 app (unchanged) +
-
+ ++
📁 pages
+-
+
-
+ ++
📁 product
+-
+
- 📁 actions +
- 📁 reducers +
- 📁 selectors +
-
+ ++
📁 ui
+-
+
- 📄 Component.jsx +
- 📄 Container.jsx +
- 📄 ProductPage.jsx +
+ - 📄 index.js +
+ - 📁 catalog +
+ -
+
-
+ ++
📁 shared (only objects that are reused)
+-
+
- 📁 actions +
- 📁 api +
- 📁 components +
- 📁 containers +
- 📁 constants +
- 📁 i18n +
- 📁 modules +
- 📁 helpers +
- 📁 utils +
- 📁 reducers +
- 📁 selectors +
- 📁 styles +
+
Loading...
;
+ }
+
+ if (isError || !post) {
+ return <>{error?.message};
+ }
+
+ return (
+
+
+ );
+};
+```
+
+### 쿼리 팩토리 사용의 장점
+- **요청 구조화**: 팩토리를 통해 모든 API 요청을 한 곳에 조직화하여 코드의 가독성과 유지보수성을 높입니다.
+- **쿼리 및 키에 대한 편리한 접근**: 다양한 유형의 쿼리와 해당 키에 쉽게 접근할 수 있는 메서드를 제공합니다.
+- **쿼리 재호출 용이성**: 애플리케이션의 여러 부분에서 쿼리 키를 변경할 필요 없이 쉽게 재호출할 수 있습니다.
+
+## 페이지네이션
+이 섹션에서는 페이지네이션을 사용하여 게시물 엔티티를 가져오는 API 요청을 수행하는 `getPosts` 함수의 예를 소개합니다.
+
+### 1. `getPosts` 함수 생성하기
+getPosts 함수는 `api` 세그먼트의 `get-posts.ts` 파일에 있습니다.
+
+```tsx title="@/pages/post-feed/api/get-posts.ts"
+import { apiClient } from "@/shared/api/base";
+
+import { PostWithPaginationDto } from "./dto/post-with-pagination.dto";
+import { PostQuery } from "./query/post.query";
+import { mapPost } from "./mapper/map-post";
+import { PostWithPagination } from "../model/post-with-pagination";
+
+const calculatePostPage = (totalCount: number, limit: number) =>
+ Math.floor(totalCount / limit);
+
+export const getPosts = async (
+ page: number,
+ limit: number,
+): PromisePost id: {post.id}
+
+
+ {post.title}
+
+
+ {post.body}
+Owner: {post.userId}
+ + +
+
+
+
+ (#29BEDC, #517AED)
(#3193FF)
(#FFF)
(#3193FF)
-
+
+
## Social Preview
@@ -78,4 +80,3 @@ FSD имеет несколько вариаций логотипа для ра
- [Обсуждение (github)](https://github.com/feature-sliced/documentation/discussions/399)
- [История ребрендинга с референсами (figma)](https://www.figma.com/file/RPphccpoeasVB0lMpZwPVR/FSD-Brand?node-id=0%3A1)
-- [Демо ребрендинга](https://rebrand-sliced.netlify.app/en/)
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
index 2281454f01..73f21947b1 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/cheatsheet.mdx
@@ -1,5 +1,6 @@
---
-sidebar_position: 3
+# sidebar_position: 3
+unlisted: true
---
# Памятка по декомпозиции
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md
index 3a8e25ae44..1a51f0c1d8 100644
--- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md
+++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md
@@ -13,7 +13,7 @@ pagination_next: guides/index
### Существует ли тулкит или линтер? {#is-there-a-toolkit-or-a-linter}
-Есть официальный конфиг для ESLint — [@feature-sliced/eslint-config][eslint-config-official], и плагин для ESLint — [@conarti/eslint-plugin-feature-sliced][eslint-plugin-conarti], созданный участником сообщества Александром Белоусом. Мы будем рады вашим вкладам в эти проекты или созданию своих!
+Да! У нас есть линтер [Steiger][ext-steiger] для проверки архитектуры вашего проекта и [генераторы папок][ext-tools] через CLI или IDE.
### Где хранить layout/template страниц? {#where-to-store-the-layouttemplate-of-pages}
@@ -42,7 +42,7 @@ _Entity_ — это понятие из реальной жизни, с кото
### Есть ли какие-нибудь полезные ресурсы/статьи/т.д. по FSD? {#are-there-any-useful-resourcesarticlesetc-about-fsd}
-Да! Добро пожаловать! Этот раздел помогает бегло познакомиться с применением Feature-Sliced Design и основами методологии. Также вы поймете ключевые преимущества методологии и причины ее создания.
-## Главное {#main} - -import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" -import { RocketOutlined, BuildOutlined, PlaySquareOutlined } from "@ant-design/icons"; -На картинке выше: три столбика, обозначенные слева направо как "Слои", "Слайсы" и "Сегменты" соответственно.
+Столбик "Слои" содержит семь делений, расположенных сверху вниз и обозначенных "app", "processes", "pages", "widgets", "features", "entities" и "shared". Деление "processes" зачеркнуто. Деление "entities" соединено со вторым столбиком "Слайсы", показывая, что второй столбик является содержимым "entities".
+Столбик "Слайсы" содержит три деления, расположенных сверху вниз и обозначенных "user", "post" и "comment". Деление "post" соединено со столбиком "Сегменты" таким же образом, что и содержимое "post".
+Столбик "Сегменты" содержит три деления, расположенных сверху вниз и обозначенных "ui", "model" и "api".
+
+
+ );
+}
```
-#### Layers: app {#layers-app}
+Затем ре-экспортируйте этот компонент в публичном API страницы фида, файл `pages/feed/index.ts`:
-Как можно заметить - мы перенесли всю базовую логику в директорию `app/`
+```tsx title="pages/feed/index.ts"
+export { FeedPage } from "./ui/FeedPage";
+```
-Именно там, согласно методологии, стоит располагать всю подготовительную логику:
+Теперь подключите его к корневому маршруту. В Remix маршрутизация работает на файлах, и файлы маршрутов находятся в папке `app/routes`, что хорошо сочетается с Feature-Sliced Design.
-- подключение глобальных стилей (`/app/styles/**` + `/app/index.css`)
-- провайдеры и HOCs с инициализирующей логикой (`/app/providers/**`)
+Используйте компонент `FeedPage` в `app/routes/_index.tsx`:
-Пока что перенесем туда всю существующую логику, а другие директории оставим пустыми, как на схеме выше.
+```tsx title="app/routes/_index.tsx"
+import type { MetaFunction } from "@remix-run/node";
+import { FeedPage } from "pages/feed";
-```tsx title=app/index.tsx
-import "./index.css";
+export const meta: MetaFunction = () => {
+ return [{ title: "Conduit" }];
+};
-const App = () => {...}
+export default FeedPage;
```
-### 1.3 Подключим глобальные стили {#13-enabling-global-styles}
+Затем, если вы запустите dev-сервер и откроете приложение, вы должны увидеть баннер Conduit!
+
+
-#### Установим зависимости {#install-dependencies}
+### API-клиент
-В туториале устанавливаем sass, но можно взять и любой другой препроцессор, поддерживающий импорты
+Чтобы общаться с бэкендом RealWorld, давайте создадим удобный API-клиент в Shared. Создайте два сегмента, `api` для клиента и `config` для таких переменных как базовый URL бэкенда:
-```cmd
-$ npm i sass
+```bash
+npx fsd shared --segments api config
```
-#### Заводим файлы для стилей {#creating-files-for-styles}
+Затем создайте `shared/config/backend.ts`:
-##### Для css-переменных {#for-css-variables}
+```tsx title="shared/config/backend.ts"
+export const backendBaseUrl = "https://api.realworld.io/api";
+```
-```scss title=app/styles/vars.scss
-:root {
- --color-dark: #242424;
- --color-primary: #108ee9;
- ...
-}
+```tsx title="shared/config/index.ts"
+export { backendBaseUrl } from "./backend";
```
-##### Для нормализации стилей {#to-normalize-styles}
+Поскольку проект RealWorld предоставляет [спецификацию OpenAPI](https://github.com/gothinkster/realworld/blob/main/api/openapi.yml), мы можем автоматически сгенерировать типы для нашего API-клиента. Мы будем использовать [пакет `openapi-fetch`](https://openapi-ts.pages.dev/openapi-fetch/), в котором дополнительно есть генератор типов.
-```scss title=app/styles/normalize.scss
-html {
- scroll-behavior: smooth;
-}
-...
+Выполните следующую команду, чтобы сгенерировать актуальные типы для API:
+
+```bash
+npm run generate-api-types
+```
+
+В результате будет создан файл `shared/api/v1.d.ts`. Мы воспользуемся этим файлом в `shared/api/client.ts` для создания типизированного клиента API:
+
+```tsx title="shared/api/client.ts"
+import createClient from "openapi-fetch";
+
+import { backendBaseUrl } from "shared/config";
+import type { paths } from "./v1";
+
+export const { GET, POST, PUT, DELETE } = createClient
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+ );
+}
```
-#### Добавим HOC для инициализации роутера {#add-hoc-to-initialize-the-router}
+Кнопка "Мне нравится" пока ничего не делает, мы исправим это, когда перейдем на страницу чтения статей и реализуем функцию "Мне нравится".
-```tsx title=app/providers/with-router.tsx
-import { Suspense } from "react";
-import { BrowserRouter } from "react-router-dom";
+Теперь мы можем получить статьи и отобразить кучу этих карточек предпросмотра. Получение данных в Remix осуществляется с помощью *загрузчиков* — серверных функций, которые собирают те данные, которые нужны странице. Загрузчики взаимодействуют с API от имени страницы, поэтому мы поместим их в сегмент `api` страницы:
-export const withRouter = (component: () => React.ReactNode) => () => (
-
+
+
+
+
+
+
+
+ {article.author.username}
+
+
+ {new Date(article.createdAt).toLocaleDateString(undefined, {
+ dateStyle: "long",
+ })}
+
+
+
+ {article.title}
+{article.description}
+ Read more... +-
+ {article.tagList.map((tag) => (
+
- + {tag} + + ))} +
+
+ );
+}
+```
-Методология пока никак не регламентирует реализацию этой логики
+### Фильтрация по тегам
-:::
+Что касается тегов, то наша задача — получить их из бэкенда и запомнить выбранный пользователем тег. Мы уже знаем, как загружать из бэкенда — это еще один запрос от функции-загрузчика. Мы будем использовать удобную функцию `promiseHash` из пакета `remix-utils`, который уже установлен.
-##### Временная страница, только для проверки роутинга {#temporary-page-only-for-checking-the-routing}
+Обновите файл загрузчика, `pages/feed/api/loader.ts`, следующим кодом:
-Ее можно удалить позднее
+```tsx title="pages/feed/api/loader.ts"
+import { json } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
-```tsx title=pages/test/index.tsx
-const TestPage = () => {
- return
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+ Test Page
;
+import { GET } from "shared/api";
+
+async function throwAnyErrors
+
+ );
+}
```
-##### Сформируем роуты {#lets-form-the-routes}
+Затем нам нужно использовать параметр поиска тегов в нашем загрузчике. Измените функцию `loader` в `pages/feed/api/loader.ts` на следующую:
-```tsx title=pages/index.tsx
-// Либо использовать @loadable/component, в рамках туториала - некритично
-import { lazy } from "react";
-import { Route, Routes, Navigate } from "react-router-dom";
+```tsx title="pages/feed/api/loader.ts"
+import { json, type LoaderFunctionArgs } from "@remix-run/node";
+import type { FetchResponse } from "openapi-fetch";
+import { promiseHash } from "remix-utils/promise";
-const TestPage = lazy(() => import("./test"));
+import { GET } from "shared/api";
-export const Routing = () => {
- return (
-
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
```
-:::tip
+Ну вот, это тоже сделали. Есть еще список вкладок, который можно реализовать аналогичным образом, но давайте повременим с этим, пока не реализуем аутентификацию. Кстати, о ней!
+
+### Аутентификация {#authentication}
+
+Аутентификация включает в себя две страницы — одну для входа в систему и другую для регистрации. Они, в основном, очень схожие, поэтому имеет смысл держать их в одном слайсе, `sign-in`, чтобы при необходимости можно было переиспользовать код.
-Но вы можете использовать **любой другой UIKit** или же **создать собственный**, расположив компоненты в `shared/ui` - именно там рекомендуется хранить UIKit приложения:
+Создайте `RegisterPage.tsx` в сегменте `ui` в `pages/sign-in` со следующим содержимым:
-```ts
-import { Checkbox } from "antd"; // ~ "shared/ui/checkbox"
-import { Card } from "antd"; // ~ "shared/ui/card"
+```tsx title="pages/sign-in/ui/RegisterPage.tsx"
+import { Form, Link, useActionData } from "@remix-run/react";
+
+import type { register } from "../api/register";
+
+export function RegisterPage() {
+ const registerData = useActionData
+
+
+
+
+ conduit
+A place to share your knowledge.
+
+
+
+
+
+ {articles.articles.map((article) => (
+
+
+
+
+
+
+ Popular Tags
+ + +
+
+ );
+}
```
-:::
+Сейчас нам нужно исправить сломанный импорт. Он обращается к новому сегменту, поэтому создайте его:
-## 2. Реализация бизнес-логики {#2-implementing-business-logic}
+```bash
+npx fsd pages sign-in -s api
+```
-:::note
+Однако прежде чем мы сможем реализовать бэкенд-часть регистрации, нам нужен некоторый инфраструктурный код для Remix для обработки сессий. Отправим его в Shared, на случай, если он понадобится какой-либо другой странице.
-Постараемся сконцентрироваться не на реализации каждого модуля, а на их последовательной композиции
+Поместите следующий код в `shared/api/auth.server.ts`. Этот код очень специфичен для Remix, так что не беспокойтесь, если там не все понятно, просто скопируйте и вставьте:
-:::
+```tsx title="shared/api/auth.server.ts"
+import { createCookieSessionStorage, redirect } from "@remix-run/node";
+import invariant from "tiny-invariant";
-### 2.1 Проанализируем функциональность {#21-lets-analyze-the-functionality}
+import type { User } from "./models";
-Прежде чем приступать к коду, надо определиться - [какую ценность мы хотим донести конечному пользователю][refs-needs]
+invariant(
+ process.env.SESSION_SECRET,
+ "SESSION_SECRET must be set for authentication to work",
+);
-Для этого, декомпозируем нашу функциональность *по зонам ответственности (слоям)*
+const sessionStorage = createCookieSessionStorage<{
+ user: User;
+}>({
+ cookie: {
+ name: "__session",
+ httpOnly: true,
+ path: "/",
+ sameSite: "lax",
+ secrets: [process.env.SESSION_SECRET],
+ secure: process.env.NODE_ENV === "production",
+ },
+});
-
+export async function createUserSession({
+ request,
+ user,
+ redirectTo,
+}: {
+ request: Request;
+ user: User;
+ redirectTo: string;
+}) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
+
+ session.set("user", user);
+
+ return redirect(redirectTo, {
+ headers: {
+ "Set-Cookie": await sessionStorage.commitSession(session, {
+ maxAge: 60 * 60 * 24 * 7, // 7 days
+ }),
+ },
+ });
+}
-#### Pages
+export async function getUserFromSession(request: Request) {
+ const cookie = request.headers.get("Cookie");
+ const session = await sessionStorage.getSession(cookie);
-Набросаем базово необходимые страницы, и пользовательские ожидания от них:
+ return session.get("user") ?? null;
+}
-1. `TasksListPage` - страница "Список задач"
- - Смотреть список задач
- - Переходить к странице конкретной задачи
- - *Помечать выполненной/невыполненной конкретную задачу*
- - Задавать фильтрацию по выполненным/невыполненным задачам
+export async function requireUser(request: Request) {
+ const user = await getUserFromSession(request);
-2. `TaskDetailsPage` - страница "Карточка задачи"
- - Смотреть информацию по задаче
- - *Помечать выполненной/невыполненной конкретную задачу*
- - Возвращаться к списку задач
+ if (user === null) {
+ throw redirect("/login");
+ }
-Каждая из описанных возможностей - представляет из себя часть функциональности
+ return user;
+}
+```
-##### Обычный подход {#usual-approach}
+А также экспортируйте модель `User` из файла `models.ts`, расположенного рядом с ним:
-И есть большой соблазн
+```tsx title="shared/api/models.ts"
+import type { components } from "./v1";
-- либо всю логику реализовать в директории каждой конкретной страницы.
-- либо все "возможно переиспользуемые" модули вынести в общую папку `src/components` или подобную
+export type Article = components["schemas"]["Article"];
+export type User = components["schemas"]["User"];
+```
-Но если для маленького и недолгоживущего проекта такое решение подошло бы, то в реальной корпоративной разработке, оно **может поставить крест** на дальнейшем развитии проекта, превратив его в **"еще одно дремучее легаси"**
+Прежде чем этот код заработает, необходимо установить переменную окружения `SESSION_SECRET`. Создайте файл `.env` в корне проекта, пропишите в нем `SESSION_SECRET=`, а затем пробегитесь по клавиатуре, чтобы создать длинную случайную строку. У вас должно получиться что-то вроде этого:
-Обусловлено это обычными условиями развития проекта:
+```bash title=".env"
+SESSION_SECRET=несмейтеэтокопировать
+```
-- требования меняются достаточно часто
-- появляются новые обстоятельства
-- техдолг копится с каждым днем и все сложнее добавлять новые фичи
-- нужно масштабировать как сам проект, так и его команду
+Наконец, добавьте несколько экспортов в публичный API, чтобы использовать этот код:
-##### Альтернативный подход {#alternative-approach}
+```tsx title="shared/api/index.ts"
+export { GET, POST, PUT, DELETE } from "./client";
-Даже при базовом разбиении мы видим, что:
+export type { Article } from "./models";
-- между страницами есть общие сущности и их отображение *(Task)*
-- между страницами есть общие фичи *(Помечать задачу выполненной / невыполненной)*
+export { createUserSession, getUserFromSession, requireUser } from "./auth.server";
+```
-Соответственно, кажется логичным продолжать декомпозировать задачу, но уже исходя из перечисленных выше возможностей для пользователя.
+Теперь мы можем написать код, который будет общаться с бэкендом RealWorld для регистрации. Мы сохраним его в `pages/sign-in/api`. Создайте файл `register.ts` и поместите в него следующий код:
-#### Features
+```tsx title="pages/sign-in/api/register.ts"
+import { json, type ActionFunctionArgs } from "@remix-run/node";
-Части функциональности, несущие ценность пользователю
+import { POST, createUserSession } from "shared/api";
-- `
+
+
+
+
+
+ Sign up
++ Have an account? +
+ + {registerData?.error && ( +-
+ {registerData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
+ );
+}
```
-:::info
+```tsx title="pages/sign-in/index.ts"
+export { RegisterPage } from './ui/RegisterPage';
+export { register } from './api/register';
+export { SignInPage } from './ui/SignInPage';
+export { signIn } from './api/sign-in';
+```
-Если вам нужны именованные экспорты неймспейсов для декларации Public API, можно посмотреть в сторону [@babel/plugin-proposal-export-namespace-from](https://babeljs.io/docs/en/babel-plugin-proposal-export-namespace-from)
+```tsx title="app/routes/login.tsx"
+import { SignInPage, signIn } from "pages/sign-in";
-Либо же, как альтернатива, использовать более развернутую конструкцию
+export { signIn as action };
-```ts title={layer}/foo/index.ts
-import { Card as FooCard, Thumbnail as FooThumbnail, ... } from "./ui";
-import * as fooModel from "./model";
+export default SignInPage;
+```
+
+Теперь давайте дадим пользователям возможность попасть на эти страницы.
+
+### Хэдер
+
+Как мы уже говорили в первой части, хэдер приложения обычно размещается либо в Widgets, либо в Shared. Мы поместим его в Shared, потому что он очень прост, и вся бизнес-логика может быть сохранена за его пределами. Давайте создадим для него место:
-export { FooCard, FooThumbnail, fooModel };
+```bash
+npx fsd shared ui
```
-:::
+Теперь создайте `shared/ui/Header.tsx` со следующим содержимым:
-### 2.3 Отобразим базово список задач {#23-lets-display-the-basic-task-list}
+```tsx title="shared/ui/Header.tsx"
+import { useContext } from "react";
+import { Link, useLocation } from "@remix-run/react";
-#### (entities) Карточка задачи {#entities-task-card}
+import { CurrentUser } from "../api/currentUser";
-```tsx title=entities/task/ui/task-row/index.tsx
-import { Link } from "react-router-dom";
-import cn from "classnames"; // Можно смело использовать аналоги
-import { Row } from "antd"; // ~ "shared/ui/row"
+export function Header() {
+ const currentUser = useContext(CurrentUser);
+ const { pathname } = useLocation();
-export const TaskRow = ({ data, titleHref }: TaskRowProps) => {
- return (
-
+
+
+
+
+
+ Sign in
++ Need an account? +
+ + {signInData?.error && ( +-
+ {signInData.error.errors.body.map((error) => (
+
- {error} + ))} +
+
);
-};
+}
```
-### 2.4 Добавим переключение статуса задач {#24-adding-task-status-switching}
+```tsx title="pages/feed/ui/Pagination.tsx"
+import { Form, useLoaderData, useSearchParams } from "@remix-run/react";
+import { ExistingSearchParams } from "remix-utils/existing-search-params";
-#### (entities) Переключение статуса задачи {#entities-switching-the-task-status}
+import { LIMIT, type loader } from "../api/loader";
-```ts title=entities/task/model/index.ts
-export const toggleTask = createEventPopular Tags
+ + +
+
+
+