컨텐츠로 건너뛰기

Astro를 수동으로 설치하기

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

요구 사항

섹션 제목: 요구 사항
  • Node.js - v18.17.1 또는 v20.3.0 또는 상위 버전. ( v19는 지원되지 않음.)
  • 텍스트 편집기 - VS Code와 공식 Astro 확장 프로그램을 함께 사용하는 것이 권장됩니다.
  • 터미널 - Astro를 제어할 명령줄 인터페이스(CLI)가 필요합니다.

설치

섹션 제목: 설치

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

1. 디렉터리 생성

섹션 제목: 1. 디렉터리 생성

프로젝트 이름으로 빈 디렉터리를 생성한 후, 해당 디렉터리로 이동합니다.

Terminal window
mkdir my-astro-project
cd my-astro-project

새 디렉터리에 package.json 파일을 생성합니다. 이 파일을 통해 Astro를 포함한 프로젝트 종속성을 관리하게 될 것입니다. 이 파일의 형식에 익숙하지 않은 경우, 다음 명령을 통해 파일을 생성하세요.

Terminal window
npm init --yes

2. Astro 설치

섹션 제목: 2. Astro 설치

먼저, 프로젝트에 Astro 패키지를 설치하세요.

Terminal window
npm install astro

그리고 package.json 파일의 “scripts” 섹션의 값을 다음과 같이 변경합니다.

package.json
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },

나중에 이 스크립트는 Astro를 시작하고 다양한 명령을 실행하는 데 사용됩니다.

3. 첫 페이지 생성

섹션 제목: 3. 첫 페이지 생성

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

이 가이드에서는 다음 코드(대시 --- 포함)를 복사하여 사용하세요.

src/pages/index.astro
---
// Astro에 오신 것을 환영합니다! 코드 펜스(삼중 대시로 구별됨) 사이에 있는 모든 것은
// "컴포넌트의 frontmatter"이며, 브라우저에서는 실행되지 않습니다.
console.log('터미널에서 실행되며, 브라우저에서는 실행되지 않습니다!');
---
<!-- 아래 코드는 "컴포넌트 템플릿"입니다.
     훌륭한 템플릿을 구축하기 위한 몇 가지 마법이 추가된 HTML입니다. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

4. 첫 번째 정적 자산 만들기

섹션 제목: 4. 첫 번째 정적 자산 만들기

또한, 정적 자산을 저장하기 위해 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: /

5. astro.config.mjs 생성

섹션 제목: 5. 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 구성 참조를 확인하세요.

6. TypeScript 지원 추가

섹션 제목: 6. 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"
}

마지막으로, src/env.d.ts를 생성하여 TypeScript가 Astro 프로젝트에서 사용할 수 있는 타입을 알 수 있도록 합니다.

src/env.d.ts
/// <reference types="astro/client" />
자세한 내용은 TypeScript 설정 가이드를 참조하세요.

7. 다음 단계

섹션 제목: 7. 다음 단계

위 단계를 모두 수행했다면 프로젝트의 디렉터리는 다음과 같은 형태가 됩니다.

  • 디렉터리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를 사용할 준비가 되었습니다!

이 가이드를 완전히 따랐다면 2단계: Astro 시작하기로 이동하여 Astro를 실행하는 방법에 대해 알아보세요.