컨텐츠로 건너뛰기

API 참조

Astro global

섹션 제목: Astro global

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

Astro.glob()

섹션 제목: Astro.glob()

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

src/components/my-component.astro
---
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()의 래퍼이기 때문입니다..

Markdown 파일

섹션 제목: Markdown 파일

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

export interface MarkdownInstance<T extends Record<string, any>> {
  /* 이 파일의 YAML 프런트매터에 지정된 모든 데이터 */
  frontmatter: T;
  /* 이 파일의 파일 경로 */
  file: string;
  /* 이 파일의 렌더링된 경로 */
  url: string | undefined;
  /* 이 파일의 내용을 렌더링하는 Astro 컴포넌트 */
  Content: AstroComponent;
  /* 이 파일의 h1...h6 요소 배열을 반환하는 함수 */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
}

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 파일

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

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

기타 파일

섹션 제목: 기타 파일

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

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

Astro.props

섹션 제목: Astro.props

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

src/components/Heading.astro
---
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>
src/pages/index.astro
---
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />
Markdown 및 MDX 레이아웃이 props를 처리하는 방법에 대해 자세히 알아보세요.
props에 대한 TypeScript 타입 정의를 추가하는 방법을 알아보세요.

Astro.params

섹션 제목: Astro.params

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

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

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

src/pages/posts/[id].astro
---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}


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

함께 보기: params

Astro.request

섹션 제목: Astro.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

섹션 제목: Astro.response

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

섹션 제목: Astro.cookies

Added in: astro@1.4.0

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

get
섹션 제목: get

타입: (key: string, options?: CookieGetOptions) => AstroCookie

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

has
섹션 제목: has

타입: (key: string) => boolean

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

set
섹션 제목: set

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

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

delete
섹션 제목: delete

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

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

headers
섹션 제목: headers

타입: () => Iterator<string>

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

AstroCookie

섹션 제목: AstroCookie

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

value
섹션 제목: value

타입: string | undefined

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

json
섹션 제목: json

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

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

number
섹션 제목: number

타입: () => number

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

boolean
섹션 제목: boolean

타입: () => boolean

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

CookieGetOptions

섹션 제목: CookieGetOptions

Added in: astro@4.1.0

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

decode
섹션 제목: decode

타입: (value: string) => string

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

CookieSetOptions

섹션 제목: CookieSetOptions

Added in: astro@4.1.0

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

domain
섹션 제목: domain

타입: string

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

expires
섹션 제목: expires

타입: Date

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

httpOnly
섹션 제목: httpOnly

타입: boolean

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

maxAge
섹션 제목: maxAge

타입: number

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

path
섹션 제목: path

타입: string

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

sameSite
섹션 제목: sameSite

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

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

secure
섹션 제목: secure

타입: boolean

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

encode
섹션 제목: encode

타입: (value: string) => string

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

Astro.redirect()

섹션 제목: Astro.redirect()

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

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

다음 예시에서는 기본 HTTP 응답 상태 코드 302를 사용하여 사용자를 로그인 페이지로 리디렉션합니다.

src/pages/account.astro
---
import { isLoggedIn } from '../utils';


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


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

Astro.canonicalURL

섹션 제목: Astro.canonicalURL

현재 페이지의 canonical URL입니다.

Astro.url

섹션 제목: Astro.url

Added in: astro@1.0.0-rc

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

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

<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을 생성하는 데 사용할 수도 있습니다.

src/pages/index.astro
---
// 예: 프로덕션 도메인을 사용하여 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

섹션 제목: Astro.clientAddress

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

섹션 제목: Astro.site

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

Astro.generator

섹션 제목: Astro.generator

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

Astro.slots.has()

섹션 제목: Astro.slots.has()

타입: (slotName: string) => boolean

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

src/pages/index.astro
---
---
<slot />


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

Astro.slots.render()

섹션 제목: 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을 대문자로 변환하고 이를 기본 슬롯에 전달합니다.

src/components/Shout.astro
---
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 매개변수를 받습니다:

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


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

Astro.self

섹션 제목: Astro.self

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

NestedList.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

섹션 제목: Astro.locals

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

src/pages/Orders.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

섹션 제목: Astro.preferredLocale

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

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

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

Astro.preferredLocaleList

섹션 제목: Astro.preferredLocaleList

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

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

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

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

Astro.currentLocale

섹션 제목: Astro.currentLocale

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

엔드포인트 Context

섹션 제목: 엔드포인트 Context

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

endpoint.json.ts
import type { APIContext } from 'astro';


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

context.params

섹션 제목: context.params

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

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

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

src/pages/posts/[id].json.ts
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

섹션 제목: context.props

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

src/pages/posts/[id].json.ts
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

섹션 제목: context.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

섹션 제목: context.cookies

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

함께 보기: Astro.cookies

context.url

섹션 제목: context.url

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

함께 보기: Astro.url

context.clientAddress

섹션 제목: context.clientAddress

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

import type { APIContext } from 'astro';


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

함께 보기: Astro.clientAddress

context.site

섹션 제목: context.site

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

함께 보기: Astro.site

context.generator

섹션 제목: context.generator

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

src/pages/site-info.json.ts
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()

섹션 제목: context.redirect()

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

import type { APIContext } from 'astro';


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

함께 보기: Astro.redirect()

context.locals

섹션 제목: context.locals

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

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

src/middleware.ts
import type { MiddlewareHandler } from 'astro';


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

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

src/pages/hello.ts
import type { APIContext } from 'astro';


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

함께 보기: Astro.locals

getStaticPaths()

섹션 제목: getStaticPaths()

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

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

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

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

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

params

섹션 제목: 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를 사용한 데이터 전달

생성된 각 페이지에 추가 데이터를 전달하려면 반환된 모든 경로 객체에 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()

섹션 제목: 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 - 페이지당 표시되는 항목 수
  • params - 동적 경로 생성을 위한 추가 매개변수 보내기
  • props - 각 페이지에서 사용할 수 있도록 추가 props 보내기

페이지네이션의 page prop

섹션 제목: 페이지네이션의 page prop

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

page.data
섹션 제목: page.data

타입: Array

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

page.start
섹션 제목: page.start

타입: number

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

page.end
섹션 제목: page.end

타입: number

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

page.size
섹션 제목: page.size

타입: number

페이지당 항목 수입니다.

page.total
섹션 제목: page.total

타입: number

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

page.currentPage
섹션 제목: page.currentPage

타입: number

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

page.lastPage
섹션 제목: page.lastPage

타입: number

총 페이지 수입니다.

page.url.current
섹션 제목: page.url.current

타입: string

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

page.url.prev
섹션 제목: page.url.prev

타입: string | undefined

이전 페이지의 URL을 가져옵니다(1페이지인 경우 undefined).

page.url.next
섹션 제목: page.url.next

타입: string | undefined

다음 페이지의 URL을 가져옵니다(더 이상 페이지가 없으면 undefined).

import.meta

섹션 제목: 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)

섹션 제목: 이미지 (astro:assets)

getImage()

섹션 제목: getImage()

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>

다음 속성을 가진 객체를 반환합니다.

{
  options: {...} // 전달된 원래 매개변수
  src: "https//..." // 생성된 이미지의 경로
  attributes: {...} // 이미지를 렌더링하는 데 필요한 추가 HTML 속성 (width, height, style, 등)
}

콘텐츠 컬렉션 (astro:content)

섹션 제목: 콘텐츠 컬렉션 (astro:content)

Added in: astro@2.0.0

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

defineCollection()

섹션 제목: defineCollection()

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

src/content/config.ts
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

섹션 제목: type

Added in: astro@2.5.0

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

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

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

schema

섹션 제목: schema

타입: TSchema extends ZodType

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

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

reference()

섹션 제목: reference()

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

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()

섹션 제목: 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()

섹션 제목: getEntry()

Added in: astro@2.5.0

Types:

  • (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()

섹션 제목: getEntries()

Added in: astro@2.5.0

Types:

  • (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()

섹션 제목: getEntryBySlug()

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

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

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


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

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

컬렉션 항목 타입

섹션 제목: 컬렉션 항목 타입

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

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

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

id

섹션 제목: 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

섹션 제목: collection

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

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

data

섹션 제목: data

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

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

slug

섹션 제목: slug

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

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

body

섹션 제목: body

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

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

render()

섹션 제목: render()

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

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

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


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

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

기타 콘텐츠 컬렉션 타입

섹션 제목: 기타 콘텐츠 컬렉션 타입

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

CollectionKey

섹션 제목: CollectionKey

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

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


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

ContentCollectionKey

섹션 제목: ContentCollectionKey

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

DataCollectionKey

섹션 제목: DataCollectionKey

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

SchemaContext

섹션 제목: SchemaContext

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

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

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)

섹션 제목: 미들웨어 (astro:middleware)

Added in: astro@2.6.0

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

onRequest()

섹션 제목: onRequest()

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

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

next()

섹션 제목: next()

Request의 Response를 가로채거나 (읽고 수정) 체인의 “next” 미들웨어를 호출하고 Response를 반환하는 함수입니다. 예를 들어 이 함수는 응답의 HTML 본문을 수정할 수 있습니다.

이는 onRequest()의 선택적 인수이며 미들웨어에서 반환하는 필수 Response를 제공할 수 있습니다.

sequence()

섹션 제목: sequence()

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

src/middleware.js
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()

섹션 제목: createContext()

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

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

trySerializeLocals()

섹션 제목: trySerializeLocals()

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

국제화 (astro:i18n)

섹션 제목: 국제화 (astro:i18n)

Added in: astro@3.5.0

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

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

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

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

getRelativeLocaleUrl()

섹션 제목: getRelativeLocaleUrl()

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()

섹션 제목: getAbsoluteLocaleUrl()

getAbsoluteLocaleUrl(locale: string, path: string, options?: GetLocaleOptions): string

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

src/pages/index.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()

섹션 제목: getRelativeLocaleUrlList()

getRelativeLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]

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

getAbsoluteLocaleUrlList()

섹션 제목: getAbsoluteLocaleUrlList()

getAbsoluteLocaleUrlList(path?: string, options?: GetLocaleOptions): string[]

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

getPathByLocale()

섹션 제목: getPathByLocale()

getPathByLocale(locale: string): string

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

astro.config.mjs
export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})
src/pages/index.astro
---
getPathByLocale("fr"); // "french" 반환
getPathByLocale("fr-CA"); // "french" 반환
---

getLocaleByPath

섹션 제목: getLocaleByPath

getLocaleByPath(path: string): string

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

astro.config.mjs
export default defineConfig({
  i18n: {
    locales: ["es", "en", {
      path: "french",
      codes: ["fr", "fr-BR", "fr-CA"]
    }]
  }
})
src/pages/index.astro
---
getLocaleByPath("french"); // 구성된 첫 번째 code이기 때문에 "fr"을 반환합니다.
---

redirectToDefaultLocale()

섹션 제목: redirectToDefaultLocale()

redirectToDefaultLocale(context: APIContext, statusCode?: ValidRedirectStatus): Promise<Response>

Added in: astro@4.6.0

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

middleware.js
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()

섹션 제목: redirectToFallback()

redirectToFallback(context: APIContext, response: Response): Promise<Response>

Added in: astro@4.6.0

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

middleware.js
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()

섹션 제목: notFound()

notFound(context: APIContext, response: Response): Promise<Response>

Added in: astro@4.6.0

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

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

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

middleware.js
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()

섹션 제목: middleware()

middleware(options: { prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean })

Added in: astro@4.6.0

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

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

middleware.js
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()

섹션 제목: requestHasLocale()

requestHasLocale(context: APIContext): boolean

Added in: astro@4.6.0

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

middleware.js
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 파일에서 사용할 수 있습니다.

<Code />

섹션 제목: &lt;Code /&gt;
---
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>

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

<Fragment />

섹션 제목: &lt;Fragment /&gt;

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

src/components/SetHtml.astro
---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />

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

<Prism />

섹션 제목: &lt;Prism /&gt;

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

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

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

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

<Image />

섹션 제목: &lt;Image /&gt;
src/components/MyComponent.astro
---
// 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 />

섹션 제목: &lt;Picture /&gt;

Added in: astro@3.3.0

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

src/pages/index.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
섹션 제목: formats

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

fallbackFormat
섹션 제목: fallbackFormat

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

pictureAttributes
섹션 제목: pictureAttributes

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

<Content />

섹션 제목: &lt;Content /&gt;

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

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

src/pages/render-example.astro
---
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 />

섹션 제목: &lt;ViewTransitions /&gt;

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

src/pages/index.astro
---
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 />

섹션 제목: &lt;Debug /&gt;
---
import { Debug } from 'astro:components';
const serverObject = {
  a: 0,
  b: "string",
  c: {
    nested: "object"
  }
}
---
<Debug {serverObject} />

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