Feature/beyondworm 116, `shared` 프로젝트 듀얼 모듈 (CommonJS/ESM) 지원 및 `web-io-game` 통합 #54

gangjung · 2025-11-30T14:42:55Z

우선, Github Pages의 deploy를 로컬에서 테스트 할 수 있는 방법을 찾아보았습니다. 그러나 저희 프론트에서는 따로 작업해줄 것이 없었습니다. 왜냐하면 저희는 Vite로 빌드한 것을 그대로 github pages에 호스팅하는 방식이기 때문입니다. 일반적으로 github pages는 Jekyll, React, Next 등을 사용합니다만, 저희는 그렇지 않기에 따로 로컬에서 테스트 할 수 있는 방법은 없는 것으로 보입니다.

목표: shared 라이브러리를 Node.js 환경(백엔드)과 브라우저/번들러 환경(프론트엔드)에서 모두 효율적으로 사용할 수 있도록 CommonJS(CJS)와 ES Module(ESM) 두 가지 모듈 형식을 동시에 지원하도록 개선하고, web-io-game 프로젝트에서 이를 통합합니다.

주요 변경 사항:

shared 프로젝트 (듀얼 모듈 빌드 설정):
- package.json:
  - "main": "dist/cjs/index.js" 및 "module": "dist/esm/index.js" 필드를 추가하여 각각 CJS 및 ESM 진입점을 명시했습니다.
  - "exports" 필드를 상세하게 정의하여 import (ESM) 및 require (CJS) 조건에 따라 로드될 파일과 타입 정의를 분리했습니다. 이는 현대적인 모듈 해석 방식에 부합합니다.
  - build 스크립트를 수정하여 tsc를 두 번 실행, 첫 번째는 CJS(기본 tsconfig.json 설정), 두 번째는 ESM (별도의 --module ES2020 --outDir dist/esm 옵션)으로 빌드하도록 했습니다.
- tsconfig.json:
  - "target": "ES2020"으로 업데이트하여 최신 JavaScript 기능을 활용합니다.
  - "outDir": "dist/cjs"로 변경하여 CJS 빌드 결과물이 명확하게 위치하도록 했습니다.
  - "moduleResolution": "node" 및 "resolveJsonModule": true를 추가하여 모듈 해석 로직을 개선했습니다.
web-io-game 프로젝트 (shared 통합 방식 개선):
- vite.config.ts:
  - 개발 모드(command === "serve")에서는 @beyondworm/shared를 ../shared/src (원본 소스 코드)로 직접 alias하여, 개발 시 빠른 HMR 및 디버깅 경험을 제공합니다.
  - 프로덕션 빌드 시에는 shared의 package.json "exports" 필드에 따라 컴파일된 ES Module 버전을 자동으로 사용하도록 합니다.
  - optimizeDeps.include: ["@beyondworm/shared"]를 추가하여 개발 서버 시작 시 shared 의존성을 사전 번들링하여 성능을 최적화했습니다.

기대 효과:

shared 라이브러리가 백엔드(Node.js)와 프론트엔드(Vite 번들러) 환경에서 각각 최적화된 모듈 형식으로 사용될 수 있어 호환성과 유연성이 향상됩니다.
web-io-game 개발 시 shared의 소스 코드를 직접 참조함으로써 개발 편의성과 디버깅 효율이 증대됩니다.
shared 라이브러리의 배포 방식이 현대적인 표준(exports 필드)을 따르게 됩니다.

notion-workspace · 2025-11-30T14:42:58Z

Github page에서 검은화면만 나오는 이슈

gemini-code-assist · 2025-11-30T14:43:14Z

Summary of Changes

Hello @gangjung, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 PR은 shared 라이브러리가 Node.js(백엔드)와 브라우저/번들러(프론트엔드) 환경 모두에서 효율적으로 사용될 수 있도록 CommonJS(CJS)와 ES Module(ESM) 두 가지 모듈 형식을 동시에 지원하도록 개선하고, 이를 web-io-game 프로젝트에 통합하는 것을 목표로 합니다. 이를 통해 라이브러리의 호환성과 유연성이 향상되며, 개발 편의성 및 디버깅 효율이 증대됩니다.

Highlights

듀얼 모듈 지원: shared 프로젝트가 CommonJS(CJS)와 ES Module(ESM) 듀얼 모듈을 지원하도록 업데이트되었습니다.
web-io-game 통합: web-io-game 프로젝트에서 듀얼 모듈을 지원하는 shared 라이브러리를 통합했습니다.
package.json 업데이트: shared/package.json에 main, module, types 필드가 업데이트되었고, 현대적인 모듈 해석을 위한 exports 필드가 추가되었습니다.
빌드 스크립트 개선: shared의 빌드 스크립트가 CJS와 ESM 두 가지 형식으로 빌드되도록 수정되었습니다.
tsconfig.json 설정 변경: shared/tsconfig.json이 target: ES2020, moduleResolution: node, resolveJsonModule: true로 업데이트되었고, outDir이 dist/cjs로 변경되었습니다.
개발 환경 최적화: web-io-game/vite.config.ts에서 개발 모드(serve)일 때 @beyondworm/shared를 원본 소스 코드(../shared/src)로 직접 alias하여 HMR 및 디버깅 편의성을 높였습니다.
성능 최적화: web-io-game/vite.config.ts에 optimizeDeps.include: ["@beyondworm/shared"]를 추가하여 개발 서버 시작 시 의존성 사전 번들링으로 성능을 최적화했습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

shared 프로젝트에 듀얼 모듈(CommonJS/ESM) 지원을 추가하고 web-io-game에 통합하는 변경 사항을 검토했습니다. package.json의 exports 필드와 Vite의 조건부 설정을 사용하는 전반적인 접근 방식은 훌륭합니다. 하지만 package.json 설정에서 ESM을 사용하는 TypeScript 프로젝트의 타입 확인을 불가능하게 만드는 치명적인 문제를 발견했습니다. 또한, 빌드 스크립트의 크로스 플랫폼 호환성을 개선하기 위한 제안도 포함했습니다. tsconfig.json과 vite.config.ts의 다른 변경 사항들은 잘 적용된 개선 사항으로 보입니다.

gemini-code-assist · 2025-11-30T14:44:29Z

shared/package.json

+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/esm/index.d.ts",


build 스크립트(28번 줄)에서 ESM 빌드 시 --declaration false 옵션으로 인해 타입 정의 파일(.d.ts)이 생성되지 않습니다. 따라서 현재 경로 (./dist/esm/index.d.ts)는 유효하지 않으며, 이 패키지를 ESM으로 사용하는 TypeScript 프로젝트에서 타입 오류를 발생시킵니다.

CJS와 ESM 모듈의 타입은 동일하므로, CJS 빌드에서 생성된 타입 정의 파일을 참조하도록 경로를 수정해야 합니다.

Suggested change

"types": "./dist/esm/index.d.ts",

"types": "./dist/cjs/index.d.ts",

반영했습니다.

gemini-code-assist · 2025-11-30T14:44:29Z

shared/package.json

    },
    "scripts": {
-        "build": "tsc",
+        "build": "rm -rf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",


build 스크립트에 사용된 rm -rf 명령어는 Unix 기반 시스템(Linux, macOS)에서는 잘 동작하지만, 기본 Windows 환경에서는 호환성 문제가 발생할 수 있습니다.

모든 개발자가 동일한 환경에서 빌드를 성공시키기 위해, 플랫폼에 독립적인 rimraf와 같은 패키지를 사용하는 것이 좋습니다.

먼저 devDependencies에 rimraf를 추가해주세요 (npm install rimraf --save-dev 또는 yarn add rimraf --dev).

그 후 스크립트를 다음과 같이 수정하는 것을 제안합니다.

Suggested change

"build": "rm -rf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",

"build": "rimraf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",

이부분은 윈도우 환경에서도 테스트 해볼 필요가 있을것 같습니다.
테스트 방법이 따로 있을까요?

@wkdnffla3
제가 윈도우로 한 번 테스트 해보고 결과 적을게요!

konempty

고생하셨습니다 👍 👍
제미나이가 리뷰 준거 무시해도 되는건지 확인 한번만 부탁드립니다!

wkdnffla3 · 2025-12-01T00:02:08Z

shared/package.json

    },
    "scripts": {
-        "build": "tsc",
+        "build": "rm -rf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",


이부분은 윈도우 환경에서도 테스트 해볼 필요가 있을것 같습니다.
테스트 방법이 따로 있을까요?

gangjung · 2025-12-04T15:33:39Z

@wkdnffla3 @konempty
제미나이 코드리뷰 반영했습니다! 중요한 리뷰같아서, 리뷰 재요청 드립니다~
Merge 승인하기 전에 윈도우 테스트 확인하겠습니다!

wkdnffla3 · 2025-12-05T00:52:58Z

고생하셧습니다!!

gangjung · 2025-12-09T04:44:51Z

@wkdnffla3 @konempty
windows 환경에서 해당 명령어가 잘 실행되는 것으로 보입니다~

확인 Comment : #54 (comment)

스크린샷 :

gangjung added 2 commits November 30, 2025 23:36

shared 프로젝트를 프론드(vite)와 서버(commonjs)에서 각각 사용할 수 있도록 모듈을 나눠 빌드하도록 수정.

34ac170

lint 적용

8f29c73

gangjung requested review from konempty and wkdnffla3 November 30, 2025 14:42

gangjung self-assigned this Nov 30, 2025

gemini-code-assist bot reviewed Nov 30, 2025

View reviewed changes

konempty approved these changes Dec 1, 2025

View reviewed changes

wkdnffla3 approved these changes Dec 1, 2025

View reviewed changes

제미나이 코드리뷰 반영

85d9b34

gangjung requested review from konempty and wkdnffla3 December 4, 2025 15:33

wkdnffla3 approved these changes Dec 5, 2025

View reviewed changes

konempty approved these changes Dec 6, 2025

View reviewed changes

gangjung merged commit dd4ea68 into main Dec 9, 2025
1 check passed

	"types": "./dist/esm/index.d.ts",
	"types": "./dist/cjs/index.d.ts",

	"build": "rm -rf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",
	"build": "rimraf dist && tsc && tsc --module ES2020 --outDir dist/esm --declaration false --declarationMap false",

Feature/beyondworm 116, shared 프로젝트 듀얼 모듈 (CommonJS/ESM) 지원 및 web-io-game 통합 #54

Feature/beyondworm 116, shared 프로젝트 듀얼 모듈 (CommonJS/ESM) 지원 및 web-io-game 통합 #54

Uh oh!

Conversation

gangjung commented Nov 30, 2025

Uh oh!

notion-workspace bot commented Nov 30, 2025

Uh oh!

gemini-code-assist bot commented Nov 30, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

gangjung Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

wkdnffla3 Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

gangjung Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

konempty left a comment

Choose a reason for hiding this comment

Uh oh!

wkdnffla3 Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

gangjung commented Dec 4, 2025

Uh oh!

wkdnffla3 commented Dec 5, 2025

Uh oh!

gangjung commented Dec 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Feature/beyondworm 116, `shared` 프로젝트 듀얼 모듈 (CommonJS/ESM) 지원 및 `web-io-game` 통합 #54

Feature/beyondworm 116, `shared` 프로젝트 듀얼 모듈 (CommonJS/ESM) 지원 및 `web-io-game` 통합 #54