Astro 구성

Astro는 프로젝트를 다양한 방식으로 구성할 수 있는 유연하고 독단적이지 않은 프레임워크입니다. 이는 새로운 프로젝트를 시작하는 것이 부담스럽게 느껴질 수 있다는 것을 의미합니다: Astro 프로젝트를 설정하는 “하나의 최선의 방법”은 없기 때문입니다!

이 “구성” 섹션의 가이드는 프로젝트와 개발 환경의 다양한 측면을 구성하고 사용자 정의할 수 있게 해주는 여러 파일들에 대해 익숙해지는 데 도움을 줄 것입니다.

만약 이것이 첫 Astro 프로젝트이거나, 새로운 프로젝트를 설정한 지 오래되었다면, 문서의 다음 가이드와 참조를 활용하세요.

Astro 구성 파일

Astro 구성 파일은 모든 스타터 프로젝트의 루트에 포함된 JavaScript 파일입니다:

유효한 Astro 구성 파일은 defineConfig 도우미를 사용하며, default export를 통해 구성을 내보냅니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  // 구성 옵션은 여기에 작성합니다.
});

구성할 것이 있는 경우에만 필요하지만, 대부분의 프로젝트는 이 파일을 사용합니다. defineConfig() 헬퍼는 IDE에서 자동 완성을 제공하며, Astro에게 프로젝트를 HTML로 빌드하고 렌더링하는 방법을 알려주는 모든 구성 옵션을 추가하는 곳입니다.

대부분의 경우 기본 파일 형식인 .mjs를 사용하거나, 구성 파일에서 TypeScript를 작성하고 싶다면 .ts를 사용하는 것을 권장합니다. 하지만 astro.config.js와 astro.config.cjs도 지원됩니다.

지원되는 모든 구성 옵션에 대한 전체 개요는 Astro의 구성 참조를 확인하세요.

TypeScript 구성 파일

모든 Astro 스타터 프로젝트에는 tsconfig.json 파일이 포함되어 있습니다. Astro의 컴포넌트 스크립트는 TypeScript이며, 이는 Astro의 편집기 도구를 제공하고 프로젝트 코드의 타입 체크를 위해 JavaScript에 선택적으로 구문을 추가할 수 있게 해줍니다.

tsconfig.json 파일을 사용하여 코드의 타입 체크를 수행할 TypeScript 템플릿을 구성하고, TypeScript 플러그인을 구성하며, 가져오기 별칭을 설정하는 등의 작업을 할 수 있습니다.

TypeScript 옵션과 Astro의 내장 유틸리티 타입에 대한 전체 개요는 Astro의 TypeScript 가이드를 참조하세요.

개발 경험

개발 모드로 작업하는 동안 코드 편집기와 다른 도구들을 활용하여 Astro 개발자 경험을 향상시킬 수 있습니다.

Astro는 자체 공식 VS Code 확장을 제공하며 다른 여러 인기 있는 편집기 도구와도 호환됩니다. 또한 Astro는 개발 서버가 실행되는 동안 브라우저 미리보기에 표시되는 사용자 지정 가능한 툴바를 제공합니다. 추가 기능을 위한 툴바 앱을 설치하고 직접 만들 수도 있습니다.

개발 경험을 사용자 지정하는 방법을 알아보려면 Astro의 편집기 설정 옵션 및 개발 툴바 사용 가이드를 참조하세요.

일반적인 새 프로젝트 작업

다음은 새로운 Astro 프로젝트에서 수행할 수 있는 첫 단계입니다.

배포 도메인 추가

사이트맵과 canonical URL을 생성하기 위해 site 옵션에서 배포 URL을 구성하세요. 경로에 배포하는 경우(예: www.example/docs) 프로젝트의 루트에 대한 base도 구성할 수 있습니다.

또한 다른 배포 호스트는 URL 끝의 후행 슬래시에 대해 다른 동작을 가질 수 있습니다(예: example.com/about vs example.com/about/). 사이트가 배포되면 trailingSlash 설정을 구성해야 할 수 있습니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://www.example.com',
  base: '/docs',
  trailingSlash: 'always',
});

사이트 메타데이터 추가

Astro는 구성 파일을 일반적인 SEO나 메타 데이터에 사용하지 않으며, 프로젝트 코드를 빌드하고 이를 HTML로 렌더링하는 데 필요한 정보에만 사용합니다.

대신, 이러한 정보는 일반 HTML 페이지를 작성하는 것처럼 HTML <link>와 <meta> 태그를 사용하여 페이지의 <head>에 추가됩니다.

Astro 사이트의 일반적인 패턴 중 하나는 모든 페이지에 적용할 수 있도록 공통 레이아웃 컴포넌트에 추가할 수 있는 <Head /> .astro 컴포넌트를 만드는 것입니다.

---
import Head from './Head.astro';
const { ...props } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <Head />
    <!-- -->
  </head>
  <body><!-- --></body>
</html>

Head.astro는 일반적인 Astro 컴포넌트이므로 파일을 가져오고 특정 페이지 제목과 같은 다른 컴포넌트로부터 전달된 props를 받을 수 있습니다.

---
import Favicon from '../assets/Favicon.astro';
import SomeOtherTags from './SomeOtherTags.astro';
const { title = 'My Astro Website', ...props } = Astro.props;
---
<link rel="sitemap" href="/sitemap-index.xml">
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">

<!-- 웹 애널리틱스 -->
<script data-goatcounter="https://my-account.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>

<!-- 오픈 그래프 태그 -->
<meta property="og:title" content="My New Astro Website" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://www.example.com/" />
<meta property="og:description" content="Welcome to my new Astro site!" />
<meta property="og:image" content="https://www.example.com/_astro/seo-banner.BZD7kegZ.webp">
<meta property="og:image:alt" content="">

<SomeOtherTags />

<Favicon />