컨텐츠로 건너뛰기

라우팅 참조

Astro에는 별도의 라우팅 설정이 없습니다.

특별한 src/pages/ 디렉터리에 위치한 모든 지원되는 페이지 파일이 라우트를 생성합니다. 파일 이름에 매개변수가 포함되어 있을 경우 라우트는 동적으로 여러 페이지를 생성할 수 있으며, 그렇지 않으면 단일 페이지를 생성합니다.

기본적으로 모든 Astro 페이지 라우트와 엔드포인트는 빌드 타임에 생성되어 사전 렌더링됩니다. 요청 시 서버 렌더링은 개별 라우트에 대해 설정하거나 기본값으로 설정할 수 있습니다.

prerender

섹션 제목: prerender

타입: boolean
기본값: 정적 모드에서 true(기본값); output: 'server' 구성 시 false

Added in: astro@1.0.0

각 개별 라우트에서 내보내는 값으로, 사전 렌더링 여부를 결정합니다.

기본적으로 모든 페이지와 엔드포인트는 사전 렌더링되며 빌드 타임에 정적으로 생성됩니다. 하나 이상의 라우트에서 사전 렌더링을 선택 해제할 수 있으며, 동일한 프로젝트에서 정적 렌더링 및 요청 시 렌더링 라우트를 모두 가질 수 있습니다.

페이지별 재정의

섹션 제목: 페이지별 재정의

개별 라우트에 대해 요청 시 렌더링을 활성화하려면 해당 파일에서 prerender 값을 false로 내보내어 기본값을 재정의할 수 있습니다:

src/pages/rendered-on-demand.astro
---
export const prerender = false
---
<!-- 서버 렌더링된 콘텐츠 -->
<!-- 사이트의 나머지 부분은 정적 -->

server 모드로 전환

섹션 제목: server 모드로 전환

모든 라우트의 기본값을 재정의하려면 output: 'server'를 설정하면 됩니다. 이 출력 모드에서는 모든 페이지와 엔드포인트가 사전 렌더링되는 대신 기본적으로 요청 시 서버에서 생성됩니다.

server 모드에서 개별 라우트에 대한 사전 렌더링을 활성화하려면 해당 파일에서 prerender 값을 true로 내보내면 됩니다:

src/pages/static-about-page.astro
---
// `output: 'server'` 구성 시
export const prerender = true
---
<!-- 정적인 소개 페이지 -->
<!-- 다른 모든 페이지는 요청 시 렌더링 -->

partial

섹션 제목: partial

타입: boolean
기본값: false

Added in: astro@3.4.0

개별 라우트에서 내보내는 값으로, 전체 HTML 페이지로 렌더링할지 여부를 결정합니다.

기본적으로 예약된 src/pages/ 디렉터리에 위치한 모든 파일은 자동으로 <!DOCTYPE html> 선언과 Astro의 스코프가 지정된 스타일 및 스크립트와 같은 추가적인 <head> 콘텐츠를 포함합니다.

개별 라우트에 대해 콘텐츠를 페이지 부분으로 지정하려면 해당 파일에서 partial에 대한 값을 내보내어 기본값을 재정의할 수 있습니다:

src/pages/my-page-partial.astro
---
export const partial = true
---
<!-- URL에서 사용할 수 있는 생성된 HTML -->
<!-- 렌더링 라이브러리에서 사용 가능 -->

export const partial은 정적으로 식별 가능해야 합니다. 다음과 같은 값을 가질 수 있습니다:

  • 불리언 값인 true.
  • import.meta.env.USE_PARTIALS와 같은 import.meta.env를 사용하는 환경 변수

getStaticPaths()

섹션 제목: getStaticPaths()

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

Added in: astro@1.0.0

파일 경로에 하나 이상의 매개변수가 있는 단일 .astro 페이지 컴포넌트에서 여러 개의 사전 렌더링된 페이지 라우트를 생성하는 함수입니다. 이는 정적 사이트 빌딩이라고도 하는, 빌드 타임에 생성될 라우트에 사용됩니다.

getStaticPaths() 함수는 Astro가 사전 렌더링할 URL 경로를 결정하기 위한 객체 배열을 반환해야 합니다. 각 객체는 라우트 경로를 지정하는 params 객체를 포함해야 합니다. 선택적으로 각 페이지 템플릿에 전달할 데이터가 있는 props 객체를 포함할 수 있습니다.

src/pages/blog/[post].astro
---
// `server` 모드에서 사전 렌더링 선택:
// export const prerender = true


export async function getStaticPaths() {
  return [
    // { params: { /* required */ }, props: { /* 선택적 */ } },
    { params: { post: '1' } }, // [post]는 매개변수입니다.
    { params: { post: '2' } }, // 반드시 파일 이름과 일치해야 합니다.
    // ...
  ];
}
---
<!-- HTML 템플릿 -->

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

params

섹션 제목: params

getStaticPaths()가 반환하는 배열의 각 객체에 있는 params 키는 Astro에게 어떤 라우트를 빌드할지 알려줍니다.

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

예를 들어, src/pages/posts/[id].astro는 파일 이름에 id 매개변수를 가지고 있습니다. 다음은 .astro 컴포넌트의 getStaticPaths() 함수가 빌드 시점에 Astro에게 posts/1, posts/2, posts/3을 정적으로 생성하도록 지시합니다.

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


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

props를 사용한 데이터 전달

섹션 제목: props를 사용한 데이터 전달

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

예를 들어, 원격 API에서 가져온 데이터로 페이지를 생성하는 경우 getStaticPaths()에서 전체 데이터 객체를 페이지 컴포넌트에 전달할 수 있습니다. 페이지 템플릿은 Astro.props를 사용하여 각 게시물의 데이터를 참조할 수 있습니다.

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

paginate()

섹션 제목: paginate()

Added in: astro@1.0.0

getStaticPaths()에서 반환할 수 있는 함수로, 콘텐츠 항목 모음을 개별 페이지로 나눕니다.

paginate()는 페이지네이션된 컬렉션의 각 페이지마다 하나의 URL을 생성하기 위해 getStaticPaths()에서 반환할 필요한 배열을 자동으로 생성합니다. 페이지 번호는 param으로 전달되고, 페이지 데이터는 page prop으로 전달됩니다.

다음 예시는 150개의 항목을 가져와 paginate 함수에 전달하고, 빌드 타임에 페이지당 10개의 항목을 표시할 정적으로 사전 렌더링된 페이지를 생성합니다:

src/pages/pokemon/[page].astro
---
export async function getStaticPaths({ paginate }) {
  // fetch(), getCollection() 등으로 데이터 로드
  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 });
}


const { page } = Astro.props;
---

paginate()는 다음과 같은 인수를 가집니다:

  • data - paginate() 함수에 전달된 페이지의 데이터를 포함하는 배열
  • options - 다음 속성을 가진 선택적 객체:
    • pageSize - 페이지당 표시되는 항목 수(기본값 10)
    • params - 동적 라우트 생성을 위한 추가 매개변수 전달
    • props - 각 페이지에서 사용할 수 있는 추가 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을 생성합니다.

페이지네이션 page prop

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

타입: Page<TData>

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

page.data
섹션 제목: page.data

타입: Array<TData>

현재 페이지에 대해 paginate() 함수에서 반환된 데이터 배열

page.start
섹션 제목: page.start

타입: number

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

page.end
섹션 제목: page.end

타입: number

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

page.size
섹션 제목: page.size

타입: number
기본값: 10

페이지당 총 항목 수입니다.

page.total
섹션 제목: page.total

타입: number

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

page.currentPage
섹션 제목: page.currentPage

타입: number

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

page.lastPage
섹션 제목: page.lastPage

타입: number

총 페이지 수입니다.

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

타입: string

현재 페이지의 URL을 가져옵니다(canonical URL에 유용). base에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

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

타입: string | undefined

이전 페이지의 URL을 가져옵니다(첫 페이지인 경우 undefined). base에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

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

타입: string | undefined

다음 페이지의 URL을 가져옵니다(마지막 페이지인 경우 undefined). base에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

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

타입: string

첫 페이지의 URL을 가져옵니다(첫 페이지인 경우 undefined). base에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

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

타입: string

마지막 페이지의 URL을 가져옵니다(마지막 페이지인 경우 undefined). base에 대한 값이 설정된 경우, URL은 해당 값으로 시작합니다.

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

타입: string | undefined

Added in: astro@4.12.0

첫 페이지의 URL을 가져옵니다(1페이지인 경우 undefined). base에 대한 값이 설정된 경우, 기본 경로가 URL 앞에 추가됩니다.

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

타입: string | undefined

Added in: astro@4.12.0

마지막 페이지의 URL을 가져옵니다(더 이상 페이지가 없는 경우 undefined). base에 대한 값이 설정된 경우, 기본 경로가 URL 앞에 추가됩니다.

기여하기 커뮤니티 Sponsor