API 참조

`Astro` global

Astro global은 .astro 파일의 모든 컨텍스트에서 사용할 수 있습니다. 다음과 같은 기능이 있습니다:

`Astro.glob()`

Astro.glob()은 정적 사이트 설정에 많은 로컬 파일을 로드하는 방법입니다.

---
const posts = await Astro.glob('../pages/post/*.md'); // ./src/pages/post/*.md 파일에 있는 게시물 배열을 반환합니다.
---

<div>
{posts.slice(0, 3).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Read more</a>
  </article>
))}
</div>

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

.glob()은 정적으로 분석할 수 없기 때문에 이를 보간하는 변수나 문자열을 사용할 수 없습니다. (해결 방법은 문제 해결 안내서를 참조하세요.) 이는 Astro.glob()이 Vite의 import.meta.glob()의 래퍼이기 때문입니다..

Astro 프로젝트에서 import.meta.glob() 자체를 사용할 수도 있습니다. 다음과 같은 경우에 이 작업을 수행할 수 있습니다.

API 경로와 같이 .astro가 아닌 파일에 이 기능이 필요합니다. Astro.glob()은 .astro 파일에서만 사용할 수 있는 반면, import.meta.glob()은 프로젝트의 어느 곳에서나 사용할 수 있습니다.
각 파일을 즉시 로드하고 싶지는 않을 때 사용할 수 있습니다. import.meta.glob()은 콘텐츠 자체를 반환하는 대신 파일 콘텐츠를 가져오는 함수를 반환할 수 있습니다. 이 가져오기에는 가져온 파일의 모든 스타일과 스크립트가 포함됩니다. 이는 파일이 실제로 사용되는지 여부에 관계없이 번들로 묶여 페이지에 추가됩니다. 이는 런타임 시가 아닌 정적 분석에 의해 결정되기 때문입니다.
각 파일의 경로에 접근하고 싶을 때 사용할 수 있습니다. import.meta.glob()은 파일의 콘텐츠 경로 맵을 반환하는 반면 Astro.glob()은 콘텐츠 목록을 반환합니다.
여러 패턴을 전달하고 싶을 때 사용할 수 있습니다. 예를 들어 특정 파일을 필터링하는 “부정 패턴”을 추가하려고 합니다. import.meta.glob()은 선택적으로 단일 문자열이 아닌 glob 문자열 배열을 취할 수 있습니다.

Vite 문서에서 자세한 내용을 읽어보세요.

Markdown 파일

Astro.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을 제외한 HTML로 컴파일된 Markdown 파일 */
  compiledContent(): string;
  /* 이 파일의 h1...h6 요소 배열을 반환하는 함수 */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

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

---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

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

Astro 파일

Astro 파일에는 다음과 같은 인터페이스가 있습니다:

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

기타 파일

다른 파일에는 다양한 인터페이스가 있을 수 있지만, 인식할 수 없는 파일 타입에 무엇이 포함되어 있는지 정확히 아는 경우 Astro.glob()은 TypeScript 제네릭을 허용합니다.

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

`Astro.props`

Astro.props는 컴포넌트 속성으로 전달된 모든 값을 포함하는 객체입니다. .md 및 .mdx 파일의 레이아웃 컴포넌트는 프런트매터 값을 props로 받습니다.

---
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>

---
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />

Markdown 및 MDX 레이아웃이 props를 처리하는 방법에 대해 자세히 알아보세요.

props에 대한 TypeScript 타입 정의를 추가하는 방법을 알아보세요.

`Astro.params`

Astro.params는 이 요청과 일치하는 동적 경로 세그먼트의 값을 포함하는 객체입니다.

정적 빌드에서 이 객체는 동적 경로 사전 렌더링에 사용되는 getStaticPaths()에서 반환하는 params입니다.

SSR 빌드에서는 동적 경로 패턴의 경로 세그먼트와 일치하는 모든 값이 될 수 있습니다.

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

함께 보기: params

`Astro.request`

타입: Request

Astro.request는 표준 Request 객체입니다. url, headers, method 및 요청 본문을 가져오는 데 사용할 수 있습니다.

<p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
<p>Received request headers: <code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code>

함께 보기: Astro.url

`Astro.response`

타입: ResponseInit & { readonly headers: Headers }

Astro.response는 표준 ResponseInit 객체입니다. 다음과 같은 구조를 가지고 있습니다.

status: 응답의 숫자 상태 코드입니다(예: 200).
statusText: 상태 코드와 관련된 상태 메시지입니다 (예: 'OK').
headers: 응답의 HTTP 헤더를 설정하는 데 사용할 수 있는 Headers 인스턴스입니다.

Astro.response는 페이지 응답에 대한 status, statusText, headers를 설정하는 데 사용됩니다.

---
if(condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---

또는 헤더를 설정하려면:

---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---

`Astro.cookies`

타입: AstroCookies

Added in: astro@1.4.0

Astro.cookies에는 서버 측 렌더링 모드에서 쿠키를 읽고 조작하기 위한 유틸리티가 포함되어 있습니다.

`get`

타입: (key: string, options?: AstroCookieGetOptions) => AstroCookie | undefined

쿠키를 문자열이 아닌 타입으로 변환하기 위한 value 및 유틸리티 함수가 포함된 AstroCookie 객체로 쿠키를 가져옵니다.

`has`

타입: (key: string, options?: AstroCookieGetOptions) => boolean

이 쿠키가 존재하는지 여부입니다. 쿠키가 Astro.cookies.set()을 통해 설정된 경우 true를 반환하고, 그렇지 않으면 Astro.request에서 쿠키를 확인합니다.

`set`

타입: (key: string, value: string | object, options?: AstroCookieSetOptions) => void

쿠키의 key를 주어진 값으로 설정합니다. 그러면 쿠키 값을 문자열로 변환하려고 시도합니다. 옵션은 maxAge 또는 httpOnly와 같은 쿠키 기능을 설정하는 방법을 제공합니다.

`delete`

타입: (key: string, options?: AstroCookieDeleteOptions) => void

만료 날짜를 과거 (Unix 시간에서는 0)로 설정하여 쿠키를 무효화합니다.

쿠키가 “제거되면” (만료되면) Astro.cookies.has()는 false를 반환하고 Astro.cookies.get()은 value가 undefined인 AstroCookie를 반환합니다. 쿠키를 삭제할 때 사용할 수 있는 옵션은 domain, path, httpOnly, sameSite 및 secure입니다.

`merge`

타입: (cookies: AstroCookies) => void

새 AstroCookies 인스턴스를 현재 인스턴스에 병합합니다. 새 쿠키가 현재 인스턴스에 추가되고 같은 이름의 쿠키가 존재하면 기존 값을 덮어씁니다.

`headers`

타입: () => Iterator<string>

응답과 함께 전송될 Set-Cookie에 대한 헤더 값을 가져옵니다.

`AstroCookie`

Astro.cookies.get()을 통해 쿠키를 가져오면 AstroCookie 타입이 반환됩니다. 다음과 같은 구조를 가지고 있습니다.

`value`

타입: string

쿠키의 원시 문자열 값입니다.

`json`

타입: () => Record<string, any>

JSON.parse()를 통해 쿠키 값을 구문 분석하여 객체를 반환합니다. 쿠키 값이 유효한 JSON이 아닌 경우 예외가 발생합니다.

`number`

타입: () => number

쿠키 값을 숫자로 구문 분석합니다. 유효한 숫자가 아닌 경우 NaN을 반환합니다.

`boolean`

타입: () => boolean

쿠키 값을 true 또는 false로 변환합니다.

`AstroCookieGetOptions`

Added in: astro@4.1.0

쿠키를 얻으면 AstroCookieGetOptions 인터페이스를 통해 옵션을 지정할 수도 있습니다.

`decode`

타입: (value: string) => string

쿠키가 값으로 역직렬화되는 방식을 사용자 정의할 수 있습니다.

`AstroCookieSetOptions`

Added in: astro@4.1.0

Astro.cookies.set()을 통해 쿠키를 설정하면 AstroCookieSetOptions를 전달하여 쿠키 직렬화 방법을 맞춤설정할 수 있습니다.

`domain`

타입: string

도메인을 지정합니다. 도메인이 설정되지 않은 경우 대부분의 클라이언트는 현재 도메인에 적용되도록 해석합니다.

`expires`

타입: Date

쿠키가 만료되는 날짜를 지정합니다.

`httpOnly`

타입: boolean

true인 경우 클라이언트 측에서 쿠키에 액세스할 수 없습니다.

`maxAge`

타입: number

쿠키가 유효한 시간 (초)을 지정합니다.

`path`

타입: string

쿠키가 적용되는 도메인의 하위 경로를 지정합니다.

`sameSite`

타입: boolean | 'lax' | 'none' | 'strict'

SameSite 쿠키 헤더의 값을 지정합니다.

`secure`

타입: boolean

true인 경우 쿠키는 https 사이트에만 설정됩니다.

`encode`

타입: (value: string) => string

쿠키가 직렬화되는 방식을 사용자 정의할 수 있습니다.

`Astro.redirect()`

타입: (path: string, status?: number) => Response

다른 페이지로 리디렉션할 수 있으며, 선택적으로 HTTP 응답 상태 코드를 두 번째 매개변수로 제공할 수 있습니다.

페이지 (하위 컴포넌트는 아님)에 리디렉션이 발생하려면 Astro.redirect() 결과를 return해야 합니다.

정적으로 생성된 사이트의 경우 <meta http-equiv="refresh"> 태그를 사용하여 클라이언트 리디렉션을 생성하며 상태 코드를 지원하지 않습니다.

주문형 렌더링 모드를 사용할 경우 상태 코드가 지원됩니다. Astro는 다른 코드를 지정하지 않는 한 리디렉션된 요청을 기본 HTTP 응답 상태인 302로 처리합니다.

다음 예시는 사용자를 로그인 페이지로 리디렉션합니다:

---
import { isLoggedIn } from '../utils';

const cookie = Astro.request.headers.get('cookie');

// 사용자가 로그인되어 있지 않은 경우 로그인 페이지로 리디렉션
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---

`Astro.rewrite()`

타입: (rewritePayload: string | URL | Request) => Promise<Response>

Added in: astro@4.13.0

브라우저를 새 페이지로 리디렉션하지 않고 다른 URL이나 경로에서 콘텐츠를 제공할 수 있습니다.

이 메서드는 경로 위치에 대한 문자열, URL 또는 Request 중 하나를 허용합니다.

문자열을 사용하여 명시적인 경로를 제공합니다:

---
return Astro.rewrite("/login")
---

리라이트를 위한 URL 경로를 구성해야 하는 경우 URL 타입을 사용합니다. 다음 예시는 상대 "../" 경로에서 새 URL을 생성하여 페이지의 상위 경로를 렌더링합니다:

---
return Astro.rewrite(new URL("../", Astro.url))
---

새 경로에 대해 서버로 전송되는 Request를 완벽하게 제어하려면 Request 타입을 사용합니다. 다음 예시는 헤더를 제공하면서 상위 페이지를 렌더링하도록 요청을 전송합니다:

---
return Astro.rewrite(new Request(new URL("../", Astro.url), {
  headers: {
    "x-custom-header": JSON.stringify(Astro.locals.someValue)
  }
}))
---

`Astro.url`

타입: URL

Added in: astro@1.0.0-rc

현재 Astro.request.url URL 문자열 값에서 생성된 URL 객체입니다. pathname 및 origin과 같은 요청 URL의 개별 속성과 상호 작용하는 데 유용합니다.

new URL(Astro.request.url)을 수행하는 것과 동일합니다.

정적 사이트 및 server 또는 hybrid 출력을 사용하는 주문형 렌더링 사이트에서 site가 구성되지 않은 경우 개발 모드에서 Astro.url은 localhost가 됩니다.

<h1>The current URL is: {Astro.url}</h1>
<h1>The current URL pathname is: {Astro.url.pathname}</h1>
<h1>The current URL origin is: {Astro.url.origin}</h1>

Astro.url을 new URL()에 인수로 전달하여 새 URL을 생성하는 데 사용할 수도 있습니다.

---
// 예: 프로덕션 도메인을 사용하여 canonical URL 구성
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// Example: 현재 도메인을 사용하여 SEO 메타 태그용 URL을 구성
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />

`Astro.clientAddress`

타입: string

Added in: astro@1.0.0-rc

요청의 IP 주소를 지정합니다. 이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

---
const ip = Astro.clientAddress;
---

<div>Your IP address is: <span class="address">{ ip }</span></div>

`Astro.site`

타입: URL | undefined

Astro.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. Astro 구성의 site가 정의되지 않은 경우 Astro.site가 정의되지 않습니다.

`Astro.generator`

타입: string

Added in: astro@1.0.0

Astro.generator는 <meta name="generator"> 태그에 현재 버전의 Astro를 추가하는 편리한 방법입니다. "Astro v1.x.x" 형식을 따릅니다.

<html>
  <head>
    <meta name="generator" content={Astro.generator} />
  </head>
  <body>
    <footer>
      <p>Built with <a href="https://astro.build">{Astro.generator}</a></p>
    </footer>
  </body>
</html>

`Astro.slots`

Astro.slots에는 Astro 컴포넌트의 슬롯 하위 항목을 수정하기 위한 유틸리티 함수가 포함되어 있습니다.

`Astro.slots.has()`

타입: (slotName: string) => boolean

Astro.slots.has()를 사용하면 특정 슬롯 이름에 대한 콘텐츠가 존재하는지 확인할 수 있습니다. 이는 슬롯 콘텐츠를 래핑하고 싶지만 슬롯이 사용될 때만 래퍼 요소를 렌더링하려는 경우에 유용할 수 있습니다.

---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>More</h2>
    <slot name="more" />
  </aside>
)}

`Astro.slots.render()`

타입: (slotName: string, args?: any[]) => Promise<string>

Astro.slots.render()를 사용하여 슬롯의 내용을 HTML 문자열로 비동기적으로 렌더링할 수 있습니다.

---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />

Astro.slots.render()는 선택적으로 두 번째 인수, 즉 모든 함수 하위 항목에 전달될 매개변수 배열을 허용합니다. 이는 사용자 정의 유틸리티 컴포넌트에 유용할 수 있습니다.

예를 들어, 이 <Shout /> 컴포넌트는 message prop을 대문자로 변환하고 이를 기본 슬롯에 전달합니다.

---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />

<Shout />의 하위 항목으로 전달된 콜백 함수는 모두 대문자인 message 매개변수를 받습니다:

---
import Shout from "../components/Shout.astro";
---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- <div>SLOTS!</div>로 렌더링 됩니다. -->

콜백 함수는 slot 속성이 있는 래핑 HTML 요소 태그 내부의 명명된 슬롯으로 전달할 수 있습니다. 이 요소는 콜백을 명명된 슬롯으로 전송하는 데만 사용되며 페이지에 렌더링되지 않습니다.

<Shout message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Shout>

래핑 태그에는 표준 HTML 요소를 사용하거나 컴포넌트로 해석되지 않는 소문자 태그 (예: <Fragment /> 대신 <fragment>)를 사용하세요. HTML <slot> 요소는 Astro 슬롯으로 해석되므로 사용하지 마세요.

`Astro.self`

Astro.self를 사용하면 Astro 컴포넌트를 재귀적으로 호출할 수 있습니다. 이 동작을 사용하면 컴포넌트 템플릿의 <Astro.self>를 사용하여 Astro 컴포넌트 자체에서 Astro 컴포넌트를 렌더링할 수 있습니다. 이는 대규모 데이터 저장소와 중첩된 데이터 구조를 반복하는 데 도움이 될 수 있습니다.

---
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- If there is a nested data-structure we render `<Astro.self>` -->
      <!-- and can pass props through with the recursive call -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>

그러면 이 컴포넌트는 다음과 같이 사용될 수 있습니다.

---
import NestedList from './NestedList.astro';
---
<NestedList items={['A', ['B', 'C'], 'D']} />

그리고 HTML을 다음과 같이 렌더링합니다.

<ul class="nested-list">
  <li>A</li>
  <li>
    <ul class="nested-list">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

`Astro.locals`

Added in: astro@2.4.0

Astro.locals는 미들웨어의 context.locals 객체의 값을 포함하는 객체입니다. 이를 사용하여 .astro 파일의 미들웨어가 반환한 데이터에 액세스합니다.

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<ul>
    {orders.map(order => {
        return <li>{/* 각 order마다 작업 수행 */}</li>
    })}
</ul>

`Astro.preferredLocale`

타입: string | undefined

Added in: astro@3.5.0

Astro.preferredLocale은 사용자가 선호하는 언어를 나타내는 계산된 값입니다.

i18n.locales 배열에 구성된 언어와 Accept-Language 헤더를 통해 사용자 브라우저에서 지원하는 언어를 확인하여 계산됩니다. 일치하는 항목이 없으면 이 값은 undefined입니다.

이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

`Astro.preferredLocaleList`

타입: string[] | undefined

Added in: astro@3.5.0

Astro.preferredLocaleList는 브라우저에서 요청하고 웹사이트에서 지원하는 모든 언어의 배열을 나타냅니다. 그러면 여러분의 사이트와 방문자 간에 호환되는 모든 언어 목록이 생성됩니다.

브라우저에서 요청한 언어가 언어 배열에 없으면 값은 []입니다. 즉, 방문자가 선호하는 언어을 지원하지 않습니다.

브라우저가 선호하는 언어를 지정하지 않으면 이 값은 i18n.locales가 됩니다. 지원되는 모든 언어는 선호 사항이 없는 방문자가 동일하게 선호하는 것으로 간주됩니다.

이 속성은 SSR(서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

`Astro.currentLocale`

타입: string | undefined

Added in: astro@3.5.6

locales 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 언어입니다. URL에 /[locale]/ 접두사가 포함되어 있지 않으면 값은 기본적으로 i18n.defaultLocale이 됩니다.

엔드포인트 Context

엔드포인트 함수는 첫 번째 매개변수로 context 객체를 받습니다. 이는 Astro global 속성의 많은 부분을 반영합니다.

import type { APIContext } from 'astro';

export function GET(context: APIContext) {
  // ...
}

`context.params`

context.params는 이 요청과 일치하는 동적 경로 세그먼트의 값을 포함하는 객체입니다.

정적 빌드에서 이 객체는 동적 경로 사전 렌더링에 사용되는 getStaticPaths()에서 반환하는 params입니다.

SSR 빌드에서는 동적 경로 패턴의 경로 세그먼트와 일치하는 모든 값이 될 수 있습니다.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

export function GET({ params }: APIContext) {
  return new Response(
    JSON.stringify({ id: params.id }),
  );
}

함께 보기: params

`context.props`

Added in: astro@1.5.0

context.props는 getStaticPaths()에서 전달된 props를 포함하는 객체입니다. SSR (서버 측 렌더링)용으로 빌드할 때는 getStaticPaths()가 사용되지 않으므로 context.props는 정적 빌드에서만 사용할 수 있습니다.

import type { APIContext } from 'astro';

export function getStaticPaths() {
  return [
    { params: { id: '1' }, props: { author: 'Blu' } },
    { params: { id: '2' }, props: { author: 'Erika' } },
    { params: { id: '3' }, props: { author: 'Matthew' } }
  ];
}

export function GET({ props }: APIContext) {
  return new Response(
    JSON.stringify({ author: props.author }),
  );
}

함께 보기: props를 사용한 데이터 전달

`context.request`

타입: Request

표준 Request 객체입니다. url, headers, method 및 요청 본문을 가져오는 데 사용할 수 있습니다.

import type { APIContext } from 'astro';

export function GET({ request }: APIContext) {
  return new Response(`Hello ${request.url}`);
}

함께 보기: Astro.request

`context.cookies`

타입: AstroCookies

context.cookies에는 쿠키를 읽고 조작하는 유틸리티가 포함되어 있습니다.

함께 보기: Astro.cookies

`context.url`

타입: URL

Added in: astro@1.5.0

현재 context.request.url URL 문자열 값에서 생성된 URL 객체.

함께 보기: Astro.url

`context.clientAddress`

타입: string

Added in: astro@1.5.0

요청의 IP 주소를 지정합니다. 이 속성은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

import type { APIContext } from 'astro';

export function GET({ clientAddress }: APIContext) {
  return new Response(`Your IP address is: ${clientAddress}`);
}

함께 보기: Astro.clientAddress

`context.site`

타입: URL | undefined

Added in: astro@1.5.0

context.site는 Astro 구성의 site에서 만들어진 URL을 반환합니다. 정의되지 않은 경우 localhost에서 생성된 URL이 반환됩니다.

함께 보기: Astro.site

`context.generator`

타입: string

Added in: astro@1.5.0

context.generator는 프로젝트가 실행 중인 Astro 버전을 나타내는 편리한 방법입니다. "Astro v1.x.x" 형식을 따릅니다.

import type { APIContext } from 'astro';

export function GET({ generator, site }: APIContext) {
  const body = JSON.stringify({ generator, site });
  return new Response(body);
}

함께 보기: Astro.generator

`context.redirect()`

타입: (path: string, status?: number) => Response

Added in: astro@1.5.0

context.redirect()는 다른 페이지로 리디렉션할 수 있는 Response 객체를 반환합니다. 이 기능은 SSR (서버 측 렌더링)용으로 빌드할 때만 사용할 수 있으며 정적 사이트에는 사용하면 안 됩니다.

import type { APIContext } from 'astro';

export function GET({ redirect }: APIContext) {
  return redirect('/login', 302);
}

함께 보기: Astro.redirect()

`context.rewrite()`

타입: (rewritePayload: string | URL | Request) => Promise<Response>

Added in: astro@4.13.0

브라우저를 새 페이지로 리디렉션하지 않고 다른 URL이나 경로에서 콘텐츠를 제공할 수 있습니다.

이 메서드는 경로 위치에 대한 문자열, URL, 또는 Request 중 하나를 허용합니다.

문자열을 사용하여 명시적인 경로를 제공합니다:

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite('/login');
}

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new URL("../", Astro.url));
}

import type { APIContext } from 'astro';

export function GET({ rewrite }: APIContext) {
  return rewrite(new Request(new URL("../", Astro.url), {
   headers: {
     "x-custom-header": JSON.stringify(Astro.locals.someValue)
   }
 }));
}

함께 보기: Astro.rewrite()

`context.locals`

Added in: astro@2.4.0

context.locals는 요청 수명 주기 동안 임의의 정보를 저장하고 액세스하는 데 사용되는 객체입니다.

미들웨어 함수는 context.locals 값을 읽고 쓸 수 있습니다.

import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Default Title";
  }
  return next();
}

API 엔드포인트는 context.locals의 정보만 읽을 수 있습니다.

import type { APIContext } from 'astro';

export function GET({ locals }: APIContext) {
  return new Response(locals.title); // "Default Title"
}

함께 보기: Astro.locals

`getStaticPaths()`

타입: (options: GetStaticPathsOptions) => Promise<GetStaticPathsResult> | GetStaticPathsResult

페이지가 파일 이름에 동적 매개변수를 사용하는 경우 해당 컴포넌트는 getStaticPaths() 함수를 내보내야 합니다.

Astro는 정적 사이트 빌더이기 때문에 이 기능이 필요합니다. 이는 전체 사이트가 미리 빌드되었음을 의미합니다. Astro가 빌드 시 페이지를 생성하는 방법을 모른다면 사용자가 사이트를 방문할 때 해당 페이지를 볼 수 없습니다.

---
export async function getStaticPaths() {
  return [
    { params: { /* 필수 */ }, props: { /* 선택사항 */ } },
    { params: { ... } },
    { params: { ... } },
    // ...
  ];
}
---
<!-- HTML 템플릿 작성 -->

getStaticPaths() 함수는 Astro가 어떤 경로를 미리 렌더링할지 결정하기 위해 객체 배열을 반환해야 합니다.

동적 라우팅을 위한 정적 파일 엔드포인트에서도 사용할 수 있습니다.

`params`

반환된 모든 객체의 params 키는 Astro에게 어떤 경로를 빌드할지 알려줍니다. 반환된 매개변수는 컴포넌트 파일 경로에 정의된 동적 매개변수 및 나머지 매개변수에 다시 매핑되어야 합니다.

params는 URL로 인코딩되므로 문자열만 값으로 지원됩니다. 각 params 객체의 값은 페이지 이름에 사용된 매개변수와 일치해야 합니다.

예를 들어 src/pages/posts/[id].astro에 페이지가 있다고 가정합니다. 이 페이지에서 getStaticPaths를 내보내고 경로에 대해 다음을 반환하는 경우:

---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}

const { id } = Astro.params;
---
<h1>{id}</h1>

그러면 Astro는 빌드 시 posts/1, posts/2, posts/3을 정적으로 생성합니다.

`props`를 사용한 데이터 전달

생성된 각 페이지에 추가 데이터를 전달하려면 반환된 모든 경로 객체에 props 값을 설정할 수도 있습니다. params와 달리 props는 URL로 인코딩되지 않으므로 문자열로만 제한되지 않습니다.

예를 들어, 원격 API에서 가져온 데이터를 기반으로 페이지를 생성한다고 가정해 보겠습니다. getStaticPaths의 페이지 컴포넌트에 전체 데이터 객체를 전달할 수 있습니다.

---
export async function getStaticPaths() {
  const data = await fetch('...').then(response => response.json());

  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}

const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>

알려진 경로 목록을 생성하거나 스텁할 때 도움이 될 수 있는 일반 배열을 전달할 수도 있습니다.

---
export async function getStaticPaths() {
  const posts = [
    {id: '1', category: "astro", title: "API Reference"},
    {id: '2', category: "react", title: "Creating a React Counter!"}
  ];
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { post }
    };
  });
}
const {id} = Astro.params;
const {post} = Astro.props;
---
<body>
  <h1>{id}: {post.title}</h1>
  <h2>Category: {post.category}</h2>
</body>

그런 다음 Astro는 pages/posts/[id].astro의 페이지 컴포넌트를 사용하여 빌드 시 posts/1, posts/2를 정적으로 생성합니다. 페이지는 Astro.props를 사용하여 이 데이터를 참조할 수 있습니다.

`paginate()`

페이지네이션은 Astro가 paginate() 함수를 통해 기본적으로 지원하는 웹사이트의 일반적인 사용 사례입니다. paginate()는 페이지가 매겨진 컬렉션의 모든 페이지에 대해 하나의 URL을 생성하는 getStaticPaths()에서 반환할 배열을 자동으로 생성합니다. 페이지 번호는 매개변수로 전달되고, 페이지 데이터는 page prop으로 전달됩니다.

export async function getStaticPaths({ paginate }) {
  // fetch(), Astro.glob() 등을 사용하여 데이터를 로드합니다.
  const response = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`);
  const result = await response.json();
  const allPokemon = result.results;

  // 모든 게시물에 대해 페이지가 매겨진 경로 컬렉션을 반환합니다.
  return paginate(allPokemon, { pageSize: 10 });
}

// 올바르게 설정되면 이제 page prop에 단일 페이지를 렌더링하는 데 필요한 모든 것이 포함됩니다 (다음 섹션 참조).
const { page } = Astro.props;

paginate()는 [page].astro 또는 [...page].astro라는 파일 이름을 가정합니다. page 매개변수는 URL의 페이지 번호가 됩니다.

/posts/[page].astro는 /posts/1, /posts/2, /posts/3 등의 URL을 생성합니다.
/posts/[...page].astro는 /posts, /posts/2, /posts/3 등의 URL을 생성합니다.

paginate()에는 다음 인수가 있습니다:

pageSize - 페이지당 표시되는 항목 수 (기본값은 10)
params - 동적 경로 생성을 위한 추가 매개변수 보내기
props - 각 페이지에서 사용할 수 있도록 추가 props 보내기

페이지네이션의 `page` prop

페이지네이션은 페이지 컬렉션의 단일 데이터 페이지를 나타내는 모든 렌더링된 페이지에 page prop을 전달합니다. 여기에는 페이지를 매긴 데이터 (page.data)와 페이지의 메타데이터 (page.url, page.start, page.end, page.total 등)가 포함됩니다. 이 메타데이터는 “다음 페이지” 버튼이나 “100개 중 1-10개 표시” 메시지 등을 표시하는데 유용합니다.

`page.data`

타입: Array

현재 페이지에 대해 data()에서 반환된 데이터 배열입니다.

`page.start`

타입: number

현재 페이지의 첫 번째 항목 색인으로 0부터 시작합니다. (예: pageSize: 25인 경우 1페이지에서는 0, 2페이지에서는 25입니다.)

`page.end`

타입: number

현재 페이지의 마지막 항목 색인입니다.

`page.size`

타입: number
기본값: 10

페이지당 항목 수입니다.

`page.total`

타입: number

모든 페이지의 총 항목 수입니다.

`page.currentPage`

타입: number

1부터 시작하는 현재 페이지 번호입니다.

`page.lastPage`

타입: number

총 페이지 수입니다.

`page.url.current`

타입: string

현재 페이지의 URL을 가져옵니다 (표준 URL에 유용함).

`page.url.prev`

타입: string | undefined

이전 페이지의 URL을 가져옵니다 (1페이지인 경우 undefined). base에 값이 설정된 경우 기본 경로를 URL 앞에 추가하세요.

`page.url.next`

타입: string | undefined

다음 페이지의 URL을 가져옵니다 (더 이상 페이지가 없으면 undefined). base에 값이 설정된 경우 기본 경로를 URL 앞에 추가하세요.

`page.url.first`

타입: string | undefined

Added in: astro@4.12.0

첫 페이지의 URL을 가져옵니다 (1페이지에 있는 경우 undefined). base의 값이 설정된 경우 URL 앞에 기본 경로를 추가하세요.

`page.url.last`

타입: string | undefined

Added in: astro@4.12.0

마지막 페이지의 URL을 가져옵니다 (더이상의 페이지가 존재하지 않는 경우 undefined). base의 값이 설정된 경우 URL 앞에 기본 경로를 추가하세요.

`import.meta`

모든 ESM 모듈에는 import.meta 속성이 포함되어 있습니다. Astro는 Vite를 통해 import.meta.env를 추가합니다.

import.meta.env.SSR 을 사용하면 서버에서 렌더링할 때 알 수 있습니다. 때로는 클라이언트에서만 렌더링되어야 하는 컴포넌트와 같은 다른 로직을 원할 수도 있습니다.

export default function () {
  return import.meta.env.SSR ? <div class="spinner"></div> : <FancyComponent />;
}

이미지 (`astro:assets`)

`getImage()`

타입: (options: UnresolvedImageTransform) => Promise<GetImageResult>

getImage() 함수는 HTML이 아닌 다른 곳 (예: API 경로)에서 사용할 이미지를 생성하기 위한 것입니다. 또한 사용자 정의 <Image /> 컴포넌트를 만들 수도 있습니다.

getImage()는 Image 컴포넌트와 동일한 속성을 가진 옵션 객체를 사용합니다 (alt 제외).

---
import { getImage } from "astro:assets";
import myBackground from "../background.png"

const optimizedBackground = await getImage({src: myBackground, format: 'avif'})
---

<div style={`background-image: url(${optimizedBackground.src});`}></div>

다음 타입을 가진 객체를 반환합니다.

type GetImageResult = {
  /* 이미지 렌더링에 필요한 추가 HTML 속성 (width, height, style 등) */
  attributes: Record<string, any>;
  /* 검증된 매개변수 전달 */
  options: ImageTransform;
  /* 원본 매개변수 전달 */
  rawOptions: ImageTransform;
  /* 생성된 이미지의 경로 */
  src: string;
  srcSet: {
    /* 생성된 srcset의 값, 각 항목에는 URL과 크기 설명자가 있습니다. */
    values: SrcSetValue[];
    /* `srcset` 속성에서 사용할 수 있는 값 */
    attribute: string;
  };
}

콘텐츠 컬렉션 (`astro:content`)

Added in: astro@2.0.0

콘텐츠 컬렉션은 src/content/에서 Markdown 또는 MDX 문서를 구성하고 쿼리하는 API를 제공합니다. 기능 및 사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`defineCollection()`

타입: (input: CollectionConfig) => CollectionConfig

defineCollection()은 src/content/config.* 파일에 컬렉션을 구성하는 유틸리티입니다.

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// 'collections' 내보내기를 통해 정의된 컬렉션을 Astro에 노출하세요.
export const collections = { blog };

이 함수는 다음 속성을 허용합니다.

`type`

타입: 'content' | 'data'
기본값: 'content'

Added in: astro@2.5.0

type은 컬렉션에 저장된 항목의 형식을 정의하는 문자열입니다.

'content' - Markdown (.md), MDX (.mdx), Markdoc (.mdoc)와 같은 콘텐츠 작성 형식
'data' - JSON (.json) 또는 YAML (.yaml)과 같은 데이터 전용 형식의 경우

`schema`

타입: ZodType | (context: SchemaContext) => ZodType

schema는 컬렉션에 대한 문서 프런트매터의 타입과 모양을 구성하는 선택적 Zod 객체입니다. 각 값은 Zod 유효성 검사기를 사용해야 합니다.

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`reference()`

타입: (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

Added in: astro@2.5.0

reference() 함수는 콘텐츠 구성에서 한 컬렉션에서 다른 컬렉션으로의 관계 또는 “reference”를 정의하는 데 사용됩니다. 이는 컬렉션 이름을 전달받고 콘텐츠 프런트매터 또는 데이터 파일에 지정된 항목 식별자의 유효성을 검사합니다.

이 예시에서는 authors 컬렉션에 대한 블로그 작성자의 참조와 동일한 blog 컬렉션에 대한 관련 게시물 배열을 정의합니다.

import { defineCollection, reference, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // `id`로 `authors` 컬렉션에서 단일 저자 참조
    author: reference('authors'),
    // `slug`의 `blog` 컬렉션에서 관련 게시물 배열을 참조하세요.
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

사용 예는 콘텐츠 컬렉션 안내서를 참조하세요.

`getCollection()`

타입: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]

getCollection()은 컬렉션 이름별로 콘텐츠 컬렉션 항목 목록을 검색하는 함수입니다.

기본적으로 컬렉션의 모든 항목을 반환하고 항목 속성별로 범위를 좁힐 수 있는 선택적 filter 함수를 허용합니다. 이를 통해 data 객체를 통해 id, slug 또는 프런트매터 값을 기반으로 컬렉션의 일부 항목만 쿼리할 수 있습니다.

---
import { getCollection } from 'astro:content';

// Get all `src/content/blog/` entries
const allBlogPosts = await getCollection('blog');

// 프런트매터에 `draft: true`가 포함된 게시물만 반환합니다.
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getEntry()`

Added in: astro@2.5.0

타입:

(collection: string, contentSlugOrDataId: string) => CollectionEntry<collection>
({ collection: string, id: string }) => CollectionEntry<collection>
({ collection: string, slug: string }) => CollectionEntry<collection>

getEntry()는 컬렉션 이름과 항목 id (type: 'data' 컬렉션의 경우) 또는 항목 slug (type: 'content' 컬렉션의 경우)로 단일 컬렉션 항목을 검색하는 함수입니다. getEntry()는 data, body, render() 속성에 액세스하기 위해 참조된 항목을 가져오는 데에도 사용할 수 있습니다.

---
import { getEntry } from 'astro:content';

// Get `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Get `src/content/captains/picard.yaml`
const picardProfile = await getEntry('captains', 'picard');

// `data.captain`이 참조하는 프로필 가져오기
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

컬렉션 항목 쿼리의 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getEntries()`

Added in: astro@2.5.0

타입:

(Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>
(Array<{ collection: string, slug: string }>) => Array<CollectionEntry<collection>>

getEntries()는 동일한 컬렉션에서 여러 컬렉션 항목을 검색하는 함수입니다. 이는 참조된 항목의 배열을 반환하여 관련 data, body, render() 속성에 액세스하는 데 유용합니다.

---
import { getEntries } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// `data.relatedPosts`에 의해 참조되는 관련 게시물 가져오기
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`getEntryBySlug()`

타입: (collection: string, slug: string) => Promise<CollectionEntry<collection>>

getEntryBySlug()는 컬렉션 이름과 항목 slug로 단일 컬렉션 항목을 검색하는 함수입니다.

---
import { getEntryBySlug } from 'astro:content';

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

`getDataEntryById()`

타입: (collection: string, id: string) => Promise<CollectionEntry<collection>>

Added in: astro@2.5.0

getDataEntryById()는 컬렉션 이름과 항목 id로 단일 컬렉션 항목을 검색하는 함수입니다.

---
import { getDataEntryById } from 'astro:content';
const picardProfile = await getDataEntryById('captains', 'picard');
---

컬렉션 항목 타입

getCollection(), getEntry(), getEntries()를 포함한 쿼리 함수는 각각 CollectionEntry 타입의 항목을 반환합니다. 이 타입은 astro:content에서 유틸리티로 사용할 수 있습니다.

import type { CollectionEntry } from 'astro:content';

CollectionEntry<TCollectionName> 타입은 다음 값을 갖는 객체입니다. TCollectionName은 쿼리 중인 컬렉션의 이름입니다 (예: CollectionEntry<'blog'>).

`id`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입 예시:

콘텐츠 컬렉션: 'entry-1.md' | 'entry-2.md' | ...
데이터 컬렉션: 'author-1' | 'author-2' | ...

src/content/[collection]에 상대적인 파일 경로를 사용하는 고유 ID입니다. 컬렉션 항목 파일 경로를 기반으로 가능한 모든 문자열 값을 열거합니다. type: 'content'로 정의된 컬렉션은 ID에 파일 확장자를 포함하지만 type: 'data'로 정의된 컬렉션은 포함하지 않습니다.

`collection`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입 예시: 'blog' | 'authors' | ...

항목이 위치한 src/content/ 아래의 최상위 폴더 이름입니다. 이는 스키마 및 쿼리 함수에서 컬렉션을 참조하는 데 사용되는 이름입니다.

`data`

사용 가능 대상: type: 'content' 및 type: 'data' 컬렉션
타입: CollectionSchema<TCollectionName>

컬렉션 스키마에서 추론된 프런트매터 속성의 객체입니다 (defineCollection() 참조를 확인하세요). 스키마가 구성되지 않은 경우 기본값은 any입니다.

`slug`

사용 가능 대상: type: 'content' 컬렉션 전용
타입 예시: 'entry-1' | 'entry-2' | ...

Markdown 또는 MDX 문서용 URL 지원 슬러그입니다. 파일 확장자가 없는 id가 기본값이지만 파일의 프런트매터에서 slug 속성을 설정하여 재정의할 수 있습니다.

`body`

사용 가능 대상: type: 'content' 컬렉션 전용
타입: string

Markdown 또는 MDX 문서의 컴파일되지 않은 원시 본문을 포함하는 문자열입니다.

`render()`

사용 가능 대상: type: 'content' 컬렉션 전용
타입: () => Promise<RenderedEntry>

렌더링을 위해 지정된 Markdown 또는 MDX 문서를 컴파일하는 기능입니다. 그러면 다음 속성이 반환됩니다.

<Content /> - Astro 파일에서 문서의 내용을 렌더링하는 데 사용되는 컴포넌트입니다.
headings - Markdown 및 MDX 가져오기에 대해 생성된 제목 목록, Astro의 getHeadings() 유틸리티 미러링.
remarkPluginFrontmatter - remark 또는 rehype 플러그인이 적용된 후 수정된 frontmatter 객체. any 타입으로 설정합니다.

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

사용 예시는 콘텐츠 컬렉션 안내서를 참조하세요.

기타 콘텐츠 컬렉션 타입

astro:content 모듈은 Astro 프로젝트에서 사용할 수 있도록 다음 타입도 내보냅니다.

`CollectionKey`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 모든 컬렉션 이름의 문자열 통합입니다. 이 타입은 모든 컬렉션 이름을 허용하는 일반 함수를 정의할 때 유용할 수 있습니다.

import type { CollectionKey, getCollection } from 'astro:content';

async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

`ContentCollectionKey`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'content' 컬렉션의 모든 이름에 대한 문자열 통합입니다.

`DataCollectionKey`

Added in: astro@3.1.0

src/content/config.* 파일에 정의된 type: 'data' 컬렉션의 모든 이름에 대한 문자열 통합입니다.

`SchemaContext`

defineCollection이 schema의 함수 모양을 위해 사용하는 context 객체입니다. 이 타입은 여러 컬렉션에 대해 재사용 가능한 스키마를 구축할 때 유용할 수 있습니다.

여기에는 다음 속성이 포함됩니다.

image - 콘텐츠 컬렉션에서 로컬 이미지를 사용할 수 있게 해주는 image() 스키마 도우미

import type { SchemaContext } from 'astro:content';

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});

미들웨어 (`astro:middleware`)

Added in: astro@2.6.0

미들웨어를 사용하면 페이지나 엔드포인트가 렌더링될 때마다 요청과 응답을 가로채고 동작을 동적으로 주입할 수 있습니다. 기능 및 사용 예시는 미들웨어 안내서 참조를 확인하세요.

`onRequest()`

타입: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

모든 페이지 또는 API 경로를 렌더링하기 전에 호출되는 src/middleware.js에서 내보낸 필수 함수입니다. 두 개의 인수 context 및 next()를 전달받습니다. onRequest()는 Response를 직접 반환하거나 next()를 호출하여 반환해야 합니다.

export function onRequest (context, next) {
    // 요청의 응답 데이터 가로채기
    // 선택적으로 응답을 변환합니다.
    // 응답을 직접 반환하거나 `next()` 호출 결과를 반환합니다.
    return next();
};

`context`

타입: APIContext

onRequest()의 첫 번째 인수는 컨텍스트 객체입니다. 이는 많은 Astro 전역 프로퍼티를 반영합니다.

컨텍스트 객체에 대해 더 자세히 알아보기 위해 엔드포인트 컨텍스트를 방문하세요.

`next()`

타입: (rewritePayload?: string | URL | Request) => Promise<Response>

onRequest()의 두 번째 인수는 체인의 모든 후속 미들웨어를 호출하고 Response를 반환하는 함수입니다. 예를 들어, 다른 미들웨어가 응답의 HTML 본문을 수정할 수 있으며 next()의 결과를 기다리면 미들웨어가 이러한 변경 사항에 응답할 수 있습니다.

Astro v4.13.0부터 next()는 새 렌더링 단계를 다시 트리거하지 않고 현재 요청을 리라이트하기 위해 문자열 형식의 선택적 URL 경로 매개 변수인 URL 또는 Request를 허용합니다.

`sequence()`

타입: (...handlers: MiddlewareHandler[]) => MiddlewareHandler

미들웨어 함수를 인수로 받아들이고 전달된 순서대로 실행하는 함수입니다.

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

export const onRequest = sequence(validation, auth, greeting);

`createContext()`

타입: (context: CreateContext) => APIContext

Added in: astro@2.8.0

Astro 미들웨어 onRequest() 함수에 전달될 APIContext를 생성하는 저수준 API입니다.

이 함수는 Astro 미들웨어를 프로그래밍 방식으로 실행하기 위해 통합/어댑터에서 사용할 수 있습니다.

`trySerializeLocals()`

타입: (value: unknown) => string

Added in: astro@2.8.0

모든 값을 받아들여 해당 값의 직렬화된 버전 (문자열)을 반환하려고 시도하는 저수준 API입니다. 값을 직렬화할 수 없으면 함수에서 런타임 오류가 발생합니다.

국제화 (`astro:i18n`)

Added in: astro@3.5.0

이 모듈은 프로젝트에 구성된 로케일을 사용하여 URL을 생성하는 데 도움이 되는 함수를 제공합니다.

i18n 라우터를 사용하여 프로젝트에 대한 경로를 생성하는 것은 페이지 경로에 영향을 주는 특정 구성 값에 따라 달라집니다. 이러한 함수를 사용하여 경로를 생성할 때 다음에 대한 개별 설정을 고려해야 합니다.

또한 defaultLocale에 대해 이러한 함수에서 반환된 URL은 i18n.routing 구성을 반영합니다.

기능 및 사용 예시는 i18n 라우팅 가이드를 참조하세요.

`getRelativeLocaleUrl()`

타입: (locale: string, path?: string, options?: GetLocaleOptions) => string

이 함수를 사용하여 로케일의 상대 경로를 검색합니다. 해당 로케일이 존재하지 않으면 Astro는 오류를 발생시킵니다.

---
getRelativeLocaleUrl("fr");
// /fr 반환
getRelativeLocaleUrl("fr", "");
// /fr 반환
getRelativeLocaleUrl("fr", "getting-started");
// /fr/getting-started 반환
getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// /blog/fr-ca/getting-started 반환
getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// /blog/fr_CA/getting-started 반환
---

`getAbsoluteLocaleUrl()`

타입: (locale: string, path: string, options?: GetLocaleOptions) => string

[site]의 값이 존재할 때 로케일의 절대 경로를 검색하려면 이 함수를 사용하세요. [site]가 구성되지 않은 경우 함수는 상대 URL을 반환합니다. 해당 로케일이 존재하지 않으면 Astro는 오류를 발생시킵니다.

---
// `site`가 `https://example.com`로 설정된 경우
getAbsoluteLocaleUrl("fr");
// https://example.com/fr 반환
getAbsoluteLocaleUrl("fr", "");
// https://example.com/fr 반환
getAbsoluteLocaleUrl("fr", "getting-started");
// https://example.com/fr/getting-started 반환
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
});
// https://example.com/blog/fr-ca/getting-started 반환
getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
});
// https://example.com/blog/fr_CA/getting-started 반환
---

`getRelativeLocaleUrlList()`

타입: (path?: string, options?: GetLocaleOptions) => string[]

모든 로케일에 대한 상대 경로 목록을 반환하려면 getRelativeLocaleUrl처럼 이 함수를 사용하세요.

`getAbsoluteLocaleUrlList()`

타입: (path?: string, options?: GetLocaleOptions) => string[]

모든 로케일에 대한 절대 경로 목록을 반환하려면 getAbsoluteLocaleUrl처럼 이 함수를 사용하세요.

`getPathByLocale()`

타입: (locale: string) => string

사용자 정의 로케일 경로가 구성된 경우 하나 이상의 codes와 연결된 path를 반환하는 함수입니다.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getPathByLocale("fr"); // "french" 반환
getPathByLocale("fr-CA"); // "french" 반환
---

`getLocaleByPath()`

타입: (path: string) => string

로케일 path와 연관된 code를 반환하는 함수입니다.

export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})

---
getLocaleByPath("french"); // 구성된 첫 번째 code이기 때문에 "fr"을 반환합니다.
---

`redirectToDefaultLocale()`

타입: (context: APIContext, statusCode?: ValidRedirectStatus) => Promise<Response>

Added in: astro@4.6.0

구성된 defaultLocale로 리디렉션되는 Response를 반환하는 함수입니다. 유효한 리디렉션 상태 코드를 선택적으로 허용합니다.

import { defineMiddleware } from "astro:middleware";
import { redirectToDefaultLocale } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  if (context.url.pathname.startsWith("/about")) {
    return next();
  } else {
    return redirectToDefaultLocale(context, 302);
  }
})

`redirectToFallback()`

타입: (context: APIContext, response: Response) => Promise<Response>

Added in: astro@4.6.0

자체 미들웨어에서 i18n.fallback 구성을 사용할 수 있게 해주는 함수입니다.

import { defineMiddleware } from "astro:middleware";
import { redirectToFallback } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  const response = await next();
  if (response.status >= 300) {
    return redirectToFallback(context, response)
  }
  return response;
})

`notFound()`

타입: (context: APIContext, response?: Response) => Promise<Response> | undefined

Added in: astro@4.6.0

다음과 같은 경우 라우팅 미들웨어에서 이 함수를 사용하여 404를 반환합니다.

현재 경로가 루트가 아닌 경우. 예를 들어 / 또는 /<base>
URL에 로케일이 포함되어 있지 않은 경우

Response가 전달되면 이 함수에서 내보낸 새 Response에는 원래 응답과 동일한 헤더가 포함됩니다.

import { defineMiddleware } from "astro:middleware";
import { notFound } from "astro:i18n";

export const onRequest = defineMiddleware((context, next) => {
  const pathNotFound = notFound(context);
  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
})

`middleware()`

타입: (options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler

Added in: astro@4.6.0

Astro i18n 미들웨어를 프로그래밍 방식으로 생성할 수 있는 함수입니다.

이는 기본 i18n 로직을 계속 사용하고 싶지만 웹 사이트에 몇 가지 예외만 추가하려는 경우에 유용합니다.

import { middleware } from "astro:i18n";
import { sequence, defineMiddleware } from "astro:middleware";

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // 응답을 해결한 후 사용자 정의 로직.
  // Astro i18n 미들웨어에서 오는 응답을 캐치할 수 있습니다.

  return response;
});

export const onRequest = sequence(customLogic, middleware({
  prefixDefaultLocale: true,
  redirectToDefaultLocale: false
}))

`requestHasLocale()`

타입: (context: APIContext) => boolean

Added in: astro@4.6.0

현재 URL에 구성된 로케일이 포함되어 있는지 확인합니다. 내부적으로 이 함수는 APIContext#url.pathname을 사용합니다.

import { defineMiddleware } from "astro:middleware";
import { requestHasLocale } from "astro:i18n";

export const onRequest = defineMiddleware(async (context, next) => {
  if (requestHasLocale(context)) {
    return next();
  }
  return new Response("Not found", { status: 404 });
})

내장 컴포넌트

Astro에는 프로젝트에 사용할 수 있는 여러 내장 컴포넌트가 포함되어 있습니다. 모든 내장 컴포넌트는 import {} from 'astro:components';를 통해 .astro 파일에서 사용할 수 있습니다.

ComponentProp 타입 유틸리티를 사용하여 이 컴포넌트의 Props를 참조할 수 있습니다.

`<Code />`

---
import { Code } from 'astro:components';
---
<!-- 구문은 일부 JavaScript 코드를 강조합니다. -->
<Code code={`const foo = 'bar';`} lang="js" />
<!-- 선택 사항: 테마를 맞춤설정합니다. -->
<Code code={`const foo = 'bar';`} lang="js" theme="dark-plus" />
<!-- 선택 사항: 단어 줄 바꿈을 활성화합니다. -->
<Code code={`const foo = 'bar';`} lang="js" wrap />
<!-- 선택 사항: 인라인 코드를 출력합니다. -->
<p>
  <Code code={`const foo = 'bar';`} lang="js" inline />
  will be rendered inline.
</p>
<!-- 선택 사항: defaultColor -->
<Code code={`const foo = 'bar';`} lang="js" defaultColor={false} />

이 컴포넌트는 빌드 시 코드 블록에 구문 강조 표시를 제공합니다 (클라이언트 측 JavaScript는 포함되지 않음). 이 컴포넌트는 Shiki에 의해 내부적으로 구동되며 모든 인기 있는 테마 및 언어를 지원합니다. 또한 사용자 정의 테마, 언어, transformers 및 기본 색상을 각각 theme, lang, transformers, defaultColor 속성에 전달하여 추가할 수 있습니다.

Transformers

Added in: astro@4.11.0

Shiki transformers는 transformers 속성에 배열로 전달하여 선택적으로 코드에 적용할 수 있습니다. Astro v4.14.0부터는 Shiki의 meta 속성에 문자열을 제공하여 트랜스포머에 옵션을 전달할 수도 있습니다.

transformers는 단지 클래스만 적용하며 코드 블록의 요소를 대상으로 지정하려면 자체 CSS 규칙을 제공해야 합니다.

---
import { transformerNotationFocus, transformerMetaHighlight } from '@shikijs/transformers'
import { Code } from 'astro:components'
const code = `const foo = 'hello'
const bar = ' world'
console.log(foo + bar) // [!code focus]
`
---
<Code
  code={code}
  lang="js"
  transformers={[transformerMetaHighlight()]}
  meta="{1,3}" />

  <style is:global>
    pre.has-focused .line:not(.focused) {
      filter: blur(1px);
    }
  </style>

`<Fragment />`

추가 래핑 요소 없이 HTML 콘텐츠를 렌더링하기 위해 set:* 지시어와 함께 사용되는 컴포넌트:

---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

Astro 구문의 프래그먼트 사용에 대해 자세히 알아보세요.

`<Prism />`

Prism 구문 강조 컴포넌트를 사용하려면 먼저 @astrojs/prism 패키지를 설치하세요.

npm install @astrojs/prism

pnpm add @astrojs/prism

yarn add @astrojs/prism

---
import { Prism } from '@astrojs/prism';
---
<Prism lang="js" code={`const foo = 'bar';`} />

이 컴포넌트는 Prism의 CSS 클래스를 적용하여 코드 블록에 대한 언어별 구문 강조를 제공합니다. 구문 강조를 표시하려면 Prism CSS 스타일시트를 제공 (또는 자신만의 스타일시트)해야합니다! 자세한 내용은 Prism 구성 섹션을 참조하세요.

언어에 해당하는 별칭을 찾을 수 있도록 Prism이 지원하는 언어 목록을 참조하세요. 그리고 lang="astro"를 사용하여 Astro 코드 블록을 표시할 수도 있습니다!

`<Image />`

---
// Image 컴포넌트 및 이미지 가져오기
import { Image } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 1600x900의 이미지
---

<!-- Image 컴포넌트에서는 'alt'가 필수입니다. -->
<Image src={myImage} alt="A description of my image." />

<!-- 결과 -->
<!-- 이미지가 최적화되었으며 적절한 속성이 적용되었습니다. -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

속성

src (필수)
alt (필수)
width 및 height (public/ 및 원격 이미지를 사용하는 경우 필수)
format
quality
densities
widths

위 속성 외에도 <Image /> 컴포넌트는 HTML <img> 태그에서 허용하는 모든 속성을 허용합니다.

이미지 안내서에서 자세한 내용을 확인하세요.

`<Picture />`

Added in: astro@3.3.0

다양한 형식 및/또는 크기로 반응형 이미지를 표시하려면 내장된 <Picture /> Astro 컴포넌트를 사용하세요.

---
import { Picture } from 'astro:assets';
import myImage from "../assets/my_image.png"; // 1600x900의 이미지
---

<!-- Picture 컴포넌트에서는 'alt'가 필수입니다. -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- 결과 -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="A description of my image."
  />
</picture>

이미지 안내서에서 자세한 내용을 확인하세요.

속성

<Picture />는 <Image /> 컴포넌트의 모든 속성과 함께 다음을 허용합니다.

`formats`

<source> 태그에 사용할 이미지 형식의 배열입니다. 기본적으로 ['webp']로 설정되어 있습니다.

`fallbackFormat`

<img> 태그에 대한 대체 값으로 사용할 형식입니다. 정적 이미지의 경우 기본값은 .png, 애니메이션 이미지의 경우 .gif, SVG 파일의 경우 .svg입니다.

`pictureAttributes`

<picture> 태그에 추가될 속성의 객체입니다. 이 속성을 사용하여 외부 <picture> 요소 자체에 속성을 적용합니다. <Picture /> 컴포넌트에 직접 적용된 속성은 이미지 변환에 사용되는 속성을 제외하고 내부 <img> 요소에 적용됩니다.

`<Content />`

콘텐츠 컬렉션 항목의 콘텐츠를 렌더링하는 데 사용되는 일반 컴포넌트입니다.

먼저 getCollection() 또는 getEntry()를 사용하여 하나 이상의 항목을 쿼리합니다. 그런 다음 entry.render() 함수는 .astro 파일 템플릿에 사용할 <Content /> 컴포넌트를 반환할 수 있습니다.

---
import { getEntry } from 'astro:content';
const entry = await getEntry('blog', 'post-1');
const { Content } = await entry.render();
---
<p>Published on: {entry.data.published.toDateString()}</p>
<Content />

`<ViewTransitions />`

Added in: astro@2.9.0

원하는 모든 페이지의 <head>에 <ViewTransitions /> 라우팅 컴포넌트를 가져오고 추가하여 개별 페이지에서 view transitions를 사용하도록 선택합니다.

---
import { ViewTransitions } from 'astro:transitions';
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

페이지 요소 및 컴포넌트에 라우터 제어 및 전환 지시어 추가 방법에 대해 자세히 알아보세요.

`<Debug />`

---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

이 컴포넌트는 JavaScript 없이 클라이언트 측에서 값을 검사하는 방법을 제공합니다.

기여하기

커뮤니티

API 참조

Astro global

Astro.glob()

Markdown 파일

Astro 파일

기타 파일

Astro.props

Astro.params

Astro.request

Astro.response

Astro.cookies

get

has

set

delete

merge

headers

AstroCookie

value

json

number

boolean

AstroCookieGetOptions

decode

AstroCookieSetOptions

domain

expires

httpOnly

maxAge

path

sameSite

secure

encode

Astro.redirect()

Astro.rewrite()

Astro.url

Astro.clientAddress

Astro.site

Astro.generator

Astro.slots

Astro.slots.has()

Astro.slots.render()

Astro.self

Astro.locals

Astro.preferredLocale

Astro.preferredLocaleList

Astro.currentLocale

엔드포인트 Context

context.params

context.props

context.request

context.cookies

context.url

context.clientAddress

context.site

context.generator

context.redirect()

context.rewrite()

context.locals

getStaticPaths()

params

props를 사용한 데이터 전달

paginate()

페이지네이션의 page prop

page.data

page.start

page.end

page.size

page.total

page.currentPage

page.lastPage

page.url.current

page.url.prev

page.url.next

page.url.first

page.url.last

import.meta

이미지 (astro:assets)

getImage()

콘텐츠 컬렉션 (astro:content)

`Astro` global

`Astro.glob()`

`Astro.props`

`Astro.params`

`Astro.request`

`Astro.response`

`Astro.cookies`

`get`

`has`

`set`

`delete`

`merge`

`headers`

`AstroCookie`

`value`

`json`

`number`

`boolean`

`AstroCookieGetOptions`

`decode`

`AstroCookieSetOptions`

`domain`

`expires`

`httpOnly`

`maxAge`

`path`

`sameSite`

`secure`

`encode`

`Astro.redirect()`

`Astro.rewrite()`

`Astro.url`

`Astro.clientAddress`

`Astro.site`

`Astro.generator`

`Astro.slots`

`Astro.slots.has()`

`Astro.slots.render()`

`Astro.self`

`Astro.locals`

`Astro.preferredLocale`

`Astro.preferredLocaleList`

`Astro.currentLocale`

`context.params`

`context.props`

`context.request`

`context.cookies`

`context.url`

`context.clientAddress`

`context.site`

`context.generator`

`context.redirect()`

`context.rewrite()`

`context.locals`

`getStaticPaths()`

`params`

`props`를 사용한 데이터 전달

`paginate()`

페이지네이션의 `page` prop

`page.data`

`page.start`

`page.end`

`page.size`

`page.total`

`page.currentPage`

`page.lastPage`

`page.url.current`

`page.url.prev`

`page.url.next`

`page.url.first`

`page.url.last`

`import.meta`

이미지 (`astro:assets`)

`getImage()`

콘텐츠 컬렉션 (`astro:content`)

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`