basePath

Next.js 애플리케이션을 도메인의 특정 하위 경로(sub-path) 아래에 배포하고 싶을 때, basePath 설정을 사용하면 됩니다.

basePath는 애플리케이션에 경로 접두사를 붙여주는 역할을 해요. 예를 들어, 기본값인 빈 문자열("") 대신 /docs 경로로 앱을 서비스하고 싶을 때는, next.config.js 파일을 열고 아래처럼 basePath를 추가하면 됩니다.

module.exports = {
  basePath: '/docs',
}

이렇게 하면 내 사이트 주소가 https://yourdomain.com/docs 같은 형태가 되겠죠.

추가 팁!

basePath를 사용할 때는 정적 파일이나 API 호출 경로도 이 경로를 고려해서 작성해야 해요.
예를 들어, 이미지 경로나 API 요청할 때 /docs/images/logo.png, /docs/api/data 이런 식으로 경로를 맞춰줘야 합니다.
만약 로컬에서 개발할 땐 basePath가 없으니, 경로 문제로 헷갈릴 수 있으니 환경별로 경로를 분리해서 쓰는 것도 좋습니다.
또한, next/link나 next/router를 사용할 때는 자동으로 basePath를 인식하기 때문에 경로를 따로 신경 쓸 필요 없다는 점도 기억해 주세요.

실제로 여러 프로젝트를 운영하다 보면, 하나의 도메인에 여러 Next.js 앱을 각기 다른 하위 경로에 딱 맞게 배포할 때 이 설정을 자주 쓰게 됩니다! 활용해보세요 :)

참고할 점: 이 값은 빌드할 때 반드시 설정되어야 하며, 클라이언트 측 번들에 직접 삽입되기 때문에 빌드 후에는 변경할 수 없어요.

링크 관련

next/link나 next/router를 사용할 때 다른 페이지로 이동하는 링크를 만들면, basePath가 자동으로 적용됩니다.

예를 들어, basePath가 /docs로 설정되어 있을 때 /about이라는 경로를 사용하면 실제 링크는 /docs/about으로 자동 변환돼요.

추가로 알아두면 좋은 팁을 하나 알려드리자면, basePath를 설정할 때는 실제 배포 환경에서 경로가 어떻게 작동할지를 꼭 확인해보세요. 특히 여러 경로나 서브 디렉터리를 다룰 때는 혼란이 생기기 쉬우니, dev 환경과 prod 환경에서 모두 테스트하는 걸 추천해요!

요즘 React 프로젝트에서 자주 보이는 Link 컴포넌트 예제인데요, 여기서 기본 경로(basePath)가 설정되어 있을 때 정말 유용한 부분을 하나 알려드릴게요.

아래 코드를 한번 볼게요:

export default function HomePage() {
  return (
    <>
      <Link href="/about">About Page</Link>
    </>
  )
}

JavaScript에선 이렇게 Link 컴포넌트를 사용하는데, 실제 브라우저에 렌더링 될 때는 아래와 같이 바뀐답니다.

<a href="/docs/about">About Page</a>

즉, href 속성에 /docs라는 basePath가 자동으로 붙어서 렌더링이 되는 거죠.

왜 이게 좋은 걸까?

만약 프로젝트 루트 경로가 나중에 바뀌어서 /docs 같은 경로가 앞에 붙어야 한다면, 기존에 /about 같은 경로를 모두 일일이 바꾸는 게 엄청 번거로울 거예요. 근데 이 Link 컴포넌트를 쓰면, 앱 안에서 링크를 쓸 때는 항상 깔끔하게 /about처럼 기본 경로만 쓰고, 실제 최종 경로는 basePath 설정에 맞게 자동 변경되니까 유지보수가 훨씬 수월해집니다.

추가 팁

Next.js 같은 프레임워크에서는 next.config.js에서 basePath 설정을 해주면 이런 동작이 자동으로 처리돼요.
이 방법은 SEO(검색엔진최적화)나 클라이언트 라우팅에서도 깔끔하게 URL 관리를 할 수 있게 도와줍니다.
만약 직접 <a> 태그를 쓰면 basePath를 수동으로 붙여줘야 하니, 링크 관련 컴포넌트는 꼭 프레임워크에서 제공하는 걸 쓰는 게 좋아요.

나중에 내가 만든 앱이 다른 경로에서 배포될 수도 있겠다 싶으면, 초기부터 이런 basePath를 고려한 링크 방식을 꼭 도입해보세요! 생각보다 개발자 경험(Developer Experience) 측면에서 큰 도움이 됩니다 :)

이미지 사용할 때 주의사항

Next.js에서 next/image 컴포넌트를 사용할 때는 이미지 경로 앞에 basePath를 꼭 붙여줘야 해요.

예를 들어, basePath가 /docs로 설정되어 있으면, 이미지 경로는 /docs/me.png로 지정해야 제대로 작동합니다. 이렇게 해야 이미지를 올바르게 불러올 수 있거든요.

import Image from 'next/image'

function Home() {
  return (
    <>
      <h1>나의 홈페이지</h1>
      <Image
        src="/docs/me.png"
        alt="작성자의 사진"
        width={500}
        height={500}
      />
      <p>홈페이지에 오신 걸 환영합니다!</p>
    </>
  )
}

export default Home

추가로, next/image는 기본적으로 이미지 최적화 기능을 제공해서 자동으로 크기 조절, WebP 변환 등 최적화 작업을 해주기 때문에 성능 향상에 큰 도움이 돼요. 하지만 외부 URL 이미지를 사용하거나 basePath가 꼭 필요한 경우에는 이 점을 꼭 기억하세요!