Astro 설치 및 설정
create astro
CLI 명령은 새 Astro 프로젝트를 처음부터 시작하는 가장 빠른 방법입니다. 새로운 Astro 프로젝트를 설정하는 모든 단계를 안내하고 몇 가지 공식 시작 템플릿 중에서 선택할 수 있습니다.
또는 기존 테마나 시작 템플릿을 사용하여 프로젝트를 시작할 수도 있습니다.
대신 Astro를 수동으로 설치하려면 단계별 수동 설치 가이드를 참조하세요.
브라우저에서 Astro를 사용해보고 싶나요? 시작 템플릿을 탐색하기 위해 astro.new를 방문하여 브라우저를 떠나지 않고 새 Astro 프로젝트를 시작해 보세요.
전제 조건
섹션 제목: 전제 조건- Node.js -
v18.17.1
또는v20.3.0
이상. (v19
는 지원되지 않습니다.) - 텍스트 편집기 - 공식 Astro 확장이 포함된 VS Code를 권장합니다.
- 터미널 - Astro는 명령줄 인터페이스 (CLI)를 통해 액세스됩니다.
새 프로젝트 시작
섹션 제목: 새 프로젝트 시작CLI 마법사로 설치
섹션 제목: CLI 마법사로 설치-
편리한 설치 마법사를 시작하려면 터미널에서 다음 명령을 실행하세요.
컴퓨터의 어느 곳에서나
create astro
를 실행할 수 있으므로 시작하기 전에 프로젝트를 위한 새로운 빈 디렉터리를 만들 필요가 없습니다. 새 프로젝트를 위한 빈 디렉터리가 아직 없다면 마법사가 자동으로 디렉터리를 만드는 데 도움을 줍니다.모든 것이 순조롭게 진행되면 성공 메시지와 함께 권장되는 다음 단계가 표시됩니다. 이제 프로젝트가 생성되었으므로 새 프로젝트 디렉터리에
cd
하여 Astro를 시작할 수 있습니다. -
CLI 마법사를 실행하는 중
npm install
단계를 건너뛴 경우 계속 진행하기 전에 종속성을 설치해야 합니다. -
이제 Astro 개발 서버를 시작하여 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!
테마 또는 시작 템플릿 사용
섹션 제목: 테마 또는 시작 템플릿 사용또한 create astro
명령에 --template
인수를 전달하여 공식 예시 또는 GitHub 저장소의 main
브랜치를 기반으로 새 Astro 프로젝트를 시작할 수도 있습니다.
-
블로그, 포트폴리오, 문서 사이트, 랜딩 페이지 등 다양한 테마를 찾아볼 수 있는 테마 및 스타터 쇼케이스를 살펴보세요! 또는 더 많은 시작 프로젝트를 찾기 위해 GitHub에서 검색하세요.
-
공식 Astro 스타터 템플릿의 이름이나 사용하려는 테마의 GitHub 사용자 이름 및 저장소로 입력을 대체하여 터미널에서 다음 명령을 실행합니다.
기본적으로 이 명령은 템플릿 저장소의
main
브랜치를 사용합니다. 다른 브랜치 이름을 사용하려면--template
인수의 일부로<github-username>/<github-repo>#<branch>
를 전달하세요. -
질문에 답하여 CLI 마법사의 지시를 따릅니다.
-
이제 Astro 개발 서버를 시작하여 프로젝트를 직접 만드는 동안 실시간 미리보기를 볼 수 있습니다!
프로젝트 편집
섹션 제목: 프로젝트 편집프로젝트를 변경하려면 코드 편집기에서 프로젝트 폴더를 엽니다. 개발 서버가 실행 중인 상태에서 개발 모드로 작업하면 코드를 편집하면서 사이트 업데이트를 확인할 수 있습니다.
TypeScript 구성이나 공식 Astro 편집기 확장 설치 등 개발 환경 측면을 사용자 정의할 수도 있습니다.
Astro 개발 서버 시작
섹션 제목: Astro 개발 서버 시작Astro에는 프로젝트 개발에 필요한 모든 것을 갖춘 개발 서버가 내장되어 있습니다. astro dev
CLI 명령은 로컬 개발 서버를 시작하여 처음으로 새 웹사이트가 작동하는 모습을 볼 수 있습니다.
모든 시작 템플릿에는 astro dev
를 실행할 사전 구성된 스크립트가 함께 제공됩니다. 프로젝트 디렉터리로 이동한 후 선호하는 패키지 관리자를 통해 이 명령을 실행하여 Astro 개발 서버를 시작하세요.
모든 것이 순조롭게 진행되었다면 Astro는 이제 http://localhost:4321/에서 프로젝트를 서비스하게 될 것입니다. 브라우저에서 해당 링크를 방문하여 새 사이트를 확인하세요!
개발 모드에서 작업
섹션 제목: 개발 모드에서 작업Astro는 src/
디렉터리에서 실시간 파일 변경 사항을 수신하고 빌드할 때 사이트 미리보기를 업데이트하므로 개발 중 변경 사항을 적용할 때 서버를 다시 시작할 필요가 없습니다. 개발 서버가 실행 중일 때 항상 브라우저에서 사이트의 최신 버전을 볼 수 있습니다.
브라우저에서 사이트를 보면 Astro 개발 툴바에 액세스할 수 있습니다. 빌드하면서 아일랜드를 검사하고 접근성 문제 등을 발견하는 데 도움이 됩니다.
개발 서버를 시작한 후 브라우저에서 프로젝트를 열 수 없는 경우 dev
명령을 실행한 터미널로 돌아가서 표시된 메시지를 확인하세요. 오류가 발생했는지 또는 프로젝트가 http://localhost:4321/이 아닌 다른 URL에서 제공되는지 알려줍니다.
개발 환경 구성
섹션 제목: 개발 환경 구성아래 가이드를 살펴보고 개발 환경을 맞춤설정하세요.
Astro에서 TypeScript 사용
섹션 제목: Astro에서 TypeScript 사용Astro에는 코드에서 객체 및 컴포넌트의 모양을 정의하여 런타임 오류를 방지하는 데 도움이 되는 TypeScript 지원이 내장되어 있습니다.
이점을 누리기 위해 Astro 프로젝트에서 TypeScript 코드를 작성할 필요는 없습니다. Astro는 항상 컴포넌트 코드를 TypeScript로 처리하며 Astro VSCode 확장은 편집기에서 자동 완성, 힌트 및 오류를 제공하기 위해 최대한 많이 추론합니다.
사이트 빌드 및 미리보기
섹션 제목: 사이트 빌드 및 미리보기빌드 시 생성될 사이트 버전을 확인하려면 개발 서버를 종료하고 (Ctrl + C) 터미널에서 패키지 관리자에 적합한 빌드 명령을 실행하세요.
Astro는 배포 가능한 버전의 사이트를 별도의 폴더 (기본적으로 dist/
)에 빌드하고 터미널에 진행 상황을 표시합니다. 이렇게 하면 프로덕션에 배포하기 전에 프로젝트의 빌드 오류를 확인할 수 있습니다. TypeScript가 strict
또는 strictest
로 구성된 경우 build
스크립트는 프로젝트의 타입 오류도 확인합니다.
빌드가 완료되면 터미널에서 적절한 preview
명령 (예: npm run preview
)을 실행하세요. 동일한 브라우저 미리보기 창에서 로컬로 사이트의 빌드된 버전을 볼 수 있습니다.
이렇게 하면 빌드 명령이 마지막으로 실행되었을 때 존재했던 코드를 미리 볼 수 있습니다. 이는 사이트가 웹에 배포되었을 때 어떻게 보일지 미리 보여주기 위한 것입니다. 빌드 후 코드를 변경하더라도 빌드 명령을 다시 실행하기 전까지 사이트의 미리 보기에는 해당 변경 사항이 반영되지 않습니다.
(Ctrl + C)를 사용하여 미리보기를 종료하고 다른 터미널 명령을 실행하세요. 예를 들어 코드 변경 사항을 실시간으로 확인하기 위해 개발 서버를 다시 시작하여 편집할 때 업데이트되는 개발 모드 작업으로 돌아갑니다.
새 사이트 배포
섹션 제목: 새 사이트 배포너무 많은 코드를 추가하거나 변경하기 전에 새 사이트를 즉시 배포하는 것이 좋습니다. 이는 사이트의 최소한의 작동 버전을 게시하는 데 도움이 되며 나중에 배포 문제를 해결하는 데 투입되는 시간과 노력을 절약할 수 있습니다.
다음 단계
섹션 제목: 다음 단계성공! 이제 Astro로 빌드를 시작할 준비가 되었습니다! 🥳
앞으로 살펴보실 것을 권장하는 몇 가지 사항은 다음과 같습니다. 어떤 순서로든 읽을 수 있습니다. 문서를 잠시 남겨두고 새 Astro 프로젝트 코드베이스를 사용해 보고 문제가 발생하거나 질문이 있을 때마다 여기로 돌아올 수도 있습니다.
Astro의 기능 살펴보기
섹션 제목: Astro의 기능 살펴보기입문용 튜토리얼
섹션 제목: 입문용 튜토리얼입문용 튜토리얼을 통해 하나의 빈 페이지에서 시작하여 완전한 기능을 갖춘 Astro 블로그를 구축하세요.
이는 Astro의 작동 방식 및 페이지, 레이아웃, 컴포넌트, 라우팅, 아일랜드 등 기본 사항을 직접 살펴볼 수 있는 좋은 방법입니다. 또한 일반적으로 웹 개발 개념을 처음 접하는 사람들을 위한 선택적이고 초보자 친화적인 유닛도 포함되어 있습니다. 이 유닛은 컴퓨터에 필수 응용 프로그램을 설치하고, GitHub 계정을 만들고, 사이트를 배포하는 과정을 안내합니다.
수동 설정
섹션 제목: 수동 설정이 가이드는 새로운 Astro 프로젝트를 수동으로 설치하고 구성하는 단계를 안내합니다.
자동 create astro
CLI 도구를 사용하지 않으려면 아래 가이드에 따라 프로젝트를 직접 설정할 수 있습니다.
-
디렉터리 만들기
프로젝트 이름으로 빈 디렉터리를 만든 다음 해당 디렉터리로 이동합니다.
새 디렉터리에 있으면 프로젝트
package.json
파일을 만듭니다. 이것이 Astro를 포함한 프로젝트 종속성을 관리하는 방법입니다. 이 파일 형식에 익숙하지 않은 경우 다음 명령을 실행하여 파일 형식을 만드세요. -
Astro 설치
먼저 프로젝트에 Astro 프로젝트 종속성을 설치하세요.
Astro는 전역이 아닌 로컬에 설치해야 합니다.
npm install -g astro
pnpm add -g astro
또는yarn add global astro
를 실행하지 않았는지 확인하세요.그런 다음
package.json
의 자리 표시자 “scripts” 섹션을 다음으로 바꿉니다.이 스크립트는 나중에 Astro를 시작하고 다양한 명령을 실행하기 위해 가이드에서 사용할 것입니다.
-
첫 번째 페이지 만들기
텍스트 편집기에서
src/pages/index.astro
파일을 만듭니다. 이 파일이 프로젝트의 첫 번째 Astro 페이지가 될 것입니다.이 가이드에서는 다음 코드 조각 (
---
대시 포함)을 복사하여 새 파일에 붙여넣습니다. -
첫 번째 정적 자산 만들기
또한 정적 자산을 저장하기 위해
public/
디렉터리를 생성할 수도 있습니다. Astro는 항상 최종 빌드에 이러한 자산을 포함하므로 컴포넌트 템플릿에서 안전하게 참조할 수 있습니다.텍스트 편집기에서
public/robots.txt
파일을 만듭니다.robots.txt
는 Google과 같은 검색 봇에게 사이트 처리 방법을 알려주기 위해 대부분의 사이트에 포함되는 간단한 파일입니다.이 가이드에서는 다음 코드 조각을 복사하여 새 파일에 붙여넣습니다.
-
astro.config.mjs
생성Astro는
astro.config.mjs
를 사용하여 구성됩니다. Astro를 구성할 필요가 없다면 이 파일은 선택 사항이지만 지금 생성하고 싶을 수도 있습니다.프로젝트 루트에
astro.config.mjs
를 만들고 아래 코드를 복사하세요.프로젝트에 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
를 사용할 수 있습니다)마지막으로
src/env.d.ts
를 생성하여 Astro 프로젝트에서 사용할 수 있는 앰비언트 타입을 TypeScript에 알립니다.자세한 내용은 Astro의 TypeScript 설정 가이드를 확인하세요.
-
다음 단계
위 단계를 수행했다면 이제 프로젝트 디렉터리는 다음과 같아야 합니다.
디렉터리node_modules/
- …
디렉터리public/
- robots.txt
디렉터리src/
디렉터리pages/
- index.astro
- env.d.ts
- astro.config.mjs
- package-lock.json 또는
yarn.lock
,pnpm-lock.yaml
등 - package.json
- tsconfig.json
-
이제 Astro 개발 서버를 시작하여 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!