Express + TypeScript + Prisma 배포 시 Render에서 발생하는 흔한 오류 해결 가이드

핵심 기술

이 글은 Express, TypeScript, Prisma 스택으로 구축된 백엔드 애플리케이션을 Render에 배포하는 과정에서 발생할 수 있는 실질적인 문제점들과 해결 방법을 개인적인 경험을 바탕으로 상세하게 설명합니다. 특히 TypeScript의 전역 변수 인식 문제, devDependencies와 dependencies의 차이, 빌드 및 시작 명령어 설정, Prisma Client 생성 순서 등에 대한 구체적인 해결책을 제시합니다.

기술적 세부사항

• TypeScript 전역 변수 인식 오류: Cannot find name ‘process’., Cannot find name ‘console’. 와 같은 오류는 tsconfig.json에 {"compilerOptions":{"types":["node"]}} 설정이 누락되거나 @types/node 패키지가 devDependencies에 포함되어 발생할 수 있습니다. 해결을 위해 @types/node를 dependencies로 옮겨야 합니다.
• devDependencies vs dependencies: Render와 같은 프로덕션 빌드 환경에서는 기본적으로 devDependencies를 설치하지 않으므로, 빌드 타임에 필요한 타입 정의 파일(@types/node) 등은 dependencies에 포함되어야 합니다.
• 컴파일된 코드 경로 오류: Error: Cannot find module '/opt/render/project/src/index.js'와 같은 오류는 컴파일된 코드가 dist/index.js에 위치함에도 불구하고, package.json의 main 필드가 올바르게 설정되지 않았거나 Render 대시보드의 Start Command가 이를 반영하지 못해서 발생합니다. package.json의 main을 dist/index.js로 설정하고, Render의 Start Command를 npm start로 지정하는 것이 중요합니다.
• Prisma Client 생성 오류: @prisma/client did not initialize yet. Please run "prisma generate"... 오류는 Prisma Client가 사용되기 전에 prisma generate 명령이 실행되지 않았기 때문입니다. 빌드 스크립트에 prisma generate를 tsc 컴파일 이전에 실행하도록 추가해야 합니다 ("build": "prisma generate --no-engine && tsc").
• Prisma Output 경로: 커스텀 Output 경로 사용 시 예기치 않은 문제가 발생할 수 있으므로, 기본 경로(node_modules/.prisma/client)를 사용하는 것이 권장됩니다.
• Render 설정: Render 대시보드의 Build Command(npm run build)와 Start Command(npm start) 설정을 확인하고 올바르게 지정해야 합니다.

개발 임팩트

이 글은 Render와 같은 클라우드 환경에 TypeScript, Prisma를 사용한 Node.js 백엔드를 배포할 때 마주칠 수 있는 흔한 설정 및 빌드 오류들을 효과적으로 진단하고 해결하는 데 도움을 줍니다. 이를 통해 개발자는 배포 시간 단축 및 안정성 향상을 기대할 수 있으며, 문제 해결 능력을 향상시킬 수 있습니다.

커뮤니티 반응

글에서 직접적인 커뮤니티 반응은 언급되지 않았으나, 비슷한 배포 이슈를 겪는 많은 개발자들에게 유용한 정보 공유를 목적으로 작성되었습니다. 작성자는 다른 개발자들의 경험 공유를 통해 함께 학습하려는 의지를 보입니다.