가져오기

Astro는 구성이 필요하지 않은 대부분의 정적 자산을 지원합니다. 프로젝트 JavaScript (Astro 프런트매터 포함) 어디에서나 import 문을 사용할 수 있으며, Astro는 최종 빌드에 해당 정적 자산의 빌드되고 최적화된 복사본을 포함합니다. @import는 CSS 및 <style> 태그에서도 지원됩니다.

지원되는 파일 형식

섹션 제목: 지원되는 파일 형식

Astro에서는 기본적으로 다음 파일 형식을 지원합니다.

• Astro 컴포넌트 (.astro)
• Markdown (.md, .markdown 등)
• JavaScript (.js, .mjs)
• TypeScript (.ts, .tsx)
• NPM 패키지
• JSON (.json)
• JSX (.jsx, .tsx)
• CSS (.css)
• CSS 모듈 (.module.css)
• 이미지 및 자산 (.svg, .jpg, .png 등)

또한 Astro를 확장하여 React, Svelte, Vue 컴포넌트와 같은 다양한 UI 프레임워크에 대한 지원을 추가할 수 있습니다. Astro MDX 통합을 설치하고 프로젝트에서 .mdx 파일을 사용할 수도 있습니다.

public/ 디렉터리 내 파일

섹션 제목: public/ 디렉터리 내 파일

프로젝트의 public/ 디렉터리에 정적 자산을 배치할 수 있으며 Astro는 이를 그대로 최종 빌드에 직접 복사합니다. public/ 파일은 Astro에서 빌드되거나 번들로 제공되지 않습니다. 즉, 모든 유형의 파일이 지원된다는 의미입니다. HTML 템플릿에서 직접 URL 경로로 public/ 파일을 참조할 수 있습니다.

Import 구문

섹션 제목: Import 구문

Astro는 브라우저에서 지원되는 것과 동일한 import 및 export 구문인 ESM을 사용합니다.

JavaScript

섹션 제목: JavaScript

import { getUser } from './user.js';

JavaScript는 일반적인 ESM import & export 구문을 사용하여 가져올 수 있습니다.

TypeScript

섹션 제목: TypeScript

import { getUser } from './user';
import type { UserType } from './user';

Astro에는 TypeScript에 대한 지원이 내장되어 있습니다. Astro 프로젝트에서 직접 .ts 및 .tsx 파일을 가져올 수 있으며. Astro 컴포넌트 스크립트 및 호이스팅된 스크립트 태그에 TypeScript 코드를 직접 작성할 수도 있습니다.

Astro는 자체적으로 어떠한 타입 검사도 수행하지 않습니다. 타입 검사는 Astro 외부에서 IDE나 별도의 스크립트를 통해 처리해야 합니다. Astro 파일의 타입 검사를 위해 astro check 명령이 제공됩니다.

TypeScript 및 파일 확장자

TypeScript의 모듈 확인 규칙에 따라 TypeScript 파일을 가져올 때 .ts 및 .tsx 파일 확장자를 사용하면 안 됩니다. 대신 .js/.jsx 파일 확장자를 사용하거나 파일 확장자를 완전히 생략하세요.

import { getUser } from './user.js'; // user.ts
import MyComponent from './MyComponent'; // MyComponent.tsx

Astro의 TypeScript 지원에 대해 자세히 알아보세요.

JSX / TSX

섹션 제목: JSX / TSX

import { MyComponent } from './MyComponent.jsx';

Astro에는 JSX (*.jsx 및 *.tsx) 파일에 대한 지원이 내장되어 있습니다. JSX 구문은 자동으로 JavaScript로 변환됩니다.

Astro는 기본적으로 JSX 구문을 이해하지만 React, Preact, Solid와 같은 프레임워크를 적절하게 렌더링하려면 프레임워크 통합을 포함해야 합니다. 자세한 내용은 통합 사용 안내서를 확인하세요.

노트

Astro는 .js/.ts 파일에서 JSX를 지원하지 않습니다. JSX는 .jsx 및 .tsx 파일 확장자로 끝나는 파일에서만 처리됩니다.

NPM 패키지

섹션 제목: NPM 패키지

NPM 패키지를 설치한 경우 Astro로 가져올 수 있습니다.

---
import { Icon } from 'astro-icon';
---

패키지가 레거시 형식을 사용하여 게시된 경우 Astro는 import 문이 작동하도록 패키지를 ESM으로 변환하려고 시도합니다. 어떤 경우에는 vite 구성을 조정해야 작동할 수도 있습니다.

주의

일부 패키지는 브라우저 환경에 의존합니다. Astro 컴포넌트는 서버에서 실행되므로 프런트매터에서 이러한 패키지를 가져오면 오류가 발생할 수 있습니다.

JSON

섹션 제목: JSON

// 기본 내보내기를 통해 JSON 객체 불러오기
import json from './data.json';

Astro는 JSON 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 파일은 기본 가져오기에서 전체 JSON 객체를 반환합니다.

CSS

섹션 제목: CSS

// 페이지에 'style.css' 불러오기 및 삽입
import './style.css';

Astro는 CSS 파일을 애플리케이션으로 직접 가져오는 것을 지원합니다. 가져온 스타일은 내보내기를 노출하지 않지만 스타일을 가져오면 해당 스타일이 페이지에 자동으로 추가됩니다. 이는 기본적으로 모든 CSS 파일에 대해 작동하며 플러그인을 통해 Sass & Less와 같은 CSS로 컴파일 언어를 지원할 수 있습니다.

CSS 모듈

섹션 제목: CSS 모듈

// 1. './style.module.css' 클래스 이름을 고유한 범위 값으로 변환합니다.
// 2. 원래 클래스 이름을 최종 범위 값에 매핑하는 객체를 반환합니다.
import styles from './style.module.css';

// 이 예시에서는 JSX를 사용하지만 모든 프레임워크에서 CSS 모듈을 사용할 수 있습니다.
return <div className={styles.error}>에러 메시지</div>;

Astro는 [name].module.css 명명 규칙을 사용하여 CSS 모듈을 지원합니다. 다른 CSS 파일과 마찬가지로 파일을 가져오면 해당 CSS가 페이지에 자동으로 적용됩니다. 그러나 CSS 모듈은 원래 클래스 이름을 고유 식별자에 매핑하는 특별한 기본 styles 객체를 내보냅니다.

CSS 모듈은 스타일시트에 대해 고유하게 생성된 클래스 이름을 사용하여 프런트엔드에서 컴포넌트 범위 지정 및 격리를 적용하는 데 도움이 됩니다.

기타 자산

섹션 제목: 기타 자산

import imgReference from './image.png'; // imgReference === '/src/image.png'
import svgReference from './image.svg'; // svgReference === '/src/image.svg'
import txtReference from './words.txt'; // txtReference === '/src/words.txt'

// 이 예시에서는 JSX를 사용하지만 모든 프레임워크에서 가져오기 참조를 사용할 수 있습니다.
<img src={imgReference.src} alt="이미지 설명" />;

위에 명시적으로 언급되지 않은 다른 모든 자산은 ESM import를 통해 가져올 수 있으며 최종 빌드된 자산에 대한 URL 참조를 반환합니다. 이는 해당 이미지를 가리키는 src 속성을 사용하여 이미지 요소를 생성하는 것과 같이 JS가 아닌 자산을 URL로 참조하는 데 유용할 수 있습니다.

프로젝트 구조 페이지에 설명된 대로 public/ 폴더에 이미지를 배치하는 것도 유용할 수 있습니다.

노트

접근성을 위해 <img> 태그에 대체 텍스트를 추가하는 것이 좋습니다! 이미지 요소에 alt="유용한 설명" 속성을 추가하는 것을 잊지 마세요. 이미지가 순전히 장식용인 경우 속성을 비워 둘 수 있습니다.

별칭

섹션 제목: 별칭

별칭은 가져오기에 대한 바로가기를 만드는 방법입니다.

별칭은 디렉터리 또는 상대 경로에서 가져오는 경우가 많은 코드베이스의 개발 경험을 개선하는 데 도움이 됩니다.

src/pages/about/company.astro

---
import Button from '../../components/controls/Button.astro';
import logoUrl from '../../assets/logo.png?url';
---

이 예에서 개발자는 src/pages/about/company.astro, src/components/controls/Button.astro, src/assets/logo.png 세 파일 간의 트리 관계를 이해해야 합니다. 그리고 company.astro 파일을 옮기려면 가져오는 경로도 함께 업데이트해야 합니다.

tsconfig.json 또는 jsconfig.json 파일에서 가져오기 별칭을 추가할 수 있습니다.

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@assets/*": ["src/assets/*"]
    }
  }
}

노트

별칭 경로를 확인할 수 있도록 compilerOptions.baseUrl이 설정되어 있는지 확인하세요.

이 구성이 변경되면 개발 서버가 자동으로 다시 시작됩니다. 이제 프로젝트의 어느 곳에서나 별칭을 사용하여 가져올 수 있습니다.

src/pages/about/company.astro

---
import Button from '@components/controls/Button.astro';
import logoUrl from '@assets/logo.png?url';
---

이러한 별칭은 VS Code 및 기타 편집기에 자동으로 통합됩니다.

Astro.glob()

섹션 제목: Astro.glob()

Astro.glob()은 한 번에 많은 파일을 가져오는 방법입니다.

Astro.glob()은 하나의 매개변수, 즉 가져오려는 로컬 파일과 일치하는 상대 glob 패턴만 사용합니다. 비동기식이며 각 파일의 내보내기와 일치하는 배열을 반환합니다.

src/components/my-component.astro

---
// `./src/pages/post/`에서 `.md`로 끝나는 모든 파일을 가져옵니다.
const posts = await Astro.glob('../pages/post/*.md');
---

<!-- 처음 5개의 블로그 게시물에 대한 <article>을 렌더링합니다. -->
<div>
  {
    posts.slice(0, 4).map((post) => (
      <article>
        <h2>{post.frontmatter.title}</h2>
        <p>{post.frontmatter.description}</p>
        <a href={post.url}>계속 읽기</a>
      </article>
    ))
  }
</div>

Astro.glob을 사용하여 가져온 Astro 컴포넌트는 AstroInstance 타입입니다. default 속성을 사용하여 각 컴포넌트 인스턴스를 렌더링할 수 있습니다.

src/pages/component-library.astro

---
// `./src/components/`에서 `.astro`로 끝나는 모든 파일을 가져옵니다.
const components = await Astro.glob('../components/*.astro');
---

<!-- 모든 컴포넌트 표시 -->{
  components.map((component) => (
    <div>
      <component.default size={24} />
    </div>
  ))
}

Glob 패턴

섹션 제목: Glob 패턴

glob 패턴은 특수 와일드카드 문자를 지원하는 파일 경로입니다. 이는 프로젝트의 여러 파일을 한 번에 참조하는 데 사용됩니다.

예를 들어 glob 패턴 ./pages/**/*.{md,mdx}는 페이지 하위 디렉터리에서 시작하여 모든 하위 디렉터리 (/**)를 검색하고 .md 또는 .mdx (.{md,mdx})로 끝나는 모든 파일 이름 (/*)을 찾습니다.

Astro의 Glob 패턴

섹션 제목: Astro의 Glob 패턴

Astro.glob()과 함께 사용하려면 glob 패턴이 문자열 리터럴이어야 하며 어떤 변수도 포함할 수 없습니다. 해결 방법은 문제 해결 가이드를 참조하세요.

또한 glob 패턴은 다음 중 하나로 시작해야 합니다.

• ./ (현재 디렉터리에서 시작)
• ../ (상위 디렉터리에서 시작)
• / (프로젝트 루트에서 시작)

glob 패턴 구문에 대해 자세히 알아보세요.

Astro.glob() vs getCollection()

섹션 제목: Astro.glob() vs getCollection()

콘텐츠 컬렉션은 Astro.glob() 대신 여러 파일을 가져오기 위한 getCollection() API를 제공합니다. 콘텐츠 파일 (예: Markdown, MDX, Markdoc)이 src/content/ 디렉터리의 컬렉션에 있는 경우 getCollection()을 사용하여 컬렉션을 쿼리하고 콘텐츠 항목을 반환합니다.

WASM

섹션 제목: WASM

// 요청된 WASM 파일을 가져와 초기화합니다.
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astro는 브라우저의 WebAssembly API를 사용하여 WASM 파일을 애플리케이션에 직접 로드하는 것을 지원합니다.

Node 내장

섹션 제목: Node 내장

Astro 사용자는 가능하면 Node.js 내장 기능(fs, path 등)을 피하는 것이 좋습니다. Astro는 어댑터를 사용하여 여러 런타임과 호환됩니다. 여기에는 fs와 같은 노드 내장 모듈을 지원하지 않는 Deno 및 Cloudflare Workers가 포함됩니다.

우리의 목표는 일반적인 Node.js 내장 기능에 대한 Astro 대안을 제공하는 것입니다. 그러나 오늘날에는 그러한 대안이 존재하지 않습니다. 따라서 이러한 내장 모듈을 반드시 사용해야 하는 경우에도 우리는 여러분을 막고 싶지 않습니다. Astro는 Node의 최신 node: 접두사를 사용하여 Node.js 내장 기능을 지원합니다. 예를 들어 파일을 읽으려면 다음과 같이 할 수 있습니다.

src/components/MyComponent.astro

---
// 예: Node.js에서 내장된 "fs/promises" 가져오기
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const data = JSON.parse(json);
---

<span>버전: {data.version}</span>

파일 형식 지원 확장

섹션 제목: 파일 형식 지원 확장

Vite 및 호환되는 Rollup 플러그인을 사용하면 Astro에서 기본적으로 지원하지 않는 파일 형식을 가져올 수 있습니다. Vite 문서의 플러그인 찾기 섹션에서 필요한 플러그인을 찾아보세요.

플러그인 구성

구성 옵션과 올바르게 설치하는 방법은 플러그인 설명서를 참조하세요.

관련 레시피: Vite 또는 Rollup 플러그인 설치