nextjs / swagger-ui-react / Node.js 버전 호환 에러 : Class extends...

배우게 된 점 

- 개발서버- 테스트서버- 프로덕션 서버 node.js 버전을 동일하게 잘 관리하자.  

 

--------

next.js 14.1.2 버전 사용중

swagger-ui-react 5.3.0 버전

개발서버 node.js 20.x

테스트서버 vercel 18.x

 

문제상황

기존에 토이 프로젝트로 Nextjs 풀스택 앱을 만들었고, swagger로 API 문서를 발행하고 있었다.

- swagger-ui-react 라이브러리를 이용하여 만들었고

- api 문서는 개발용 및 테스트용으로 보여주는 것이기 때문에, 프로덕션 서버가 아닌 테스트 서버인 Vercel을 통해 접근할 수 있었다.

 

기존에 설치하지 않았던 eslint-config-next (14.1.3) 를 설치한 시점부터 빌드에 문제가 생겼다.

 

TypeError: Class extends valude undefined is not a constructor or null 

 

 

개발 환경에서는 문제가 안 일어나는데, 왜 테스트 서버에 빌드할 때만 문제가 나타나는가? 

이상했다.

 

import { getApiDocs } from "../../../utils/swagger";

import ReactSwagger from "./react-swagger";

//Swagger - api-docs

export default async function IndexPage() {

    try {

        const spec = await getApiDocs();

        return (

            <section className="container mx-auto min-h-screen px-3 py-3 md:px-24">

                <ReactSwagger spec={spec} />

            </section>

        );

    } catch (error) {

        console.error("Error while fetching API docs:", error);

        return <div>API 문서를 가져오는데 에러가 발생하였습니다. 잠시 후 다시 시도해주세요.</div>;

    }

}

 

"use client";

import SwaggerUI from "swagger-ui-react";

import "swagger-ui-react/swagger-ui.css";

export type SwaggerProps = {

    spec: object;

};

export default function ReactSwagger({ spec }: SwaggerProps): JSX.Element {

    return <SwaggerUI spec={spec} />;

}

 

swagger 관련 코드. 특히 props 문제 인 것 같아서 spec 관련하여 코드를 아무리 바꾸어봐도 개선이 없었다.

 

swager-ui-react 라이브러리도 재설치해고 node_modules도 삭제후 재설치 해보았지만 해결되지 않았다.

 

참고로 dynamic 방식으로 구성하는 방식도 문제 개선에 도움이 안 됐다.

문제 정의

https://github.com/swagger-api/swagger-ui/issues/9243

Swagger-ui-react not working with nextjs since 5.3.2 · Issue #9243 · swagger-api/swagger-ui

 

여러차례 삽질한 끝에 위 문서를 보고  node.js 버전의 문제의심을 했다.

 

개발 환경은 node 20.x 버전이었고

테스트 환경인 vercel에서는 node. 18.x 버전으로 활용되고 있었다. 

- vercel 환경의 node.js 버전에 대해 굳이 버전업을 하지 않은 이유는 beta 단계에 있기 때문이다.

 

 

앞서 node.js 버전에 대한 의문을 가지지 못했던 것은

개발 환경에서 에러가 발생하지 않고, 테스트 환경에 빌드할 때만 에러가 나는 나고 있었는데,

이것을 내 코드 문제로만 보았기 때문이다.

위에 링크로 첨부한 깃허브 이슈로 보아서, swagger-ui-react 라이브러리와 node 버전간에 호환성 문제로 의심을 해볼만했다.

 

 

문제해결전략

결국 Vecel의 Node.js Version을 18.x 에서 20.x로 바꾸었고,

Redeploy를 해보았다.

 

 

마침내 정상적으로 배포가 되었다.

 

 

 

배우게 된 점

1. 라이브러리를 도입하기 전에 node.js 버전 간의 호환성 문제를 살펴보자. 

 

2. 개발서버 버전 업을 조심스럽게 하자. 

- 특히, 동일 개발 서버에서 프로젝트가 늘어나서 여러 프로젝트가 진행되고 있다면 더더욱 주의해야한다.

- 이 라이브러리를 도입할 시점에 개발(로컬)서버는 node.js 18.x 버전이었다.

- 새로운 프로젝트를 시작하면서 개발서버를 LTS 버전인 Node.js 20.x 로 업그레이드 했다. 그리고 이때 별 문제가 없었다.

- 업그레이드하고나서도 한동안 문제가 없어서 문제를 파악하는데 더 애를 먹었다. 

 

3. 개발서버- 테스트서버- 프로덕션 서버 node.js 버전을 동일하게 잘 관리하자.  

Iaas 혹은 Paas 에서 라이브러리가 요구하는 node.js 버전(특히 상위 버전)을 지원하지 않는다면 난감한 상황이 발생할 수 있다.

 

다행히 나는 컨테이너 환경을 구성했기 때문에 런타임 환경을 바꾸면서 발생하는 어려움은 다소 적었다.

나의 경우 dockerfile로 런타임 환경을 nodejs 18 버전에서 node 20버전으로 상향하기만 하면 됐지만

 

AWS App Runner 대신, (이전에 사용을 고려했었던) AWS amplify 같은 다른 서비스를 사용했다면 node 20버전을 지원하지 않았기 때문에 난처하지 않았을까.  이로써 컨테이너 환경을 구성하는 것의 장점을 실감할 수 있었다.

 

p.s 3/15 런타임에서 node.js 버전을 18에서 20으로 상향하는 과정에서, 이미지 크기가 98mb 가량이나 늘어났다. 아직 큰 문제는 없지만 노드 버전을 올려서 그런건지 다른 무언가 때문인건지 파악해봐야할 것 같다.

 

p.s.3/25 용량 감소