Nuxt 3에서 API 라우트, 정확히 어디에 만들어야 할까?

Nuxt 3를 사용하다 보면 API 라우트를 어디에 만들어야 하는지 헷갈릴 때가 많습니다. server/api/와 server/routes/ 폴더의 차이를 모르면, 의도와 다르게 API가 동작하지 않아 당황할 수 있죠. 이번 글에서는 Nuxt 3에서 API를 올바르게 만드는 방법, 그리고 구조별 차이점을 명확하게 정리합니다.

✅ Nuxt 3에서 API는 `server/api/`에 만들어야 해

Nuxt 3의 공식 규칙에 따라, JSON API나 비동기 데이터 처리를 원한다면 반드시 server/api/ 폴더에 파일을 만들어야 정상적으로 API로 동작합니다.

server/routes/api/처럼 만들면 Nuxt가 해당 파일을 API로 인식하지 않고, 일반적인 페이지 응답(HTML, 텍스트 등)으로 처리할 수 있습니다.

📁 Nuxt 3의 올바른 폴더 구조

Nuxt 3에서는 다음처럼 폴더를 구성하는 것이 가장 명확합니다.

server/
├── api/
│   └── ping-search.ts   ✅ ← 여기에 넣은 파일만 API 엔드포인트가 됨
├── routes/
│   └── sitemap.xml.ts   ✅ ← 여긴 XML/텍스트 같은 페이지 응답용

server/api/
- JSON 데이터 또는 동적 처리가 필요한 API 엔드포인트
- 예시: /api/ping-search
server/routes/
- 브라우저에서 직접 접근할 수 있는 HTML, XML, robots.txt, sitemap 등
- 예시: /sitemap.xml, /robots.txt

📌 Nuxt 3의 동작 규칙 — 표로 비교!

폴더	용도	예시
`server/api/`	JSON API, 비동기 처리용	`/api/ping-search`
`server/routes/`	브라우저에서 직접 접근하는 페이지 응답	`/sitemap.xml`, `/robots.txt`

server/routes/api/something.ts처럼 만들면, Nuxt가 해당 파일을 API로 인식하지 않고 단순 페이지 응답으로 처리할 수 있으니 주의해야 합니다.

✅ 구조별 동작 차이 — 실제 예시

경로	동작
`server/api/ping-search.ts`	✅ `fetch('/api/ping-search')`로 정상 접근
`server/routes/ping-search.ts`	❌ API가 아니라, HTML/텍스트 등 페이지 응답
`server/routes/api/ping-search.ts`	⚠️ 혼란 유발, Nuxt에서 권장하지 않음

Nuxt 3 API 파일 위치, 왜 이렇게 중요할까?

Nuxt가 내부적으로 라우터를 생성할 때 폴더 위치 기반으로 자동 인식하기 때문입니다.

server/api/ 내 파일만 JSON API로서의 처리가 적용됩니다.
그 외 경로(server/routes/ 등)는 HTML, XML, 일반 텍스트 등 페이지 응답용으로만 동작합니다.

이 차이를 모르고 API 파일을 잘못된 위치에 두면,

API가 404로 뜨거나
예상과 달리 JSON이 아니라 HTML/text로 응답되는 문제가 발생할 수 있습니다.

정리

API를 만들려면 반드시 server/api/ 폴더에 파일을 두세요.
server/routes/는 HTML/텍스트 등 브라우저에서 직접 접근하는 정적/동적 페이지 응답용입니다.
Nuxt의 라우트 자동 생성 규칙을 잘 활용하면, 코드를 더 명확하게 관리할 수 있습니다.

실제 개발 중 혼동하기 쉬운 부분이지만, 폴더 구조만 명확히 이해하면 어렵지 않게 해결할 수 있습니다. 필요하다면 다음 글에서 Nuxt 3의 API 핸들러에서 POST 요청이나 파라미터 처리 방법, 실전 예제도 자세히 다뤄보겠습니다.