Astro 설치

create astro CLI 명령어는 처음부터 새로운 Astro 프로젝트를 시작하는 가장 빠른 방법입니다. 이 명령어는 새로운 Astro 프로젝트 설정의 모든 단계를 안내하고 몇 가지 공식 스타터 템플릿 중에서 선택할 수 있게 해줍니다.

CLI 명령어를 template 플래그와 함께 실행하여 기존의 테마나 스타터 템플릿을 사용해 프로젝트를 시작할 수도 있습니다. 블로그, 포트폴리오, 문서 사이트, 랜딩 페이지 등을 위한 테마를 살펴볼 수 있는 테마 및 스타터 쇼케이스를 둘러보세요!

대신 Astro를 수동으로 설치하려면 단계별 수동 설치 가이드를 참조하세요.

전제 조건

Node.js - v18.17.1 또는 v20.3.0, v22.0.0 또는 그 이상. ( v19 및 v21은 지원되지 않습니다.)
텍스트 편집기 - VS Code 및 공식 Astro 확장를 사용하는 것을 권장합니다.
터미널 - Astro는 명령줄 인터페이스(CLI)를 통해 접근됩니다.

브라우저 호환성

Astro는 Vite를 기반으로 구축되어 있으며, 기본적으로 현대적인 JavaScript를 지원하는 브라우저를 대상으로 합니다. 전체 참조를 위해서는 Vite에서 현재 지원되는 브라우저 버전 목록을 확인할 수 있습니다.

CLI 마법사를 통한 설치

프로젝트를 위한 빈 디렉터리를 생성할 필요 없이 시스템의 어느 곳에서나 create astro를 실행할 수 있습니다. 새 프로젝트를 위한 빈 디렉터리가 아직 없다면, 마법사가 자동으로 생성하도록 도와드립니다.

설치 마법사를 시작하려면 터미널에서 다음 명령어를 실행하세요:
- npm
- pnpm
- Yarn
터미널 창
# npm으로 새 프로젝트 시작 npm create astro@latest
터미널 창
# pnpm으로 새 프로젝트 시작 pnpm create astro@latest
터미널 창
# yarn으로 새 프로젝트 시작 yarn create astro
모든 것이 잘 진행되면, 성공 메시지와 함께 권장되는 다음 단계들이 표시될 것입니다.
이제 프로젝트가 생성되었으므로, Astro를 사용하기 위해 새로운 프로젝트 디렉터리로 cd 명령어를 통해 이동할 수 있습니다.
CLI 마법사 실행 중 “Install dependencies?” 단계를 건너뛰었다면, 계속 진행하기 전에 반드시 의존성을 설치하세요.
- npm
- pnpm
- Yarn
터미널 창
npm install
터미널 창
pnpm install
터미널 창
yarn install
이제 Astro 개발 서버를 시작하고 프로젝트를 만드는 동안 실시간 미리보기를 확인할 수 있습니다!

CLI 설치 플래그

create astro 명령어를 추가 플래그와 함께 실행하여 설정 과정(예: 모든 질문에 “yes”로 답하기, Houston 애니메이션 건너뛰기)이나 새 프로젝트(예: git 설치 여부, 통합 추가)를 사용자 정의할 수 있습니다.

사용 가능한 모든 create astro 명령어 플래그 보기

통합 추가

create astro 명령어에 --add 인자를 전달하여 새로운 astro 프로젝트를 시작하고 astro add 명령어를 지원하는 공식 통합 또는 커뮤니티 통합을 동시에 설치할 수 있습니다.

터미널에서 다음 명령어를 실행하고, astro add 명령어를 지원하는 통합으로 대체하세요:

# react와 tailwind를 포함한 새 프로젝트 생성
npm create astro@latest -- --add react --add tailwind

# react와 tailwind를 포함한 새 프로젝트 생성
pnpm create astro@latest --add react --add tailwind

# react와 tailwind를 포함한 새 프로젝트 생성
yarn create astro --add react --add tailwind

테마나 스타터 템플릿 사용하기

create astro 명령어에 --template 인자를 전달하여 공식 예제 또는 GitHub 저장소의 main 브랜치를 기반으로 새로운 astro 프로젝트를 시작할 수 있습니다.

터미널에서 다음 명령어를 실행하고, 공식 Astro 스타터 템플릿 이름이나 사용하고자 하는 테마의 GitHub 사용자 이름과 저장소로 대체하세요:

# 공식 예제를 사용한 새 프로젝트 생성하기
npm create astro@latest -- --template <example-name>

# GitHub 저장소의 main 브랜치를 기반으로 새 프로젝트 생성하기
npm create astro@latest -- --template <github-username>/<github-repo>

# 공식 예제를 사용한 새 프로젝트 생성하기
pnpm create astro@latest --template <example-name>

# GitHub 저장소의 main 브랜치를 기반으로 새 프로젝트 생성하기
pnpm create astro@latest --template <github-username>/<github-repo>

# 공식 예제를 사용한 새 프로젝트 생성하기
yarn create astro --template <example-name>

# GitHub 저장소의 main 브랜치를 기반으로 새 프로젝트 생성하기
yarn create astro --template <github-username>/<github-repo>

기본적으로 이 명령어는 템플릿 저장소의 main 브랜치를 사용합니다. 다른 브랜치 이름을 사용하려면 --template 인자의 일부로 전달하세요: <github-username>/<github-repo>#<branch>.

수동 설정

이 가이드는 Astro 프로젝트를 수동으로 설치하고 구성하는 단계를 안내합니다.

자동 create astro CLI 도구를 사용하지 않으려면, 아래 가이드를 따라 직접 프로젝트를 설정할 수 있습니다.

디렉터리를 생성합니다.

프로젝트의 이름으로 빈 디렉터리를 생성한 다음, 해당 디렉터리로 이동하세요.
터미널 창
```
mkdir my-astro-project
cd my-astro-project
```
새로운 디렉터리로 이동한 후에는 프로젝트의 package.json 파일을 생성하세요. 이는 Astro를 포함한 프로젝트 의존성을 관리하는 방법입니다. 이 파일 형식에 익숙하지 않다면, 다음 명령어를 실행하여 생성하세요.
- npm
- pnpm
- Yarn
터미널 창
npm init --yes
터미널 창
pnpm init
터미널 창
yarn init --yes
Astro 설치

먼저, 프로젝트에 Astro 프로젝트 의존성을 설치하세요.

Astro는 전역이 아닌 로컬에 설치되어야 합니다. npm install -g astro, pnpm add -g astro 또는 yarn add global astro를 실행하지 않도록 하세요.
- npm
- pnpm
- Yarn
터미널 창
npm install astro
터미널 창
pnpm add astro
터미널 창
yarn add astro
그런 다음, package.json의 임시 “scripts” 섹션을 다음과 같이 교체하세요:
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
이 스크립트들은 이후 가이드에서 Astro를 시작하고 여러 명령어를 실행하는 데 사용됩니다.

첫 페이지를 생성합니다.

텍스트 편집기에서 디렉터리의 src/pages/index.astro에 새 파일을 생성하세요. 이것이 프로젝트의 첫 번째 Astro 페이지가 될 것입니다.

이 가이드에서는 다음 코드 스니펫을 (--- 대시 포함) 새로운 파일에 복사하여 붙여넣으세요:

---
// Astro에 오신 것을 환영합니다! 이 삼중 대시 코드 펜스 사이의 모든 것은
// "컴포넌트 프런트매터"입니다. 이것은 브라우저에서 실행되지 않습니다.
console.log('This runs in your terminal, not the browser!');
---
<!-- 아래는 "컴포넌트 템플릿"입니다. HTML이지만,
  훌륭한 템플릿을 만드는데 도움이 되는 몇 가지 마법이 뿌려져 있습니다. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

첫 번째 정적 자산을 생성합니다.

정적 자산을 저장하기 위해 public/ 디렉터리를 생성해야 합니다. Astro는 최종 빌드에 이러한 자산들을 항상 포함시키므로, 컴포넌트 템플릿에서 안전하게 참조할 수 있습니다.

텍스트 편집기에서 디렉터리의 public/robots.txt에 새 파일을 생성하세요. robots.txt는 대부분의 사이트가 Google과 같은 검색 봇에게 사이트를 어떻게 처리해야 하는지 알려주기 위해 포함하는 간단한 파일입니다.

이 가이드에서는 다음 코드 스니펫을 새로운 파일에 복사하여 붙여넣으세요:
public/robots.txt
```
# 예시: 모든 봇이 사이트를 스캔하고 색인할 수 있도록 허용
# 전체 구문: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
astro.config.mjs를 생성합니다.

Astro는 astro.config.mjs를 사용하여 구성됩니다. Astro를 구성할 필요가 없다면 이 파일은 선택사항이지만, 지금 생성해두는 것이 좋을 수 있습니다.

프로젝트의 루트에 astro.config.mjs를 생성하고, 아래 코드를 복사하여 붙여넣으세요:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
React, Svelte 등과 같은 UI 프레임워크 컴포넌트를 포함하거나 프로젝트에서 Tailwind 또는 Partytown과 같은 다른 도구를 사용하려면, 이곳에서 통합을 수동으로 가져와 구성하면 됩니다.

더 자세한 내용은 Astro의 API 구성 참조를 참고하세요.
TypeScript 지원 추가

TypeScript는 tsconfig.json을 사용하여 구성됩니다. TypeScript 코드를 작성하지 않더라도, 이 파일은 Astro와 VS Code와 같은 도구가 프로젝트를 이해하는 방법을 알 수 있게 해주므로 중요합니다. npm 패키지 가져오기와 같은 일부 기능은 tsconfig.json 파일이 없으면 편집기에서 전혀 지원되지 않습니다.

TypeScript 코드를 작성할 계획이 있다면, Astro의 strict 또는 strictest 템플릿을 사용하는 것이 권장됩니다. astro/tsconfigs/에서 세 가지 템플릿 구성을 보고 비교할 수 있습니다.

프로젝트의 루트에 tsconfig.json을 생성하고, 아래 코드를 복사하여 붙여넣으세요. (TypeScript 템플릿으로 base, strict, 또는 strictest를 사용할 수 있습니다):
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
Astro의 TypeScript 설정 가이드에서 더 자세한 내용을 참고하세요.
다음 단계

위의 단계들을 따랐다면, 프로젝트 디렉터리는 이제 다음과 같이 보일 것입니다:
- 디렉터리node_modules/
  - …
- 디렉터리public/
  - robots.txt
- 디렉터리src/
  - 디렉터리pages/
    index.astro
- astro.config.mjs
- package-lock.json 또는 yarn.lock, pnpm-lock.yaml, 등
- package.json
- tsconfig.json
이제 Astro 개발 서버를 시작하고 프로젝트를 만드는 동안 실시간 미리보기를 확인할 수 있습니다!

기여하기

커뮤니티