routing

라우팅(Routing)

Astro는 프로젝트의 src/pages/ 폴더 파일 구조를 기준으로 빌드 URL을 만들어 내는 **파일 기반 라우팅(file-based routing)**을 써요. 파일 하나를 두는 것만으로 라우트가 생기니, 경로마다 라우트 설정 파일을 따로 만들 필요가 없어요. 어떤 파일이 어떤 URL이 되고, 동적 파라미터와 리다이렉트는 어떻게 다루는지 볼게요.

출처: 공식문서

본문

페이지 사이 이동

Astro는 라우트 사이를 이동할 때 표준 HTML <a> 요소를 써요. 프레임워크만의 <Link> 컴포넌트는 제공하지 않아요.

정적 라우트(Static routes)

src/pages/ 폴더 안의 .astro 페이지 컴포넌트와 Markdown·MDX 파일(.md, .mdx)은 자동으로 웹사이트의 페이지가 돼요. 각 페이지의 라우트는 src/pages/ 폴더 안에서의 경로와 파일명에 대응해요.

동적 라우트(Dynamic routes)

Astro 페이지 파일은 파일명에 동적 라우트 파라미터를 지정해 여러 개의 일치 페이지를 만들 수 있어요. 예를 들어 src/pages/authors/[author].astro는 블로그의 작성자마다 소개 페이지를 만들어 내요. 이때 author는 페이지 안에서 접근할 수 있는 파라미터가 돼요.

주문형 동적 라우트(On-demand dynamic routes)

주문형(on-demand) 렌더링 라우트에서는 파일명에 스프레드 표기법을 쓰는 rest 파라미터를 하나만 쓸 수 있어요. 예를 들어 src/pages/[locale]/[...slug].astro나 src/pages/[...locale]/[slug].astro는 되지만, src/pages/[...locale]/[...slug].astro처럼 rest 파라미터를 두 번 쓰는 건 안 돼요.

리다이렉트(Redirects)

Astro 전역의 Astro.redirect 메서드로 다른 페이지로 동적으로 리다이렉트할 수 있어요. 예를 들어 쿠키에서 세션을 얻어 사용자가 로그인했는지 확인한 뒤 리다이렉트하는 식으로 쓸 수 있어요.

astro.config.mjs에서 설정된 리다이렉트(Configured Redirects)를 정의할 수도 있어요.

import { defineConfig } from "astro/config";

export default defineConfig({
  redirects: {
    "/old-page": "/new-page",
    "/blog": "https://example.com/blog"
  }
});

이 리다이렉트들은 파일 기반 라우트와 같은 우선순위 규칙을 따르고, 프로젝트에 같은 이름의 실제 페이지 파일이 있으면 항상 그보다 낮은 우선순위를 가져요. 예를 들어 src/pages/old-page.astro 파일이 있으면 /old-page는 /new-page로 리다이렉트되지 않아요.

상태 코드와 대상을 함께 지정할 수도 있어요.

import { defineConfig } from "astro/config";

export default defineConfig({
  redirects: {
    "/old-page": {
      status: 302,
      destination: "/new-page"
    },
    "/news": {
      status: 302,
      destination: "https://example.com/news"
    }
  }
});

리라이트(Rewrites)

참고: [email protected]부터 추가됐어요.

리라이트(rewrite)는 브라우저를 다른 페이지로 리다이렉트하지 않고, 다른 라우트를 서빙하게 해 줘요. 브라우저 주소창에는 원래 주소가 그대로 보이지만, Astro.rewrite()에 넘긴 URL의 콘텐츠를 대신 표시해요.

콘텐츠가 영구히 이동했거나, 로그인 후 사용자를 다른 페이지(예: 대시보드)로 보낼 때는 리다이렉트를 쓰는 게 맞아요.

리라이트는 같은 콘텐츠를 여러 경로에 보여줄 때 유용해요. 예를 들어 /products/shoes/men/과 /products/men/shoes/ 두 경로에 같은 내용을 보여주고 싶을 때 소스 파일을 두 개 유지하지 않아도 되거든요. 또 SEO와 사용자 경험에도 좋아요. 방문자를 다른 페이지로 리다이렉트하거나 404 상태를 반환해야만 하던 콘텐츠를 그대로 보여줄 수 있으니까요. 언어 변형마다 지역화된 같은 콘텐츠를 보여주는 것도 흔한 용도예요.

다음 예시는 /es-CU/(쿠바 스페인어) URL 경로가 방문됐을 때 /es/ 버전 페이지를 렌더링해요. 방문자가 /es-cu/articles/introduction 주소로 들어오면 Astro는 src/pages/es/articles/introduction.astro 파일이 만든 콘텐츠를 렌더링해요.

Astro.rewrite()는 지정한 리라이트 경로의 콘텐츠를 표시하기 전에 새롭고 완전한 렌더링 단계를 시작해요. 이 과정에서 새 라우트/요청에 대한 미들웨어를 다시 실행해요.

라우트 우선순위

예시에서 /posts/create.astro가 다른 모든 라우트보다 우선해요.

  • 이름 있는 파라미터를 쓰는 동적 라우트가 rest 파라미터보다 우선해요. 예: /posts/[page].astro가 /posts/[...slug].astro보다 우선.
  • 프리렌더된 동적 라우트가 서버 동적 라우트보다 우선해요.

예약된 라우트

  • _astro/ — CSS 문서, 번들된 클라이언트 스크립트, 최적화된 이미지, Vite 자산 등 모든 정적 자산을 클라이언트에 서빙해요.
  • _server_islands/ — 서버 island로 지연된 동적 컴포넌트를 서빙해요.
  • _actions/ — 정의된 액션들을 서빙해요.

페이지네이션(Pagination)

여러 페이지로 나눠야 할 큰 데이터 컬렉션을 위해 Astro는 내장 페이지네이션을 지원해요. 이전/다음 페이지 URL, 총 페이지 수 등 공통 페이지네이션 속성을 자동으로 만들어 줘요.

중첩 페이지네이션(Nested Pagination)

페이지네이션을 다른 동적 라우트 파라미터와 결합하는 중첩 페이지네이션도 쓸 수 있어요. 페이지네이션된 컬렉션을 어떤 속성이나 태그로 묶고 싶을 때 유용해요.

예를 들어 페이지네이션된 Markdown 글을 태그별로 묶고 싶다면 /src/pages/[tag]/[page].astro 페이지를 만들어 다음 URL들이 일치하게 할 수 있어요.

  • /red/1 (tag=red)
  • /red/2 (tag=red)
  • /blue/1 (tag=blue)
  • /green/1 (tag=green)

페이지 제외(Excluding pages)

이 규칙으로 페이지를 임시로 비활성화할 수도 있고, 테스트·유틸리티·컴포넌트를 관련 페이지와 같은 폴더에 둘 수도 있어요. 페이지 파일명을 _로 시작하거나 [대괄호]로 감싼 폴더를 쓰면 빌드에서 제외할 수 있어요.

더 알아보기