가져오기 참조

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

지원되는 파일 형식

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

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

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

`public/` 디렉터리 내 파일

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

HTML 템플릿에서 직접 URL 경로로 public/ 파일을 참조할 수 있습니다.

// /public/reports/annual/2024.pdf 링크
Download the <a href="/reports/annual/2024.pdf">2024 annual statement as a PDF</a>.

// /public/assets/cats/ginger.jpg 표시
<img src="/assets/cats/ginger.jpg" alt="An orange cat sleeping on a bed.">

Import 구문

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

JavaScript

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

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

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 파일을 가져올 때 .ts 및 .tsx 파일 확장자를 사용하면 안 됩니다. 대신 .js/.jsx 파일 확장자를 사용하거나 파일 확장자를 완전히 생략하세요.

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

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

NPM 패키지

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

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

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

JSON

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

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

CSS

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

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

스타일링 가이드에서 CSS 파일에 대한 직접 URL 참조 또는 문자열로 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/ 폴더에 이미지를 배치하는 것도 유용할 수 있습니다.

Vite 가져오기 매개변수 (예: ?url, ?raw) 추가에 대한 자세한 내용은 Vite의 정적 자산 처리 가이드를 참조하세요.

별칭

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

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

---
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 파일에서 별칭 가져오기를 추가할 수 있습니다.

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

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

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

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

`import.meta.glob()`

Vite의 import.meta.glob()는 glob 패턴을 사용하여 일치하는 파일 경로를 찾아 한 번에 여러 파일을 가져오는 방법입니다.

import.meta.glob()은 가져오고 싶은 로컬 파일과 일치하는 상대적인 glob 패턴을 매개변수로 받습니다. 일치하는 각 파일의 내보내기가 포함된 배열을 반환합니다. 일치하는 모든 모듈을 미리 로드하려면 두 번째 인수로 { eager: true }를 전달하세요:

---
// `./src/pages/post/`에서 `.md`로 끝나는 모든 파일을 가져옵니다.
const matches = import.meta.glob('../pages/post/*.md', { eager: true });
const posts = Object.values(matches);
---

<!-- 처음 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>

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

---
// `./src/components/`에서 `.astro`로 끝나는 모든 파일을 가져옵니다.
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- 모든 컴포넌트 표시 -->{
  components.map((component) => (
    <div>
      <component.default size={24} />
    </div>
  ))
}

지원되는 값

Vite의 import.meta.glob() 함수는 정적 문자열 리터럴만 지원합니다. 동적 변수와 문자열 보간을 지원하지 않습니다.

일반적인 해결 방법은 필요한 모든 파일이 포함된 더 큰 파일 세트를 가져온 다음 필터링하는 것입니다:

---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  Take a look at my favorite post, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>

타입 유틸리티 가져오기

Markdown 파일

import.meta.glob()로 로드된 Markdown 파일은 다음과 같은 MarkdownInstance 인터페이스를 반환합니다:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* 이 파일의 YAML 프런트매터에 지정된 모든 데이터 */
  frontmatter: T;
  /* 이 파일의 절대 경로 */
  file: string;
  /* 이 파일의 렌더링된 경로 */
  url: string | undefined;
  /* 이 파일의 내용을 렌더링하는 Astro 컴포넌트 */
  Content: AstroComponentFactory;
  /** (Markdown만 해당) 레이아웃 HTML과 YAML 프런트매터를 제외한 원시 Markdown 파일 내용 */
  rawContent(): string;
  /** (Markdown만 해당) HTML로 컴파일된 Markdown 파일, 레이아웃 HTML 제외 */
  compiledContent(): string;
  /* 이 파일의 h1부터 h6까지의 요소들의 배열을 반환하는 함수 */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

TypeScript 제네릭을 사용하여 frontmatter 변수의 타입을 선택적으로 제공할 수 있습니다.

---
import type { MarkdownInstance } from 'astro';
interface Frontmatter {
    title: string;
    description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Astro 파일

Astro 파일은 다음과 같은 인터페이스를 가집니다:

export interface AstroInstance {
  /* 이 파일의 경로 */
  file: string;
  /* 이 파일의 URL (pages 디렉터리에 있는 경우) */
  url: string | undefined;
  default: AstroComponentFactory;
}

기타 파일

다른 파일들은 다양한 인터페이스를 가질 수 있지만, 알 수 없는 파일 타입이 무엇을 포함하는지 정확히 알고 있다면 import.meta.glob()은 TypeScript 제네릭을 받습니다.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---

Glob 패턴

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

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

Astro의 Glob 패턴

import.meta.glob()과 함께 사용하려면 glob 패턴이 문자열 리터럴이어야 하며 어떤 변수도 포함할 수 없습니다.

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

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

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

`import.meta.glob()` vs `getCollection()`

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

WASM

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

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

Node 내장

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

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

---
// 예: 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 플러그인 설치

기여하기

커뮤니티

가져오기 참조

지원되는 파일 형식

`public/` 디렉터리 내 파일

Import 구문

JavaScript

TypeScript

NPM 패키지

JSON

CSS

CSS 모듈

기타 자산

별칭

`import.meta.glob()`

지원되는 값

타입 유틸리티 가져오기

Markdown 파일

Astro 파일

기타 파일

Glob 패턴

Astro의 Glob 패턴

`import.meta.glob()` vs `getCollection()`

WASM

Node 내장

파일 형식 지원 확장

여러분의 생각을 들려주세요!

GitHub Issue 생성

의견 보내기

의견 보내기

가져오기 참조

지원되는 파일 형식

public/ 디렉터리 내 파일

Import 구문

JavaScript

TypeScript

NPM 패키지

JSON

CSS

CSS 모듈

기타 자산

별칭

import.meta.glob()

지원되는 값

타입 유틸리티 가져오기

Markdown 파일

Astro 파일

기타 파일

Glob 패턴

Astro의 Glob 패턴

import.meta.glob() vs getCollection()

WASM

Node 내장

파일 형식 지원 확장

`public/` 디렉터리 내 파일

`import.meta.glob()`

`import.meta.glob()` vs `getCollection()`