From f5dc46aa75d149884a47cb66798a471cfae15eeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80?= Date: Wed, 22 Apr 2026 00:42:58 +0900 Subject: [PATCH 1/4] docs(kr): add Korean translation for Astro integration guide --- .../docs/kr/docs/guides/tech/with-astro.mdx | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 src/content/docs/kr/docs/guides/tech/with-astro.mdx diff --git a/src/content/docs/kr/docs/guides/tech/with-astro.mdx b/src/content/docs/kr/docs/guides/tech/with-astro.mdx new file mode 100644 index 000000000..e39e960de --- /dev/null +++ b/src/content/docs/kr/docs/guides/tech/with-astro.mdx @@ -0,0 +1,76 @@ +--- +title: Usage with Astro +sidebar: + order: 10 +--- + +import { FileTree } from '@astrojs/starlight/components'; + +Astro와 FSD는 같은 `src/pages` 폴더를 다른 용도로 사용해 충돌이 발생합니다. + +- **Astro**: `src/pages`는 라우트 폴더입니다. Astro가 이 폴더에서 라우트 파일을 찾습니다. +- **FSD**: `pages`는 layer 이름입니다. page 단위 코드를 이 layer에 둡니다. + +이 문제를 피하려면 FSD의 pages Layer는 `📁 src/_pages`에 두고, `📁 src/pages`는 라우팅에만 사용합니다. +이렇게 하면 Astro 라우팅은 `src/pages`에서 처리하고, FSD의 페이지 코드는 `src/_pages`에서 관리할 수 있습니다. + + +- src + - pages Astro 라우트 + - 404.astro + - index.astro + - _pages FSD pages layer + - home + - ui + - HomePage.astro + - index.ts + + +`src/pages`의 파일은 FSD Layer의 페이지 컴포넌트를 불러와 렌더링하는 역할만 합니다. + +```astro title="src/pages/index.astro" +--- +import { HomePage } from '@/_pages/home'; +--- + + +``` + +## 경로 별칭 설정하기 + +`src` 아래 파일을 `@/`로 불러오려면 `tsconfig.json`에 경로 별칭을 추가합니다. + +```json title="tsconfig.json" +{ + "extends": "astro/tsconfigs/strict", + "compilerOptions": { + "paths": { + "@/*": ["./src/*"] + } + } +} +``` + +## Integration과 함께 사용하기 + +[Starlight](https://starlight.astro.build/) 같은 일부 Astro integration은 Markdown이나 MDX로 작성한 문서를 구조화해 다루는 **Content Collections** 기능을 사용합니다. 이런 integration은 보통 `📁 src/content/docs`처럼 정해진 위치에 파일이 있어야 동작합니다. + +Integration이 요구하는 폴더 위치는 바꾸지 않고 그대로 둡니다. Content Collections 폴더는 FSD Layer와 이름이 겹치지 않는 경우가 대부분이라, `_pages`나 `shared` 같은 FSD Layer를 이 폴더들과 나란히 둘 수 있습니다. + + +- src + - _pages FSD pages layer + - ... + - content Integration이 사용하는 폴더 (Starlight docs 등) + - docs + - getting-started.md + - shared FSD shared layer + - ... + + +라우팅과 렌더링은 integration에 맡기고, 프로젝트에서 만드는 나머지 화면과 기능은 FSD 구조로 관리합니다. + +## 참고 자료 + +- [Astro Routing](https://docs.astro.build/en/guides/routing/) +- [Astro Project Structure](https://docs.astro.build/en/basics/project-structure/) \ No newline at end of file From c9a690d812f8588138cbf9d39217e02fa9fd60f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80?= Date: Thu, 23 Apr 2026 00:20:20 +0900 Subject: [PATCH 2/4] docs(kr): refine intro wording in Astro guide --- src/content/docs/kr/docs/guides/tech/with-astro.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/content/docs/kr/docs/guides/tech/with-astro.mdx b/src/content/docs/kr/docs/guides/tech/with-astro.mdx index e39e960de..54c10dc0f 100644 --- a/src/content/docs/kr/docs/guides/tech/with-astro.mdx +++ b/src/content/docs/kr/docs/guides/tech/with-astro.mdx @@ -6,13 +6,11 @@ sidebar: import { FileTree } from '@astrojs/starlight/components'; -Astro와 FSD는 같은 `src/pages` 폴더를 다른 용도로 사용해 충돌이 발생합니다. +Astro와 FSD는 모두 `pages`라는 명칭을 사용하지만, 의미는 다릅니다. +Astro에서 `📁 src/pages`는 파일 기반 라우팅을 위한 폴더이고, FSD에서 `pages`는 페이지 단위를 나타내는 layer입니다. +FSD의 `pages` layer를 Astro 폴더 구조에 반영하면 `📁 src/pages`를 사용하게 되는데, Astro도 같은 경로를 파일 기반 라우팅에 사용하므로 두 구조가 충돌합니다. +이를 구분하기 위해 FSD의 `pages` layer는 `📁 src/_pages`에 두고, `📁 src/pages`는 Astro의 파일 기반 라우팅 전용으로 유지합니다. -- **Astro**: `src/pages`는 라우트 폴더입니다. Astro가 이 폴더에서 라우트 파일을 찾습니다. -- **FSD**: `pages`는 layer 이름입니다. page 단위 코드를 이 layer에 둡니다. - -이 문제를 피하려면 FSD의 pages Layer는 `📁 src/_pages`에 두고, `📁 src/pages`는 라우팅에만 사용합니다. -이렇게 하면 Astro 라우팅은 `src/pages`에서 처리하고, FSD의 페이지 코드는 `src/_pages`에서 관리할 수 있습니다. - src @@ -36,7 +34,7 @@ import { HomePage } from '@/_pages/home'; ``` -## 경로 별칭 설정하기 +## Setting up path aliases `src` 아래 파일을 `@/`로 불러오려면 `tsconfig.json`에 경로 별칭을 추가합니다. From 0138803a0cf4acb907032b64bc242d33077ae86e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80?= Date: Thu, 23 Apr 2026 00:44:40 +0900 Subject: [PATCH 3/4] docs(kr): improve wording in Next.js App Router conflict section --- src/content/docs/kr/docs/guides/tech/with-nextjs.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx b/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx index de5b98b9a..e571d0a24 100644 --- a/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx +++ b/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx @@ -13,11 +13,15 @@ FSD는 Next.js의 App Router와 Pages Router 양쪽에 적용할 수 있습니 ### `app` layer에서 FSD와 Next.js의 충돌 \{#conflict-between-fsd-and-nextjs-in-the-app-layer\} -App Router에서는 `app` 폴더 구조가 곧 라우트 구조가 됩니다. 반면 FSD에서 `app`은 라우트 폴더가 아니라 애플리케이션 전역 구성을 위한 layer입니다. 두 구조가 같은 `app` 폴더를 서로 다른 용도로 사용하기 때문에 충돌이 발생합니다. +App Router에서는 `app` 폴더 구조가 그대로 라우트 구조로 사용됩니다. 반면 FSD에서 `app`은 애플리케이션 전역 구성을 담당하는 layer입니다. +두 구조에서 `app` 폴더가 담당하는 역할이 다르기 때문에 같은 위치에서 함께 사용할 수 없으며, 구조 충돌이 발생합니다. -이 충돌을 피하려면 Next.js의 `app` 폴더는 프로젝트 루트에 두고, 여기에는 라우트 파일만 둡니다. 실제 페이지 파일은 `src` 하위의 FSD 구조에 유지합니다. 루트 `app`의 각 라우트 파일은 `src/pages`의 페이지 파일을 가져와 연결합니다. +이 충돌을 피하려면 Next.js의 `app` 폴더는 프로젝트 루트에 두고, 라우팅에 필요한 파일만 배치합니다. +페이지 파일은 `src` 하위의 FSD pages layer 구조에 두고, 루트 `app` 폴더의 각 라우트 파일은 해당 페이지 파일을 가져와 라우트에 연결합니다. + +프로젝트 루트에는 빈 `pages` 폴더도 함께 두어야 합니다. 그렇지 않으면 App Router를 사용하더라도 Next.js가 `src/pages`를 Pages Router로 인식하므로 빌드가 실패합니다. +또한 이 루트 `pages` 폴더가 왜 필요한지 설명하는 `README.md`를 함께 두는 것이 좋습니다. -프로젝트 루트에는 빈 `pages` 폴더도 함께 두어야 합니다. App Router를 쓰더라도 Next.js는 `src/pages`를 Pages Router로 사용하려 하므로 빌드가 실패합니다. 루트의 빈 `pages` 폴더가 이 동작을 막습니다. 폴더 안에는 왜 비어 있어야 하는지 설명하는 `README.md`를 두는 것이 좋습니다. - app App folder (Next.js) From 8c06f25be7c1a541e4bd2b43f78e3c614e522351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80?= Date: Thu, 23 Apr 2026 08:40:12 +0900 Subject: [PATCH 4/4] docs(kr): improve wording in Next.js App Router conflict section --- src/content/docs/kr/docs/guides/tech/with-nextjs.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx b/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx index e571d0a24..ee9ca38c7 100644 --- a/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx +++ b/src/content/docs/kr/docs/guides/tech/with-nextjs.mdx @@ -13,14 +13,14 @@ FSD는 Next.js의 App Router와 Pages Router 양쪽에 적용할 수 있습니 ### `app` layer에서 FSD와 Next.js의 충돌 \{#conflict-between-fsd-and-nextjs-in-the-app-layer\} -App Router에서는 `app` 폴더 구조가 그대로 라우트 구조로 사용됩니다. 반면 FSD에서 `app`은 애플리케이션 전역 구성을 담당하는 layer입니다. -두 구조에서 `app` 폴더가 담당하는 역할이 다르기 때문에 같은 위치에서 함께 사용할 수 없으며, 구조 충돌이 발생합니다. +App Router에서 `app` 폴더는 라우트 구조로 사용됩니다. 반면 FSD에서 `app` 폴더는 애플리케이션 전역을 담당하는 layer입니다. +두 구조는 `app` 폴더의 역할이 다르고, 같은 위치에 둘 경우 구조 충돌이 발생합니다. 이 충돌을 피하려면 Next.js의 `app` 폴더는 프로젝트 루트에 두고, 라우팅에 필요한 파일만 배치합니다. -페이지 파일은 `src` 하위의 FSD pages layer 구조에 두고, 루트 `app` 폴더의 각 라우트 파일은 해당 페이지 파일을 가져와 라우트에 연결합니다. +페이지는 `src` 하위의 FSD pages layer에 두고, 루트 `app` 폴더의 각 라우트 파일에서 이를 가져와 연결합니다. 프로젝트 루트에는 빈 `pages` 폴더도 함께 두어야 합니다. 그렇지 않으면 App Router를 사용하더라도 Next.js가 `src/pages`를 Pages Router로 인식하므로 빌드가 실패합니다. -또한 이 루트 `pages` 폴더가 왜 필요한지 설명하는 `README.md`를 함께 두는 것이 좋습니다. +또한 비어 있는 폴더이더라도 왜 필요한지 설명하는 `README.md`를 이 루트 `pages` 폴더 안에 함께 두는 것이 좋습니다.