feat: module loading for stylesheets, imported constants, and remaining compat gaps

[owjs3901]

머지 순서: #675 → #676 → #677 → 이 PR. CI가 main 대상 PR에서만 돌기 때문에 base를 main으로 열었습니다. 이전 PR들의 커밋이 포함되어 있으며, 이 PR의 변경은 feat/compat-gaps-and-module-loader 브랜치에서 #677 이후 커밋들입니다.

요약

#677에서 남은 한계로 적었던 항목을 모두 해결하고, import한 상수를 정적 값으로 처리하는 최적화를 추가했습니다.
이후 라운드에서 StyleX 조건부 값, 빌드 타임 계산값(full 엔진), 상수 스타일 객체를 지원하고, 빌드가 읽을 수 없는 스타일은 조용히 버리지 않고 위치가 붙은 빌드 에러로 보고합니다.

모듈 로더 (.css.ts가 다른 모듈을 import)

• 번들러가 쓰는 방식으로 import를 해석하는 resolver를 받습니다: setModuleResolver((specifier, importer) => ({ path, code }))
  • Rust API: extract_with_modules
  • 각 플러그인은 createModuleResolver로 이를 등록합니다. 해석 대상은 상대 경로, tsconfig paths, theme.css→theme.css.ts 보완입니다.
• import된 스타일시트는 번들러와 같은 파이프라인으로 추출된 뒤, 그 출력을 평가합니다.
  • 그래서 export하는 클래스/변수 이름이 그 파일이 직접 내보내는 CSS와 정확히 일치합니다.
  • importer는 import "./theme.css"를 유지해서 해당 CSS가 번들에 포함되게 합니다.
• 일반 모듈도 지원합니다. 지원하는 export 형태: named, default, export { a as b }, export … from, export *, export * as ns
• 순환 import는 오류로 처리되고, 해당 스타일시트는 기존처럼 plain 추출로 폴백합니다.
• 읽은 파일은 Output.dependencies로 반환되고, 각 플러그인이 watch 대상으로 등록합니다.
  • vite addWatchFile, webpack/next/rsbuild addDependency, Turbopack coordinator는 응답에 포함합니다.
• .css.ts의 side-effect import(import './global.css')가 사라지던 기존 버그도 고쳤습니다.

import한 상수 인라인 (제안된 최적화)

• <Box color={PRIMARY} />에서 PRIMARY가 다른 모듈의 const 문자열/숫자이면, CSS 변수 대신 정적 클래스로 처리합니다.
  • 지원하는 형태: 리터럴, as const 객체의 멤버 접근, alias, re-export, default
• 스타일 위치(패키지 컴포넌트의 prop, 패키지 함수의 인자)에서 읽는 import만 resolver로 조회합니다.
• 원시값만 치환하고 scope를 고려해서 해석하므로(shadowing 안전) 런타임 동작은 같습니다.
• lite 엔진에서도 동작합니다.

호환성

• styled-components .attrs():
  • 객체와 함수 모두 지원하고, 순서대로 props 위에 병합합니다.
  • 함수 attrs는 사용자 코드일 뿐이라 스타일은 여전히 빌드 타임에 추출됩니다. 그래서 에러 대신 지원했습니다.
• .withConfig(): 제거합니다(런타임 옵션뿐입니다).
• 한 파일에 여러 라이브러리의 styled import가 있어도 모두 추출합니다.
• 조건부 조합(css(base, cond && {...}), 삼항, styled.div(...))은 속성별 삼항으로 병합합니다.
  • atomic 클래스 두 개의 우선순위는 스타일시트 순서로 정해지므로, 분기마다 클래스를 만드는 방식은 틀립니다.
  • 조건부 클래스는 cond ? cls : ''로 합칩니다. 기존에는 "false"가 출력되거나 스타일이 통째로 사라졌습니다.
• Emotion의 숫자→px 변환이 조건 분기 안까지 적용됩니다.

레이어 · 타이포그래피 (cascade)

• @layer 안의 동적 값도 레이어 안에 둡니다.
• 레이어가 클래스/변수 이름 키에 포함됩니다.
  • 기존에는 같은 값의 layered/unlayered 선언이 한 클래스를 공유해서 레이어가 무효화되는 버그가 있었습니다.
• 조건부 typography 프리셋 선언을 각 origin 안의 typography 레이어에 둡니다(t / oN.t / b.t).
  • 그래서 직접 쓴 선언이 조건부로만 적용되더라도 항상 프리셋을 이깁니다.

검증

• cargo fmt, clippy(full·lite·wasm32) 통과
• cargo test --workspace 통과
• bun test 전체 통과, 변경 파일 커버리지 100%
• bun run build, verify:dist 통과
• bun-plugin 회귀 테스트 통과
• 빌드된 wasm과 createModuleResolver로 실제 end-to-end 확인:
  • theme/button 스타일시트 간 클래스·변수 일치
  • 상수 인라인, 의존성 반환

추가: 남은 동작 해결

• 패키지 로딩: createModuleResolver가 bare specifier를 번들러처럼 node_modules에서 해석합니다.
  • exports: 문자열, 배열, 조건(import > module > default > require > node), * 패턴, null 차단
  • 그다음 module → main → index 순서, .cjs 포함
  • realpath로 해석해서 심볼릭 링크로 설치된 경우에도 번들러와 이름이 같습니다.
• CommonJS:
  • 로더가 module/exports/require 모듈을 평가합니다. default는 __esModule interop를 따릅니다.
  • 상수 인라인은 한 번만 할당된 export만 대상으로 합니다(TS의 void 0 placeholder는 제외). require 바인딩도 추적합니다.
• import 순환: ES 모듈 의미론으로 처리합니다.
  • 모듈 객체를 먼저 예약하고, live binding(getter)과 지연 바인딩을 씁니다.
  • 평가 전에 읽지 않는 순환은 동작합니다.
  • 너무 일찍 읽으면 binding과 모듈 이름을 담은 빌드 에러가 납니다. 이 경우 폴백하지 않습니다(vanilla-extract와 동일).
  • .tsx/.js 모듈은 각자의 source type으로 파싱합니다.
• 스타일 조합:
  • value || {...}, value ?? {...}를 지원합니다.
  • styled도 css()처럼 클래스를 조합합니다.
  • 빌드 타임에 알 수 없는 인자(호출, spread, 계산된 키)는 빈 클래스로 조용히 사라지지 않고, 인자를 명시한 빌드 에러가 됩니다.
• 검증:
  • 저장소의 apps·components·benchmark 파일 168개를 빌드된 wasm으로 추출해 봤고 실패는 0건입니다.
  • 임시 프로젝트로 end-to-end 확인: CJS 패키지 토큰 인라인, 지연 순환, 조기 읽기 에러, 조합 불가 에러

감사 라운드: 찾아서 고친 누락

• css(), globalCss(), keyframes(), stylex.create()는 런타임에만 알 수 있는 값을 빌드 에러로 보고합니다. 기존에는 아무도 설정하지 않는 CSS 변수를 출력하거나, 빈 선언(color:)을 남기거나, 선언을 버렸습니다.
• 파일 최상위의 문자열/숫자 const는 resolver 없이도 인라인하고, 상수에 대한 템플릿과 산술 연산을 접습니다(${SIZE * 2}px). StyleX 파일에도 적용됩니다.
• globalCss / createGlobalStyle / keyframes 템플릿의 보간(리터럴, 상수, 테마 읽기)을 CSS에 씁니다.
• 템플릿 mixin(${mixin}, ${p => cond && mixin})은 그 클래스를 조합합니다. 기존에는 mixin 자신과 다음 선언까지 조용히 사라졌습니다.
• 셀렉터나 속성 이름 자리의 알 수 없는 보간은 빌드 에러입니다.
• Next.js: prewarm한 추출 결과도 dependencies를 유지하므로, import한 모듈이 바뀌면 다시 빌드합니다.
• css-utils-literal-only 규칙이 빌드가 인라인하는 상수를 허용합니다.
• 변경 후 저장소 스캔: 파일 168개 추출, 실패 0건

개선 라운드

• webpack(및 Next.js webpack 모드): prewarm이 loader의 module resolver를 등록합니다. 이것이 없으면 다른 파일의 CSS 버킷에 합쳐진 파일이, webpack이 이미 만든 CSS에 없는 클래스를 쓸 수 있었습니다.
• StyleX: 다른 모듈(.stylex.ts 관례)에서 import한 defineVars / createThemeContract / defineConsts / createTheme 값을 그 모듈이 생성하는 이름으로 해석합니다. StyleX namespace/default import를 모두 인식합니다.
• vanilla-extract: 평가 중 예외를 던지는 .css.ts는 그 예외를 보고합니다. 기존에는 런타임에 여전히 style()을 호출하는 출력으로 폴백했습니다.
• 성능: 상수 인라인은 스타일이 상수일 수 있는 이름을 읽을 때만 scope를 분석합니다. 파일당 오버헤드 0.036 ms → 0.005 ms
• DX: 빌드 에러를 소스 순서대로 모아 file:line:column: message 형식으로 보고합니다. 위치는 import alias 변환 전의 원본 위치로 매핑합니다.
• 저장소 스캔: 파일 168개와 .css.ts 스타일시트 2개 모두 실패 없이 추출합니다.

StyleX 조건부 값

• defineVars / createTheme 값에 조건 객체를 쓸 수 있습니다.
  • 키: default, @media, @supports, @container([DARK] 같은 상수 키 포함)
  • types.*() 래퍼는 있어도 되고 없어도 됩니다.
• 조건 조합마다 조건 없는 값 뒤에 블록을 하나씩 만들고, 더 깊은 조건을 뒤에 두어 더 구체적인 값이 이기게 합니다.
• 정의한 파일과 그 파일을 import하는 파일 모두에서 동작합니다.
• 정적이지 않은 변수/테마 값은 변수가 조용히 빠지는 대신 빌드 에러가 됩니다.

빌드 타임 계산값과 StyleX 빌드 에러

• 상수에 대한 Math.* 호출을 빌드 타임에 접습니다(Math.max(SIZE, 20), Math.round, Math.PI). 반올림은 JavaScript 규칙을 따르고, 다른 값으로 가려진 Math는 건드리지 않습니다.
• css(), globalCss(), keyframes(), StyleX가 모듈 실행 시 상수로 계산하는 값(darken(0.1, PRIMARY), helper 호출)은 full 엔진(Boa)에서 계산해 정적 클래스로 만듭니다.
  • 그 값이 읽는 코드만 실행합니다.
  • 빌드가 결정론적이도록 Date와 Math.random은 쓸 수 없습니다.
  • JSX prop과 styled는 기존처럼 런타임 CSS 변수를 씁니다.
• 두 WASM 엔진 모두 hasBuildTimeValues를 export합니다. Next.js는 후보 파일에 계산이 필요하면 full 엔진을 선택하고, lite 엔진의 에러는 full 엔진을 안내합니다.
• StyleX create, defineVars, defineConsts, createTheme, keyframes, positionTry, viewTransitionClass, include는 읽을 수 없는 입력(spread, 계산된 키, 객체가 아닌 인자, 없는 테마 키, 구조 분해한 create())을 그대로 출력하거나 버리지 않고 위치가 붙은 빌드 에러로 보고합니다.
• stylex.props() / attrs()는 다른 곳에서 컴파일된 스타일(style prop, spread, 다른 모듈의 namespace)을 런타임에 합칩니다. 같은 파일의 namespace는 정적으로 해석합니다.

상수 스타일 객체와 빌드가 읽을 수 없는 스타일

• 파일에 선언했거나 import한 객체·배열·TypeScript enum 상수를, 스타일을 읽는 모든 위치에서 그 자리에 직접 쓴 것처럼 읽습니다: css(base), { ...base, color: 'red' }, _hover: hover, space[2], Size.M, <Box {...base} _hover={hover} />
  • 스타일 객체와 JSX prop 모두 JavaScript처럼 뒤 속성이 앞 속성을 덮습니다. 기존에는 두 클래스를 모두 출력해서 스타일시트 순서가 결과를 정했습니다.
  • 객체는 빌드가 스타일을 읽는 위치에서만 인라인하므로 props={...} 같은 런타임 prop은 원래 객체를 그대로 받습니다.
• 조용히 사라지던 경우는 위치가 붙은 빌드 에러가 됩니다: 알 수 없는 객체의 spread, 셀렉터(_hover)에 준 객체가 아닌 값, 계산된 키, 객체가 아닌 globalCss/keyframes 인자, styled 객체 형식 안의 props 함수. 알 수 없는 객체의 JSX spread는 기존처럼 런타임에 그대로 전달합니다.
• 조용히 틀리던 경우도 고쳤습니다.
  • 객체가 아닌 인자 하나를 받은 css(x) / styled.div(x)는 그 값을 클래스로 조합합니다(기존에는 버려졌습니다).
  • JSX의 객체 리터럴 spread가 스타일이 아닌 prop을 유지합니다(기존에는 onClick이 사라졌습니다).
  • bg={theme.colors[key]}는 CSS 변수가 됩니다(기존에는 사라졌습니다).
  • spread가 채울 수 있는 배열 인덱스나 객체 키는 런타임에 리터럴 전체에서 읽습니다(기존에는 잘못된 인덱스를 읽었습니다).
• full 엔진은 const나 import를 거친 값(토큰 파일의 const DARK = darken(...)), spread, shorthand 속성, 계산된 키, 런타임 조건도 계산합니다.
  • import는 필요할 때 로드하고, 스타일 패키지와 로드할 수 없는 모듈은 stub으로 대체합니다.
  • 예외를 던지는 모듈이나 선언은 그것에 의존하는 값만 잃습니다.
• hasBuildTimeValues(filename, code, package, importAliases)는 먼저 module resolver로 상수를 인라인하므로, 정말 평가가 필요한 값이 없으면 Next.js는 lite 엔진을 유지합니다(이 저장소에서 파일당 약 0.4 ms).
• 스타일시트 평가가 TypeScript enum에서 panic하지 않습니다.

남은 개선 항목

• 계산된 규칙 조합: full 엔진에서 css()/styled()가 조합하는 바인딩이 모듈이 계산하는 규칙을 담고 있으면 그 규칙을 적용합니다.
  • 예: const base = makeStyles(); css(base), styled.div(base)
  • 이전에는 클래스로 조합되어 런타임에 조용히 사라졌습니다.
  • 클래스를 담은 바인딩(css() 결과, 스타일시트에서 import한 클래스)은 그대로 클래스로 조합합니다.
  • 버그 수정: 다른 계산값 때문에 평가가 실행되면, 조합 위치에서 계산된 클래스 문자열이 CSS 텍스트로 읽히던 문제를 고쳤습니다. 조합 위치에는 객체·배열 결과만 씁니다.
  • Next.js 엔진 선택이 styled.div(...), styled(...)(...) 조합도 확인합니다.
• 에러 문구: 엔진별로 실제로 허용하는 범위를 말합니다.
  • full 엔진: "its values must be literals, theme tokens or constants, or be computed from them"
  • lite 엔진과 JSX 요소: "its values must be literals, theme tokens or constants"
  • 파일 안의 상수도 인라인되므로 "imported"를 뺐습니다.
• source map: import alias 변환이나 계산값 치환 뒤에도 원본 코드의 줄·열을 가리키고, sourcesContent는 원본 코드입니다. 이전에는 치환된 코드를 기준으로 해서, 여러 줄 계산값 뒤의 줄이 어긋났습니다.
• 평가 캐시: 다른 평가가 import한 스타일시트는 같은 스크립트면 한 번만 실행하고, 모듈의 TypeScript 제거 결과는 소스가 같으면 재사용합니다.
  • 파일 번호, 소스, 실행 스크립트를 모두 비교하므로 오래된 결과를 쓰지 않습니다.
  • 측정(release, 파일당): 헬퍼를 import하는 테마를 import하는 스타일시트 5.68 ms → 1.67 ms, 테마와 헬퍼를 import하는 스타일시트 6.48 ms → 5.18 ms, 계산값 5.12 ms → 5.01 ms
  • Boa가 import한 모듈을 평가마다 다시 컴파일하는 비용은 남습니다. 평가마다 새 컨텍스트를 써야 평가 사이에 상태가 섞이지 않아 결과가 결정론적이기 때문입니다.
• eslint css-utils-literal-only: 엔진이 읽는 범위에 맞췄습니다.
  • import하거나 모듈에 선언한 함수와 내장 함수(Math(단 Math.random 제외), String 등)로 상수에서 계산한 값은 허용합니다.
  • Date, Math.random, 매개변수처럼 런타임에만 아는 함수는 보고합니다.
  • README에 계산값과 필요한 엔진을 설명했습니다.
• 검증:
  • extractor 테스트 1382개, cargo test --workspace, clippy(full·lite·wasm32) 통과
  • bun 테스트 5267개 통과
  • 저장소 스캔: 176개 추출, 실패 0, 엔진 감지 68.1 ms

추가 점검에서 찾은 버그

• 동적 as가 JSX 자식 위치에서 코드를 망가뜨리던 버그 (main에도 있음): as={Link}, as={cond ? 'a' : 'b'}처럼 리터럴이 아닌 as를 JSX 자식으로 쓰면 결과가 틀렸습니다.
  • 부모 요소 전체가 대체되거나(<section>이 사라짐), 뒤의 다른 식({on}, 형제의 title)이 대체됐습니다.
  • <Box>가 출력에 남아 런타임에 "Cannot run on the runtime" 에러가 났습니다.
  • 목록(items.map(... <Box key={id} as={C} />))에서는 key 없는 fragment로 감싸져 React key 경고가 났습니다.
  • 이제 요소가 있던 자리(식, 자식, 속성 값)에 바로 대체합니다.
• 런타임 값을 CSS 텍스트로 최적화하던 버그 (main에도 있음): 요소가 런타임에 받는 값의 코드에 CSS 최적화가 적용됐습니다.
  • 함수에 넘기는 문자열의 숫자가 바뀌었고(f('#336699') → f('#369'), '10px 0px' → '10px 0'), --i가 var(--i)가 됐습니다.
  • 이제 코드를 그대로 씁니다.
• 런타임 값 누락: await, new, 대입, 쉼표 식, tagged template 값이 조용히 사라졌습니다. 이제 CSS 변수로 전달하고, 함수·클래스는 에러로 보고합니다.
• spread 반복 평가 (main에도 있음): <Box {...register('email')} />처럼 다시 읽으면 값이 달라질 수 있는 spread를 spread, className, style에서 3번 평가했습니다. 훅이면 상태가 3개로 갈라집니다.
  • 이제 한 번만 평가합니다.
  • 앞에 쓴 props와 자식도 쓴 순서대로 평가하고, await/yield도 지원합니다.
  • 컴파일된 jsx() 호출도 같습니다.
• globalCss()를 값으로 쓰면 잘못된 코드가 나오던 버그 (main에도 있음): const a = globalCss(...)가 const a = ;가 됐습니다. 이제 void 0이 됩니다.
• 클래스를 바꿀 수 없는 곳의 런타임 조건: globalCss(), keyframes(), <Global>의 런타임 조건은 조용히 사라졌습니다. 이제 빌드 에러입니다.
  • 빌드가 아는 조건(const DARK = true; DARK ? 'white' : 'black')은 해당 분기로 접습니다.

계산값 확장

• JSX spread, 셀렉터 prop, styled 객체의 spread·셀렉터·계산된 키, css(...parts), css()의 템플릿 인자를 full 엔진이 계산합니다.
• 알려진 클래스만 담은 namespace/객체(css(styles.card))는 더 이상 모듈을 실행하거나 full 엔진을 선택하게 만들지 않습니다.
• 일부만 아는 객체의 중첩 멤버(css(tokens.nested.x))도 상수 경로로 판별합니다.
• Next.js 엔진 선택이 JSX spread와 셀렉터 prop도 확인합니다.
• 끝나지 않는 스타일시트는 빌드를 멈추는 대신 반복 한도에서 실패합니다.
• 에러 문구의 요구 조건을 엔진별로 정확히 씁니다. Cannot compose 에러는 spread 인자 이름(...rest)을 보여 줍니다.
• eslint css-utils-literal-only는 값 안에 쓴 콜백의 매개변수([1, 2].map((n) => n * 4))를 허용합니다.

추가 점검 검증

• extractor 테스트 1,390개와 cargo test --workspace가 통과하고, clippy(full·lite·wasm32)는 경고가 없습니다.
• bun 테스트 5,269개가 통과합니다.
• 저장소 스캔: 176개 추출, 실패 0
• 빌드한 WASM으로 동적 as, spread 1회 평가, 계산값을 직접 확인했습니다.

lite 엔진 제거

사용하는 곳이 우리 플러그인뿐이어서 엔진을 Boa가 들어간 하나로 합쳤습니다.

• @devup-ui/wasm은 빌드를 하나만 만듭니다. @devup-ui/wasm/lite export와 lite 빌드, 엔진을 고르는 데만 쓰던 hasBuildTimeValues를 없앴습니다.
• Rust vanilla-extract feature를 없애고 Boa를 extractor·sheet·wasm crate의 일반 의존성으로 바꿨습니다.
• Next 플러그인은 시작할 때 프로젝트 파일을 훑어 엔진을 고르지 않고 항상 @devup-ui/wasm을 불러옵니다. 그래서 dev 서버 실행 중에 추가한 파일도 다른 파일과 똑같이 처리됩니다.
• 엔진 선택 때문에 WASM 로드 앞으로 옮겼던 import 그래프·prewarm 파일 수집은 원래 자리로 돌렸습니다.
• 문서, css-utils-literal-only README, changepack에서 lite와 엔진 선택 설명을 지웠습니다.

런타임에 바뀌는 값은 빌드 때 굳히지 않음

빌드 때 미리 계산한 값이 런타임에 계산한 값과 다를 수 있는 두 경우를 막았습니다.

1. 코드가 바꾸는 객체·배열·enum 상수

빌드가 볼 수 있는 코드에서 바꾸는 상수는 선언한 값으로 읽지 않습니다. 확인하는 파일은 스타일을 쓰는 파일, 상수를 선언한 모듈, 중간에 re-export하는 모듈입니다.

• 바꾸는 코드로 보는 것:
  • 멤버 대입, delete, ++
  • push·sort 같은 메서드, Object.assign
  • 빌드가 모르는 함수에 넘기기
  • 바뀌는 다른 객체에 담기
• 바꾸는 코드로 보지 않는 것:
  • 담긴 문자열·숫자를 넘기기. 예: darken(colors.primary)
  • 아무도 바꾸지 않는 top-level const에 담기. 예: const theme = { colors }
• 이런 상수를 쓰면 이렇게 처리합니다.
  • 요소 prop에서 멤버를 읽으면 런타임 CSS 변수가 됩니다.
  • css(obj), styled.div(obj), <Box {...obj} />처럼 객체 전체를 받으면 빌드 에러가 납니다. 에러에는 바꾸는 위치(src/tokens.ts:10:26)를 적습니다.
  • Boa로 계산하는 값도 이 상수를 읽지 않습니다.
• 빌드가 볼 수 없는 모듈에서 바꾸는 경우는 감지할 수 없습니다. 그래서 "스타일에 쓰는 객체는 런타임에 바꾸지 말고, 바뀌는 값은 테마 토큰이나 prop으로 쓴다"는 규칙을 문서에 적었습니다.

2. 실행 환경에 따라 달라지는 코드

Boa로 계산할 때 아래 값을 읽으면 에러가 납니다. 그래서 그 값에 의존하는 계산은 빌드 때 하지 않습니다.

• 읽을 수 없는 값: window, document, navigator, location, process, globalThis에서 정의되지 않은 속성
• 예: typeof window === 'undefined' ? ..., process.env.NODE_ENV, globalThis.BRAND ?? 'red'
• 이런 값은 빌드 환경에서 나온 분기가 CSS에 박히는 대신, css()에서 빌드 에러가 납니다.

lite 제거·런타임 값 검증

• CI green: 5db2b827(lite 제거), 8866988a(런타임 값). bfd18e60에서 커버리지가 두 줄 모자라 테스트를 보강했습니다.
• 로컬 확인
  • cargo: fmt, clippy -D warnings(host·wasm32), test --workspace
  • bun: 5264개 테스트 통과
  • tarpaulin: CI와 같은 포맷으로 돌려, 새로 바뀐 줄 중 커버되지 않은 줄이 없음을 확인
• 새 테스트
  • mutations::tests: 바꾸는 코드, 넘기기, 읽기, 전역 이름을 가린 경우를 분류하는지 확인
  • test_changed_constants 스냅샷 21개 케이스
    • 로컬·import·re-export 상수가 바뀌는 경우
    • 문자열만 넘기는 경우, 다른 const에 담는 경우, 순환 참조
    • Boa 입력, window·process·globalThis