Astro 렌더링 컨텍스트

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

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

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

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

컨텍스트 객체

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

`props`

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

Astro.props
context.props

---
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;
---

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로 데이터 전달

`params`

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

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

Astro.params
context.params

---
export function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } },
    { params: { id: '3' } }
  ];
}
const { id } = Astro.params;
---
<h1>{id}</h1>

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

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

추가된 버전: 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을 받게 됩니다.

<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을 만들 수도 있습니다.

---
// 예시: 프로덕션 도메인을 사용하여 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`

타입: URL | undefined

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

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

`clientAddress`

타입: string

추가된 버전: astro@1.0.0

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

Astro.clientAddress
context.clientAddress

---
export const prerender = false; // 'server' 모드에서는 필요하지 않음
---

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

export const prerender = false; // 'server' 모드에서는 필요하지 않음
import type { APIContext } from 'astro';

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

`isPrerendered`

타입: boolean

추가된 버전: astro@5.0.0

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

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

`generator`

타입: string

추가된 버전: astro@1.0.0

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

Astro.generator
context.generator

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

import type { APIContext } from 'astro';

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

`request`

타입: Request

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

Astro.request
context.request

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

import type { APIContext } from 'astro';

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

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

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

추가된 버전: astro@1.5.0

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

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

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

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

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

Astro.redirect()
context.redirect()

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

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

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

<p>User information</p>

import type { APIContext } from 'astro';

export function GET({ redirect, request }: APIContext) {
  const cookie = request.headers.get('cookie');
  if (!isLoggedIn(cookie)) {
    return redirect('/login', 302);
  } else {
    // 사용자의 정보를 반환합니다.
  }
}

`rewrite()`

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

추가된 버전: astro@4.13.0

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

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

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

Astro.rewrite()
context.rewrite()

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

import type { APIContext } from 'astro';

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

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

Astro.rewrite()
context.rewrite()

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

import type { APIContext } from 'astro';

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

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

Astro.rewrite()
context.rewrite()

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

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)
    }
  }));
}

`originPathname`

타입: string

추가된 버전: astro@5.0.0

originPathname은 URL 재작성 (Rewrite)이 적용되기 전 요청의 원래 경로 이름을 정의합니다.

Astro.originPathname
context.originPathname

<p>원래 경로 이름은 {Astro.originPathname}</p>
<p>다시 작성된 경로는 {Astro.url.pathname}</p>

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  // URL을 다시 작성하기 전에 원래 경로 이름을 기록합니다.
  recordPageVisit(context.originPathname);
  return next();
});

`locals`

추가된 버전: astro@2.4.0

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

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

import type { MiddlewareHandler } from 'astro';

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

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

Astro.locals
context.locals

---
const title = Astro.locals.title;
---
<h1>{title}</h1>

import type { APIContext } from 'astro';

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

`preferredLocale`

타입: string | undefined

추가된 버전: astro@3.5.0

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

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

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

`preferredLocaleList`

타입: string[] | undefined

추가된 버전: astro@3.5.0

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

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

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

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

`currentLocale`

타입: string | undefined

추가된 버전: astro@3.5.6

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

`getActionResult()`

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

추가된 버전: astro@4.15.0

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

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

추가된 버전: astro@4.15.0

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

---
import { actions } from 'astro:actions';

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

`routePattern`

타입: string

추가된 버전: 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`

타입: AstroCookies

추가된 버전: astro@1.4.0

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

쿠키 유틸리티

`cookies.get()`

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

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

`cookies.has()`

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

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

`cookies.set()`

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

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

`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: AstroCookies) => void

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

`cookies.headers()`

타입: () => Iterator<string>

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

`AstroCookie` 타입

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

`AstroCookie.value`

타입: string

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

`AstroCookie.json()`

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

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

`AstroCookie.number()`

타입: () => number

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

`AstroCookie.boolean()`

타입: () => boolean

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

`AstroCookieGetOptions`

추가된 버전: astro@4.1.0

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

`AstroCookieGetOptions.decode()`

타입: (value: string) => string

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

`AstroCookieSetOptions`

추가된 버전: astro@4.1.0

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

`AstroCookieSetOptions.domain`

타입: string

도메인을 지정합니다. 도메인을 설정하지 않으면 대부분의 클라이언트는 현재 도메인에 적용되는 것으로 해석합니다.

`AstroCookieSetOptions.expires`

타입: Date

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

`AstroCookieSetOptions.httpOnly`

타입: boolean

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

`AstroCookieSetOptions.maxAge`

타입: number

쿠키가 유효한 기간(초)을 숫자로 지정합니다.

`AstroCookieSetOptions.path`

타입: string

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

`AstroCookieSetOptions.partitioned`

타입: boolean

추가된 버전: astro@5.17.0

true인 경우, 이 쿠키는 파티셔닝된 쿠키입니다. 파티셔닝된 쿠키는 설정된 최상위 사이트의 컨텍스트에서만 읽을 수 있으며, 이는 교차 사이트 추적을 차단하면서, 타사 쿠키의 합법적인 사용을 가능하게 합니다.

파티셔닝된 쿠키는 secure: true로 설정해야 합니다.

`AstroCookieSetOptions.sameSite`

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

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

`AstroCookieSetOptions.secure`

타입: boolean

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

`AstroCookieSetOptions.encode()`

타입: (value: string) => string

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

`session`

타입: AstroSession

추가된 버전: astro@5.7.0

요청 시 렌더링되는 라우트에 대해 요청 간 데이터를 저장할 수 있게 해주는 객체가 바로 session입니다. 세션 자체의 데이터는 쿠키에 저장되지 않고, 세션 ID만 담고 있는 쿠키와 연결됩니다.

세션은 처음 사용될 때 생성되며, 세션 쿠키는 자동으로 설정됩니다. 세션 스토리지가 구성되지 않았거나 현재 라우트가 사전 렌더링된 경우에는 session 객체가 undefined가 되며, 이를 사용하려고 하면 오류가 기록됩니다.

Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한 내용은 세션 가이드를 참조하세요.

`session.get()`

타입: (key: string) => Promise<any>

세션에서 주어진 키에 해당하는 값을 반환합니다. 해당 키가 존재하지 않으면 undefined를 반환합니다.

Astro.session
context.session

---
const cart = await Astro.session?.get('cart');
---
<button>🛒 {cart?.length}</button>

import type { APIContext } from 'astro';

export async function GET({ session }: APIContext) {
  const cart = await session.get('cart');
  return Response.json({ cart });
}

`session.set()`

타입: (key: string, value: any, options?: { ttl: number }) => void

세션에서 주어진 키에 해당하는 값을 설정합니다. 값은 직렬화 가능한 어떤 타입이든 가능합니다. 이 메서드는 동기적이며, 설정된 값은 즉시 검색할 수 있지만, 요청이 끝날 때까지 백엔드에 저장되지는 않습니다. ttl 옵션은 값의 만료 시간을 초 단위로 설정합니다.

Astro.session
context.session

---
const { slug } = Astro.params;
Astro.session?.set('lastViewedProduct', slug);
---

import type { APIContext } from 'astro';

export async function POST({ session, request }: APIContext) {
  const cart = await session.get('cart');
  const newItem = await request.json();
  cart.push(newItem);
  // 업데이트된 장바구니를 세션에 저장합니다.
  session.set('cart', cart);
  return Response.json({ cart });
}

`session.regenerate()`

타입: () => void

세션 ID를 갱신합니다. 세션 고정 공격을 방지하기 위해 사용자가 로그인하거나 권한이 상승했을 때 호출하세요.

Astro.session
context.session

---
Astro.session?.regenerate();
---

import type { APIContext } from 'astro';

export async function POST({ session }: APIContext) {
  // 사용자를 인증합니다...
  doLogin();
  // 세션 고정 공격을 방지하기 위해 세션 ID를 갱신합니다.
  session.regenerate();
  return Response.json({ success: true });
}

`session.destroy()`

타입: () => void

세션을 파기합니다. 쿠키와 백엔드에 있는 객체를 모두 삭제합니다. 사용자가 로그아웃하거나 세션이 무효화되었을 때 호출하세요.

Astro.session
context.session

---
Astro.session?.destroy();
return Astro.redirect('/login');
---

import type { APIContext } from 'astro';

export async function POST({ session }: APIContext) {
  session.destroy();
  return Response.json({ success: true });
}

`session.load()`

타입: (id: string) => Promise<void>

ID를 사용하여 세션을 로드합니다. 일반적인 사용 환경에서는 요청 쿠키로부터 세션이 자동으로 로드됩니다. 이 메서드는 다른 ID의 세션을 로드해야 할 때 사용합니다. 세션 ID를 직접 관리하거나, 쿠키를 사용하지 않고 세션을 추적하고 싶을 때 유용합니다.

Astro.session
context.session

---
// 헤더에서 쿠키 대신 세션을 로드합니다.
const sessionId = Astro.request.headers.get('x-session-id');
await Astro.session?.load(sessionId);
const cart = await Astro.session?.get('cart');
---
<h1>Your cart</h1>
<ul>
  {cart?.map((item) => (
    <li>{item.name}</li>
  ))}
</ul>

import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ session, request }) => {
  // 헤더에서 쿠키 대신 세션을 로드합니다.
  const sessionId = request.headers.get('x-session-id');
  await session.load(sessionId);
  const cart = await session.get('cart');
  return Response.json({ cart });
};

`csp`

타입: object | undefined

추가된 버전: astro@6.0.0

Astro의 CSP 런타임 API는 문서가 로드할 수 있는 리소스를 제어하여 특정 유형의 보안 위협을 최소화하는 데 도움이 되는 콘텐츠 보안 정책(CSP) 지원을 활성화합니다. 이는 교차 사이트 스크립팅(XSS) 공격에 대한 추가적인 보호를 제공합니다.

.astro 컴포넌트 내부의 Astro 전역 객체 또는 엔드포인트 및 미들웨어의 APIContext 타입을 사용하여 페이지별로 <meta> 요소를 사용자 정의할 수 있습니다.

리소스가 여러 번 삽입되거나 여러 소스(예: csp 구성에 정의된 것과 다음 CSP 런타임 API를 사용하여 추가된 것)에서 제공되는 경우, Astro는 모든 리소스를 병합하고 중복을 제거하여 <meta> 요소를 생성합니다.

`csp.insertDirective()`

타입: (directive: CspDirective) => void

추가된 버전: astro@6.0.0

현재 페이지에 단일 지시어를 추가합니다. 이 메서드를 여러 번 호출하여 지시어를 추가할 수 있습니다.

---
Astro.csp?.insertDirective("default-src 'self'");
Astro.csp?.insertDirective("img-src 'self' https://images.cdn.example.com");
---

빌드 후, 이 개별 페이지의 <meta> 요소는 기존 script-src 및 style-src 지시어와 함께 추가된 지시어를 포함하게 됩니다.

<meta
http-equiv="content-security-policy"
content="
  default-src 'self';
  img-src 'self' https://images.cdn.example.com;
  script-src 'self' 'sha256-somehash';
  style-src 'self' 'sha256-somehash';
  "
>

`csp.insertStyleResource()`

타입: (resource: string) => void

추가된 버전: astro@6.0.0

style-src 지시어에 사용할 새로운 리소스를 삽입합니다.

---
Astro.csp?.insertStyleResource("https://styles.cdn.example.com");
---

빌드 후, 이 개별 페이지의 <meta> 요소는 기본 style-src 지시어에 지정된 소스를 추가합니다.

<meta
http-equiv="content-security-policy"
content="
  script-src 'self' 'sha256-somehash';
  style-src https://styles.cdn.example.com 'sha256-somehash';
  "
>

`csp.insertStyleHash()`

타입: (hash: CspHash) => void

추가된 버전: astro@6.0.0

style-src 지시어에 새로운 해시를 추가합니다.

---
Astro.csp?.insertStyleHash("sha512-styleHash");
---

빌드 후, 이 개별 페이지의 <meta> 요소는 기본 style-src 지시어에 지정된 해시를 추가합니다.

<meta
http-equiv="content-security-policy"
content="
  script-src 'self' 'sha256-somehash';
  style-src 'self' 'sha256-somehash' 'sha512-styleHash';
  "
>

`csp.insertScriptResource()`

타입: (resource: string) => void

추가된 버전: astro@6.0.0

script-src 지시어에 사용할 새로운 유효한 소스를 삽입합니다.

---
Astro.csp?.insertScriptResource("https://scripts.cdn.example.com");
---

빌드 후, 이 개별 페이지의 <meta> 요소는 기본 script-src 지시어에 지정된 소스를 추가합니다.

<meta
http-equiv="content-security-policy"
content="
  script-src https://scripts.cdn.example.com 'sha256-somehash';
  style-src 'self' 'sha256-somehash';
  "
>

`csp.insertScriptHash()`

타입: (hash: CspHash) => void

추가된 버전: astro@6.0.0

script-src 지시어에 새로운 해시를 추가합니다.

---
Astro.csp?.insertScriptHash("sha512-scriptHash");
---

빌드 후, 이 개별 페이지의 <meta> 요소는 기본 script-src 지시어에 지정된 해시를 추가합니다.

<meta
http-equiv="content-security-policy"
content="
  script-src 'self' 'sha256-somehash' 'sha512-styleHash';
  style-src 'self' 'sha256-somehash';
  "
>

기여하기 커뮤니티 후원하기

Astro 렌더링 컨텍스트

컨텍스트 객체

props

params

url

site

clientAddress

isPrerendered

generator

request

response

redirect()

rewrite()

originPathname

locals

preferredLocale

preferredLocaleList

currentLocale

getActionResult()

callAction()

routePattern

cookies

쿠키 유틸리티

cookies.get()

cookies.has()

cookies.set()

cookies.delete()

cookies.merge()

cookies.headers()

AstroCookie 타입

AstroCookie.value

AstroCookie.json()

AstroCookie.number()

AstroCookie.boolean()

AstroCookieGetOptions

AstroCookieGetOptions.decode()

AstroCookieSetOptions

AstroCookieSetOptions.domain

AstroCookieSetOptions.expires

AstroCookieSetOptions.httpOnly

AstroCookieSetOptions.maxAge

AstroCookieSetOptions.path

AstroCookieSetOptions.partitioned

AstroCookieSetOptions.sameSite

AstroCookieSetOptions.secure

AstroCookieSetOptions.encode()

session

session.get()

session.set()

session.regenerate()

session.destroy()

session.load()

csp

csp.insertDirective()

csp.insertStyleResource()

csp.insertStyleHash()

csp.insertScriptResource()

csp.insertScriptHash()

`props`

`params`

`url`

`site`

`clientAddress`

`isPrerendered`

`generator`

`request`

`response`

`redirect()`

`rewrite()`

`originPathname`

`locals`

`preferredLocale`

`preferredLocaleList`

`currentLocale`

`getActionResult()`

`callAction()`

`routePattern`

`cookies`

`cookies.get()`

`cookies.has()`

`cookies.set()`

`cookies.delete()`

`cookies.merge()`

`cookies.headers()`

`AstroCookie` 타입

`AstroCookie.value`

`AstroCookie.json()`

`AstroCookie.number()`

`AstroCookie.boolean()`

`AstroCookieGetOptions`

`AstroCookieGetOptions.decode()`

`AstroCookieSetOptions`

`AstroCookieSetOptions.domain`

`AstroCookieSetOptions.expires`

`AstroCookieSetOptions.httpOnly`

`AstroCookieSetOptions.maxAge`

`AstroCookieSetOptions.path`

`AstroCookieSetOptions.partitioned`

`AstroCookieSetOptions.sameSite`

`AstroCookieSetOptions.secure`

`AstroCookieSetOptions.encode()`

`session`

`session.get()`

`session.set()`

`session.regenerate()`

`session.destroy()`

`session.load()`

`csp`

`csp.insertDirective()`

`csp.insertStyleResource()`

`csp.insertStyleHash()`

`csp.insertScriptResource()`

`csp.insertScriptHash()`