[owjs3901]

Summary

PR #934 노트의 "Bun 런타임 플러그인은 프로젝트 자신의 .js를 컴파일하지 못한다"를 조사했습니다. 고칠 수 없다고 판단해 문서로 남깁니다.

조사 (Bun 1.4.4, 런타임 plugin() + --preload)

시도	결과
onLoad에서 node_modules 파일은 undefined를 돌려 Bun에 넘김	TypeError: onLoad() expects an object returned
filter에 lookahead /^(?![\s\S]*[\\/]node_modules[\\/])[\s\S]*\.js$/	동작합니다. node_modules 밖 .js만 받습니다. #934 노트의 "Bun filter는 lookahead를 지원하지 않는다"는 이 버전의 런타임 플러그인에는 맞지 않습니다.
위 filter로 받은 파일 중 Devup UI가 없는 파일은 원본 그대로 { contents, loader: 'js' } 반환	ESM 파일은 정상. CommonJS .js(require, module.exports)는 SyntaxError: Missing 'default' export로 깨집니다. Bun이 플러그인이 돌려준 소스를 ES module로 읽기 때문입니다. 플러그인 없이 실행하면 같은 파일이 정상입니다.

• 즉 filter를 좁히는 것은 가능하지만, filter에 걸린 파일은 반드시 소스를 돌려줘야 하고, 그 순간 CommonJS .js가 깨집니다. 어떤 .js에 Devup UI가 있는지는 파일을 읽어야 알 수 있어 filter(경로만 봄)로는 가를 수 없습니다.
• loader: 'object'로 require() 결과를 넘기는 우회는 같은 hook에 재진입하고, ESM의 live binding / top-level await를 잃어 채택하지 않았습니다.
• 그래서 프로젝트의 CommonJS .js(설정 파일, 스크립트 등)를 깨뜨리지 않고는 고칠 수 없다고 판단했습니다.

변경 (문서만)

• packages/bun-plugin/README.md: "Compiled Files" 절 추가. .ts/.tsx/.jsx/.mjs는 어디서든, .js는 @devup-ui 패키지 안에서만 컴파일되고, 프로젝트 .js의 Devup UI 코드는 런타임 placeholder(Cannot run on the runtime)에 닿는다는 것, .jsx/.tsx/.mjs로 바꾸라는 우회, 그리고 이유.
• limitations 페이지 Known limitations에 같은 내용 한 줄.

겹치는 PR

• fix(plugins): compile modern modules, resolve bundler conditions and hoist over every source root #934: Bun.build에서는 프로젝트 .js/.cjs도 컴파일하게 됩니다(빌드 hook은 값을 돌려주지 않아도 됨). #934가 머지되면 이 문서의 첫 문장을 "런타임에서는"으로 좁혀야 합니다.
• fix(bun-plugin): compile the .js files of included packages #925: include에 나열한 패키지의 .js도 컴파일합니다. 머지되면 "@devup-ui 패키지" 부분에 include를 더해야 합니다. 같은 README에 "Libraries" 절을 추가하므로 위치가 겹칠 수 있습니다.

문서만 바꾸므로 changepack은 없습니다.

Test plan

• 위 표의 동작을 Bun 1.4.4에서 최소 재현 스크립트로 확인
• bunx prettier --check (limitations mdx)
• git diff --stat: 라인 엔딩 churn 없음 (README는 index에서 CRLF/LF가 섞여 있어 원본 바이트를 유지해 삽입)

Refs #686

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.