프로젝트 구조

create astro CLI 마법사로 생성된 새 Astro 프로젝트에는 이미 일부 파일과 폴더가 포함되어 있습니다. 다른 파일들은 사용자가 직접 만들어 Astro의 기존 파일 구조에 추가해야 합니다.

Astro 프로젝트의 구성 방식과 새 프로젝트에서 찾을 수 있는 몇 가지 파일은 다음과 같습니다.

디렉터리 및 파일

Astro는 프로젝트에 대해 의견이 담긴 폴더 레이아웃을 활용합니다. 모든 Astro 프로젝트 루트에는 다음 디렉터리와 파일이 포함되어야 합니다.

src/* - 프로젝트 소스 코드 (컴포넌트, 페이지, 스타일, 이미지 등)
public/* - 코드 외 처리되지 않는 자산 (글꼴, 아이콘 등)
package.json - 프로젝트 매니페스트
astro.config.mjs - Astro 구성 파일 (권장)
tsconfig.json - TypeScript 구성 파일 (권장)

프로젝트 트리 예시

일반적인 Astro 프로젝트 디렉터리는 다음과 같습니다.

디렉터리public/
- robots.txt
- favicon.svg
- my-cv.pdf
디렉터리src/
- 디렉터리blog/
  - post1.md
  - post2.md
  - post3.md
- 디렉터리components/
  - Header.astro
  - Button.jsx
- 디렉터리images/
  - image1.jpg
  - image2.jpg
  - image3.jpg
- 디렉터리layouts/
  - PostLayout.astro
- 디렉터리pages/
  - 디렉터리posts/
    [post].astro
  - about.astro
  - index.astro
  - rss.xml.js
- 디렉터리styles/
  - global.css
- content.config.ts
astro.config.mjs
package.json
tsconfig.json

`src/`

src/ 폴더는 대부분의 프로젝트 소스 코드가 위치하는 곳입니다. 여기에는 다음이 포함됩니다.

Astro는 src/ 파일을 처리, 최적화 및 번들링하여 브라우저로 전송되는 최종 웹사이트를 만듭니다. 정적인 public/ 디렉터리와 달리 src/ 파일은 Astro에 의해 빌드되고 처리됩니다.

일부 파일 (예: Astro 컴포넌트)은 작성된 그대로 브라우저로 전송되지 않고 대신 정적 HTML로 렌더링됩니다. 다른 파일 (예: CSS)은 브라우저로 전송되지만 성능을 위해 최적화되거나 다른 CSS 파일과 함께 번들링될 수 있습니다.

`src/pages`

사이트의 페이지 경로는 이 디렉터리에 지원되는 파일 형식을 추가하여 생성됩니다.

`src/components`

컴포넌트는 HTML 페이지를 위한 재사용 가능한 코드 단위입니다. Astro 컴포넌트 또는 React나 Vue와 같은 UI 프레임워크 컴포넌트일 수 있습니다. 이 폴더에 모든 프로젝트 컴포넌트를 함께 그룹화하고 정리하는 것이 일반적입니다.

Astro 프로젝트에서 흔히 사용되는 규칙이지만 필수는 아닙니다. 원하는 방식으로 컴포넌트를 구성해도 괜찮습니다!

`src/layouts`

레이아웃은 하나 이상의 페이지에서 공유하는 UI 구조를 정의하는 Astro 컴포넌트입니다.

src/components와 마찬가지로 이 디렉터리 역시 일반적인 규칙이지만 필수는 아닙니다.

`src/styles`

src/styles 디렉터리에 CSS 또는 Sass 파일을 저장하는 것이 일반적인 규칙이지만 필수는 아닙니다. 스타일이 src/ 디렉터리 어딘가에 있고 올바르게 가져오기만 하면 Astro에서 처리하고 최적화합니다.

`public/`

public/ 디렉터리는 Astro 빌드 과정 중에 처리할 필요가 없는 프로젝트의 파일과 자산을 위한 곳입니다. 이 폴더의 파일은 변경 없이 빌드 폴더로 복사된 후 사이트가 빌드됩니다.

이러한 동작으로 인해 public/은 일부 이미지와 글꼴, 또는 robots.txt 및 manifest.webmanifest와 같은 특수 파일과 같이 처리할 필요가 없는 일반적인 자산에 이상적입니다.

public/ 디렉터리에 CSS와 JavaScript를 배치할 수 있지만, 해당 파일은 최종 빌드에서 번들링되거나 최적화되지 않습니다.

`package.json`

JavaScript 패키지 관리자가 의존성을 관리하는 데 사용하는 파일입니다. 또한 Astro를 실행하는 데 일반적으로 사용되는 스크립트 (예: npm run dev, npm run build)를 정의합니다.

package.json에는 지정할 수 있는 두 가지 종류의 의존성이 있습니다. dependencies와 devDependencies가 그것입니다. 대부분의 경우 이들은 동일하게 작동합니다. Astro는 빌드 시 모든 의존성이 필요하며 패키지 관리자는 둘 다 설치합니다. 처음에는 모든 의존성을 dependencies에 넣고 특정 요구 사항이 있는 경우에만 devDependencies를 사용하는 것이 좋습니다.

프로젝트에 대한 새 package.json 파일을 만드는 데 도움이 필요하면 수동 설정 지침을 확인하세요.

`astro.config.mjs`

이 파일은 모든 스타터 템플릿에서 생성되며 Astro 프로젝트의 구성 옵션을 포함합니다. 여기서 사용할 통합, 빌드 옵션, 서버 옵션 등을 지정할 수 있습니다.

Astro는 JavaScript 구성 파일에 대해 astro.config.js, astro.config.mjs, astro.config.cjs, astro.config.ts 등 여러 파일 형식을 지원합니다. 대부분의 경우 .mjs를 사용하고 구성 파일에서 TypeScript를 작성하려면 .ts를 사용하는 것이 좋습니다.

TypeScript 구성 파일 로딩은 tsm을 사용하여 처리되며 프로젝트의 tsconfig 옵션을 따릅니다.

자세한 내용은 구성 참조를 확인하세요.

`tsconfig.json`

이 파일은 모든 스타터 템플릿에서 생성되며 Astro 프로젝트의 TypeScript 구성 옵션을 포함합니다. 일부 기능 (예: npm 패키지 가져오기)은 tsconfig.json 파일 없이는 편집기에서 완전히 지원되지 않습니다.

자세한 구성 설정 방법은 TypeScript 가이드를 참조하세요.

기여하기 커뮤니티 후원하기