안녕하세염.
이번 포스트에서는 NextJS 15.3.2 + React 19 버전 환경에서 Resium 라이브러리 설치 + 설정하는 방법을 적어보려고해염.

서론

Resium은 Cesium 라이브러리를 리액트 코드로 쓸 수 있게 만든 라이브러리에염.

우선 Resium 공식문서에 나와있는 방법과 큰 차이는 없어염.
Resium

근데 NextJS 프로젝트를 셋팅할 때

npx create-next-app@latest

대충 요런 커맨드로 설치하게되는데 현재 (2025.05.22) 일 기준으로 설치하면 우선 기본적으로 turbopack 번들러 기반으로 돌아가는 프로젝트로 설치가 되염.

근데 Resium 설치 공식문서에서 next.config.ts 관련 내용을 보면 요렇게 나와있어염.

근데 이렇게 설정하면 저희의 turbopack 기반 Next.js는 콘솔에 불만을 표시해염.

그래서 저희는 turbopack 을 꺼야대염.

package.json 들어가면 dev 스크립트 부분에 -- turbo 붙어있을텐데 그거 지워주세염.

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },

그리고 지금 turbopack 하고 resium 을 같이 쓰는게 어려워보여염.
혹시나 방법 아시는 분 있다면 댓글을 달아주면 좋겠네염.

시작

npm install --save cesium resium
# OR
yarn add cesium resium

cesium과 resium을 둘다 깔아주세염.
현재 (2025.05.22) 기준으로 설치했을때 깔리는 버전은 다음과 같아염

"resium": "1.19.0-beta.1",
"cesium": "^1.129.0",

그 다음 next.config.ts 파일로 들어가세염.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  reactStrictMode: true,
  webpack: (config, { webpack }) => {
    config.plugins.push(
      new webpack.DefinePlugin({
        CESIUM_BASE_URL: JSON.stringify("cesium"),
      }),
    );
    return config;
  },
};

export default nextConfig;

이거 복붙하세염.
공식문서랑 똑같아염.

npm install --save-dev symlink-dir
# OR
yarn add --dev symlink-dir

그 다음은 이 패키지를 설치하고
package.json 파일 들어가서 scripts 부분에 postinstall 부분 추가하세염.

{
  "scripts": {
  	...
    "postinstall": "symlink-dir node_modules/cesium/Build/Cesium public/cesium"
  }
}

그 다음

npm install
# OR
yarn

이 명령어 한번 입력해주세염.
postinstall 명령어를 한번 실행시키려고 해주는 작업이라고 이해하시면대염.

깃 쓰시면 .gitignore 파일에도 다음 항목 추가해주세염.

/public/cesium

이제 설치 끝났어염. 파일 아무거나 들어가서 Cesium을 한번 띄워볼게염.

우선 공식 문서에 나와있는데로 아무 파일이나 만들어서

이 코드로 띄워보면 안 나올 가능성이 높아염.

import { Viewer, Entity } from "resium";
import { Cartesian3 } from "cesium";

const position = Cartesian3.fromDegrees(-74.0707383, 40.7117244, 100);
const pointGraphics = { pixelSize: 10 };

function App() {
  return (
    <Viewer full>
      <Entity position={position} point={pointGraphics} />
    </Viewer>
  );
}

export default App;

Cesium Ion 홈페이지들어가서 Access Token을 받아야해염.
Cesium Ion
위 홈페이지에서 회원가입하고, 마이페이지 들어가서 토큰 발급받으면대염.

그 다음 코드로는 이렇게 적으세염.

import { Viewer, Entity } from "resium";
import { Ion, Cartesian3 } from "cesium";

Ion.defaultAccessToken = process.env.NEXT_PUBLIC_CESIUM_TOKEN || "";

const position = Cartesian3.fromDegrees(-74.0707383, 40.7117244, 100);
const pointGraphics = { pixelSize: 10 };

function App() {
  return (
    <Viewer full>
      <Entity position={position} point={pointGraphics} />
    </Viewer>
  );
}

export default App;

Ion.defaultAccessToken 에 발급받은 엑세스 토큰 넣어주는거에염.

이러면 지도가 뜰거에염.

끝!

배포 할 때 참고

여러분 위에서 심볼릭 링크로 cesium 모듈에 걸어서 썼었죠?

근데 이러면 vercel 배포할때 문제가 생겨염.
아마 다른 환경으로 배포할때도 문제가 생길 수 있어염.

그래서 이걸 어떻게 해야하냐?

node_modules 폴더에서 머리끄댕이 잡아서 꺼내와야해염.

node_modules/cesium/Build/Cesium

이 폴더를 복사하고

프로젝트 루트 /public 폴더에 넣어주세염.

Cesium -> cesium 으로 이름도 바꿔주세염.

postinstall 스크립트도 지워줘도되염.

이미지 표시에는 심볼릭 링크가 걸려있는것처럼 나와있는데, 사실 심볼릭 링크가 안걸려있어염.

그리고 .gitignore 에서 /public/cesium 이 부분 추가했던것도 없애주세염.

그다음에 배포하면 빌드에러 안날거에염.

(저의 경우 그랬음)

끝

도움이 됬으면 좋겠어염.

turbopack 하고 쓰려고 여러가지 해봤는데 잘 안되서 그냥 웹팩쓴게 좀 아쉽긴해염..

그럼이만. 질문있으면 댓글다세염. 아는거면 답글담