프론트엔드¶

app.frontend()(또는 router.frontend())로 정적 프론트엔드 애플리케이션을 제공할 수 있습니다.

이는 Vite를 사용하는 React, TanStack Router, Astro, Vue, Svelte, Angular, Solid 등과 같이 정적 파일을 생성하는 프론트엔드 도구에 유용합니다.

이러한 도구에서는 보통 다음과 같은 명령어로 프론트엔드를 빌드하는 단계가 있습니다:

npmrunbuild

그러면 프론트엔드 파일이 들어 있는 ./dist/ 같은 디렉터리가 생성됩니다.

app.frontend()를 사용하면 이러한 프론트엔드 프레임워크에 필요한 규칙에 따라 해당 디렉터리를 제공할 수 있습니다.

FastAPI는 먼저 경로 처리를 확인합니다. 프론트엔드 파일은 일반 라우트와 매칭되지 않는 경우에만 확인되므로, API에는 영향을 주지 않습니다.

프론트엔드 제공하기¶

예를 들어 npm run build로 프론트엔드를 빌드한 후, 생성된 파일을 dist 같은 디렉터리에 넣습니다.

프로젝트 구조는 다음과 같을 수 있습니다:

.
├── pyproject.toml
├── app
│ ├── __init__.py
│ └── main.py
└── dist
 ├── index.html
 └── assets
 └── app.js

그런 다음 app.frontend()로 제공합니다:

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist")

이렇게 하면 /assets/app.js에 대한 요청이 dist/assets/app.js를 제공할 수 있습니다.

FastAPI 경로 처리도 있다면, 경로 처리가 우선합니다.

클라이언트 사이드 라우팅¶

single-page apps(SPAs)를 포함한 많은 프론트엔드 애플리케이션은 클라이언트 사이드 라우팅을 사용합니다. /dashboard/settings 같은 경로는 실제 파일이 아닐 수 있지만, 프레임워크가 이를 처리합니다.

따라서 해당 URL에 직접 접근하는 경우(애플리케이션 안에서 탐색하는 대신), 백엔드는 index.html에서 프론트엔드 애플리케이션을 제공해야 합니다. 그러면 프론트엔드 프레임워크가 클라이언트 사이드 라우팅을 처리할 수 있습니다.

이를 위해 fallback="index.html"을 사용합니다:

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="index.html")

FastAPI는 브라우저 탐색처럼 보이는 GET 및 HEAD 요청에만 이 fallback을 사용합니다. JavaScript, CSS, 이미지처럼 누락된 파일은 여전히 404를 반환합니다.

POST나 PUT 같은 다른 메서드의 요청이 프론트엔드 fallback에만 매칭되는 경로로 들어와도 404를 반환합니다. 일반 FastAPI 경로 처리는 여전히 프론트엔드 라우트보다 높은 우선순위를 가집니다.

이는 클라이언트 사이드 라우팅을 사용하는 많은 프론트엔드 애플리케이션에서 원하는 동작입니다. 예를 들어 TanStack Router를 사용하는 React, Vue, Angular, SvelteKit, Solid 등이 있습니다.

사용자 정의 404 페이지¶

누락된 프론트엔드 경로에 대해 정적 404.html 페이지를 제공할 수도 있습니다:

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="404.html")

이 응답은 404 상태 코드를 유지합니다.

이 경우 FastAPI는 누락된 프론트엔드 경로에 대해 index.html을 제공하지 않습니다. 대신 404.html 파일을 반환합니다.

이는 Astro처럼 각 페이지에 대한 정적 HTML 파일을 생성하는 프론트엔드 도구에 유용합니다.

Fallback 자동 설정¶

기본적으로 app.frontend()는 fallback="auto"를 사용합니다.

프론트엔드 디렉터리에 404.html 파일이 있으면, 누락된 프론트엔드 경로는 상태 코드 404와 함께 해당 파일을 제공합니다.

그렇지 않고 index.html 파일이 있으면, 누락된 브라우저 탐색 경로는 index.html을 제공합니다. 이는 클라이언트 사이드 라우팅을 사용하는 많은 프론트엔드 애플리케이션이 기대하는 동작입니다.

따라서 대부분의 경우 fallback 인자를 지정하지 않고 app.frontend("/", directory="dist")를 사용할 수 있습니다.

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist")

Fallback 비활성화¶

누락된 프론트엔드 경로에 대해 fallback 파일을 제공하고 싶지 않다면 fallback=None을 사용합니다:

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback=None)

그러면 누락된 프론트엔드 경로는 일반 404를 반환합니다.

디렉터리 확인하기¶

기본적으로 app.frontend()는 애플리케이션이 생성될 때 디렉터리가 존재하는지 확인합니다.

이는 설정 오류를 일찍 발견하는 데 도움이 됩니다. 예를 들어 프론트엔드 빌드 출력 디렉터리가 없다면 FastAPI는 시작 시 오류를 발생시킵니다.

프론트엔드 파일이 나중에 생성된다면, 예를 들어 애플리케이션 객체가 생성된 후 별도의 빌드 단계에서 생성된다면, check_dir=False를 설정합니다:

fromfastapiimport FastAPI
app = FastAPI()
app.frontend("/", directory="dist", check_dir=False)

check_dir=False를 사용하면 FastAPI는 애플리케이션이 생성될 때 디렉터리를 확인하지 않습니다. 요청이 처리될 때 설정된 디렉터리가 여전히 없다면, 그때 FastAPI가 오류를 발생시킵니다.

APIRouter와 함께 사용하기¶

프론트엔드 파일을 APIRouter에 추가하고 prefix와 함께 포함할 수도 있습니다:

fromfastapiimport APIRouter, FastAPI
app = FastAPI()
router = APIRouter()
router.frontend("/", directory="dist", fallback="index.html")
app.include_router(router, prefix="/app")

이 예제에서는 프론트엔드 경로가 /app 아래에서 제공됩니다.

다른 라우터에 있는 것을 포함하여, 애플리케이션의 모든 일반 경로 처리가 여전히 우선합니다.

정적 빌드 출력만 사용하기¶

app.frontend()는 프론트엔드 빌드에서 이미 생성된 파일을 제공합니다.

서버 사이드 렌더링은 실행하지 않습니다. 각 요청마다 서버에서 동적 렌더링이 필요한 프레임워크가 아니라, 정적 파일을 생성하는 프론트엔드 프레임워크를 위한 것입니다.