컨텐츠로 건너뛰기

Astro 렌더링 컨텍스트

페이지를 렌더링할 때 Astro는 현재 렌더링에 특정한 런타임 API를 제공합니다. 여기에는 현재 페이지 URL과 같은 유용한 정보와 다른 페이지로 리디렉션하는 등의 작업을 수행하는 API가 포함됩니다.

.astro 컴포넌트에서 이 컨텍스트는 Astro 전역 객체에서 사용할 수 있습니다. 엔드포인트 함수도 이 동일한 컨텍스트 객체를 첫 번째 인수로 사용하여 호출되며, 그 속성은 Astro 전역 속성을 반영합니다.

일부 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있거나 미리 렌더링된 페이지에서 기능이 제한될 수 있습니다.

Astro 전역 객체는 모든 .astro 파일에서 사용할 수 있습니다. 정적 또는 라이브 서버 엔드포인트를 제공하려면 엔드포인트 함수에서, 페이지 또는 엔드포인트가 렌더링될 때 동작을 삽입하려면 미들웨어에서 context 객체를 사용합니다.

컨텍스트 객체

섹션 제목: 컨텍스트 객체

다음 프로퍼티는 Astro 전역(예: Astro.props, Astro.redirect())에서 사용할 수 있으며 엔드포인트 함수 및 미들웨어에 전달되는 컨텍스트 객체(예: context.props, context.redirect())에서도 사용할 수 있습니다.

props

섹션 제목: props

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 객체에는 정적 경로를 렌더링할 때 getStaticPaths()에서 전달된 모든 props도 포함됩니다.

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


const { id } = Astro.params;
const { author } = Astro.props;
---

더 보기: props로 데이터 전달

params

섹션 제목: params

params는 요청과 일치하는 동적 경로 세그먼트의 값을 포함하는 객체입니다. 해당 키는 페이지 또는 엔드포인트 파일 경로의 매개변수와 일치해야 합니다.

정적 빌드에서는 동적 경로를 미리 렌더링하는데 사용되는 getStaticPaths()가 반환하는 params가 됩니다.

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는 동적 경로 패턴의 경로 세그먼트와 일치하는 임의의 값일 수 있습니다.

src/pages/posts/[id].astro
---
import { getPost } from '../api';


const post = await getPost(Astro.params.id);


// ID로 게시물을 찾을 수 없는 경우
if (!post) {
  return Astro.redirect("/404")
}
---
<html>
  <h1>{post.name}</h1>
</html>

더 보기: params

url

섹션 제목: url

타입: URL

Added in: astro@1.0.0

url은 현재 request.url 값으로 구성된 URL 객체입니다. pathname 및 origin과 같은 요청 URL의 개별 속성과 상호 작용할 때 유용합니다.

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

개발 모드에서 url은 localhost URL이 됩니다. 사이트를 빌드할 때 미리 렌더링된 경로는 site 및 base 옵션에 기반한 URL을 받게 됩니다. site가 구성되지 않은 경우 미리 렌더링된 페이지도 빌드 중에 localhost URL을 받게 됩니다.

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

url을 new URL()의 인자로 전달하여 새 URL을 만들 수도 있습니다.

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

site

섹션 제목: site

타입: URL | undefined

site는 Astro 구성의 site에서 만든 URL을 반환합니다. Astro 구성에서 site에 대한 값을 설정하지 않은 경우 undefined를 반환합니다.

src/pages/index.astro
<link
    rel="alternate"
    type="application/rss+xml"
    title="Your Site's Title"
    href={new URL("rss.xml", Astro.site)}
/>

clientAddress

섹션 제목: clientAddress

타입: string

Added in: astro@1.0.0

clientAddress는 요청의 IP 주소를 지정합니다. 이 속성은 요청 시 렌더링되는 경로에만 사용할 수 있으며 미리 렌더링된 페이지에는 사용할 수 없습니다.

src/pages/ip-address.astro
---
export const prerender = false; // 'server' 모드에서는 필요하지 않음
---


<div>Your IP address is: <span class="address">{Astro.clientAddress}</span></div>

isPrerendered

섹션 제목: isPrerendered

타입: boolean

Added in: astro@5.0.0

현재 페이지가 미리 렌더링된 페이지인지 여부를 나타내는 부울입니다.

이 속성을 사용하여 미들웨어에서 조건부 로직을 실행할 수 있습니다(예: 미리 렌더링된 페이지의 헤더에 액세스하지 않도록 하기 위해).

generator

섹션 제목: generator

타입: string

Added in: astro@1.0.0

generator는 프로젝트가 실행 중인 Astro의 현재 버전을 제공합니다. 현재 사용 중인 Astro 버전과 함께 <meta name="generator"> 태그를 추가하는 편리한 방법입니다. 이 태그는 "Astro v5.x.x" 형식을 따릅니다.

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

request

섹션 제목: request

타입: Request

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

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

response

섹션 제목: response

타입: ResponseInit & { readonly headers: Headers }

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=/;');
---

redirect()

섹션 제목: redirect()

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

Added in: astro@1.5.0

redirect()는 다른 페이지로 리디렉션할 수 있는 Response 객체를 반환하며, 선택적으로 HTTP 응답 상태 코드를 두 번째 파라미터로 제공합니다.

리디렉션이 발생하려면 하위 컴포넌트가 아닌 페이지가 Astro.redirect()의 결과를 반환해야 합니다.

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

요청 시 렌더링되는 경로에서는 리디렉션 시 사용자 지정 상태 코드를 설정하는 것이 지원됩니다. 지정하지 않으면 리디렉션은 302 상태 코드와 함께 제공됩니다.

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

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


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


// 사용자가 로그인하지 않았다면 로그인 페이지로 리디렉션합니다.
if (!isLoggedIn(cookie)) {
  return Astro.redirect('/login');
}
---


<p>User information</p>

rewrite()

섹션 제목: rewrite()

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

Added in: astro@4.13.0

rewrite()를 사용하면 브라우저를 새 페이지로 리디렉션하지 않고 다른 URL 또는 경로의 콘텐츠를 제공할 수 있습니다.

이 메서드는 경로 위치에 대한 문자열, URL 또는 Request를 받습니다.

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

src/pages/index.astro
---
return Astro.rewrite("/login")
---

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

src/pages/blog/index.astro
---
return Astro.rewrite(new URL("../", Astro.url))
---

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

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

locals

섹션 제목: locals

Added in: astro@2.4.0

locals는 요청의 수명 주기 동안 임의의 정보를 저장하고 액세스하는 데 사용되는 객체입니다. Astro.locals는 미들웨어가 설정한 context.locals 객체의 모든 값을 포함하는 객체입니다. 이를 사용하여 .astro 파일에서 미들웨어가 반환한 데이터에 액세스할 수 있습니다.

미들웨어 함수는 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();
}

Astro 컴포넌트와 API 엔드포인트는 렌더링할 때 locals에서 값을 읽을 수 있습니다:

src/pages/Orders.astro
---
const title = Astro.locals.title;
---
<h1>{title}</h1>

preferredLocale

섹션 제목: preferredLocale

타입: string | undefined

Added in: astro@3.5.0

preferredLocale은 방문자의 브라우저 언어 기본 설정과 사이트에서 지원하는 로케일 간에 가장 잘 일치하는 것을 찾기 위해 계산된 값입니다.

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

이 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있으며 미리 렌더링된 정적 페이지에는 사용할 수 없습니다.

preferredLocaleList

섹션 제목: preferredLocaleList

타입: string[] | undefined

Added in: astro@3.5.0

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

브라우저에서 요청한 언어가 로케일 배열에 없으면 값은 []가 됩니다. 이는 방문자가 선호하는 로케일을 지원하지 않을 때 발생합니다.

브라우저에 기본 설정 언어가 지정되지 않은 경우 이 값은 i18n.locales가 되며, 기본 설정이 없는 방문자에게는 지원되는 모든 로케일이 동일하게 기본 설정된 것으로 간주됩니다.

이 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있으며 미리 렌더링된 정적 페이지에는 사용할 수 없습니다.

currentLocale

섹션 제목: currentLocale

타입: string | undefined

Added in: astro@3.5.6

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

getActionResult()

섹션 제목: getActionResult()

타입: (action: TAction) => ActionReturnType<TAction> | undefined

Added in: astro@4.15.0

getActionResult()는 액션 제출의 결과를 반환하는 함수입니다. 이 함수는 액션 함수(예: actions.logout)를 인수로 받아 제출이 수신되면 data 또는 error 객체를 반환합니다. 그렇지 않으면 undefined을 반환합니다.

src/pages/index.astro
---
import { actions } from 'astro:actions';


const result = Astro.getActionResult(actions.logout);
---


<form action={actions.logout}>
  <button type="submit">Log out</button>
</form>
{result?.error && <p>Failed to log out. Please try again.</p>}

callAction()

섹션 제목: callAction()

Added in: astro@4.15.0

callAction()은 Astro 컴포넌트에서 액션 핸들러를 직접 호출하는 데 사용되는 함수입니다. 이 함수는 액션 함수를 첫 번째 인수로 받고(예: actions.logout), 액션이 수신하는 모든 입력을 두 번째 인수로 받습니다. 이 함수는 액션의 결과를 프로미스로 반환합니다.

src/pages/index.astro
---
import { actions } from 'astro:actions';


const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---

routePattern

섹션 제목: routePattern

타입: string

Added in: astro@5.0.0

현재 페이지 또는 경로를 생성하는 경로 패턴입니다. 파일 기반 라우팅에서는 경로를 생성하는 데 사용되는 프로젝트의 파일 경로와 유사합니다. 통합이 프로젝트의 경로를 생성하는 경우 context.routePattern은 injectRoute.pattern의 값과 동일합니다.

이 값은 선행 슬래시로 시작하며 파일 확장자가 없는 src/pages/ 폴더를 기준으로 한 페이지 컴포넌트의 경로와 유사하게 표시됩니다.

예를 들어, src/pages/en/blog/[slug].astro 파일은 routePattern에 대해 /en/blog/[slug]를 반환합니다. 해당 파일에 의해 생성된 사이트의 모든 페이지(예: /en/blog/post-1/, /en/blog/post-2/ 등)는 routePattern에 대해 동일한 값을 공유합니다. index.* 경로의 경우, 경로 패턴에 “index.”라는 단어가 포함되지 않습니다. 예를 들어 src/pages/index.astro는 /를 반환합니다.

이 속성을 사용하여 컴포넌트를 렌더링하는 경로를 파악할 수 있습니다. 이를 통해 유사하게 생성된 페이지 URL을 함께 타겟팅하거나 분석할 수 있습니다. 예를 들어 특정 정보를 조건부로 렌더링하거나 어떤 경로가 느린지에 대한 메트릭을 수집하는 데 사용할 수 있습니다.

cookies

섹션 제목: cookies

타입: AstroCookies

Added in: astro@1.4.0

cookies에는 요청 시 렌더링되는 경로에 대한 쿠키를 읽고 조작하기 위한 유틸리티가 포함되어 있습니다.

쿠키 유틸리티

섹션 제목: 쿠키 유틸리티
cookies.get()
섹션 제목: cookies.get()

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

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

cookies.has()
섹션 제목: cookies.has()

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

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

cookies.set()
섹션 제목: cookies.set()

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

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

cookies.delete()
섹션 제목: cookies.delete()

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

만료일을 과거(유닉스 시간 기준 0)로 설정하여 쿠키를 무효화합니다.

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

cookies.merge()
섹션 제목: cookies.merge()

타입: (cookies: AstroCookies) => void

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

cookies.headers()
섹션 제목: cookies.headers()

타입: () => Iterator<string>

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

AstroCookie 타입

섹션 제목: AstroCookie 타입

Astro.cookies.get()을 통해 쿠키를 가져올 때 반환되는 타입입니다. 다음과 같은 속성을 가집니다:

value
섹션 제목: value

타입: string

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

json
섹션 제목: json

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

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

number
섹션 제목: number

타입: () => number

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

boolean
섹션 제목: boolean

타입: () => boolean

쿠키 값을 부울로 변환합니다.

AstroCookieGetOptions

섹션 제목: AstroCookieGetOptions

Added in: astro@4.1.0

AstroCookieGetOption 인터페이스를 사용하면 쿠키를 받을 때 옵션을 지정할 수 있습니다.

decode
섹션 제목: decode

타입: (value: string) => string

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

AstroCookieSetOptions

섹션 제목: AstroCookieSetOptions

Added in: astro@4.1.0

AstroCookieSetOptions는 쿠키를 설정할 때 Astro.cookies.set()에 전달하여 쿠키 직렬화 방식을 사용자 지정할 수 있는 객체입니다.

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.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()은 통계적으로 분석할 수 없으므로 변수나 보간하는 문자열을 받을 수 없습니다. (해결 방법은 가져오기 가이드를 참조하세요.) 이는 Astro.glob()이 Vite의 import.meta.glob()의 래퍼이기 때문입니다.

Markdown 파일
섹션 제목: 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 전용) 원시 Markdown 파일 콘텐츠, 레이아웃 HTML 및 YAML 프런트매터 제외 */
  rawContent(): string;
  /** (Markdown 전용) HTML로 컴파일된 Markdown 파일, 레이아웃 HTML 제외 */
  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 파일

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

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

기타 파일에는 다양한 인터페이스가 있을 수 있지만 Astro.glob()은 인식할 수 없는 파일 형식이 정확히 무엇인지 알고 있는 경우 TypeScript 제네릭을 허용합니다.

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

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

GitHub Issue 생성

우리에게 가장 빨리 문제를 알려줄 수 있어요.

커뮤니티