Skip to content

[전수조사/D] 흡수 라이브러리 기능: css prop, 컴포넌트 선택자, @emotion/css, VE·StyleX API #690

Closed

Description

@owjs3901

원 라이브러리에서 흔히 쓰는 기능 중 지원되지 않거나 조용히 빠지는 것들입니다.

전체 계획과 결정 사항은 추적 이슈(#682)에 있습니다. 조사 기준 커밋: 77daad74 (현재 main d0b84255).

결정에 따른 작업

  • (필수) Emotion css prop: import/pragma/tsconfig jsxImportSource/컴파일된 @emotion/react/jsx-runtime(include 라이브러리 포함; 감지 비용 측정 결과 MUI 1,312파일 약 2.9 ms). DOM 요소는 항상, 사용자 컴포넌트는 Emotion 신호가 있을 때만 컴파일. 사용자 컴포넌트의 동적 값은 style도 전달해야 함(문서화)
  • (필수) 컴포넌트 선택자: 선택자로 참조된 컴포넌트에만 짧은 marker class
  • (필수) @emotion/css: css/keyframes/injectGlobal/cx/merge. cx는 이슈 A의 정적 합성 사용
  • (필수) alias된 Emotion 파일의 배열 값은 fallback 의미(EMO-15)

발견 항목

심각도: P0 = 흔한 사용에서 조용히 틀리거나 크래시, P1 = 흔한 패턴이 명시적 에러로 막히거나 드물게 조용히 틀림, P2 = 드문 경우·도구/문서 불일치, P3 = 있으면 좋음.

필수 (7)

  • EMO-01 (P0, WRONG) Emotion css prop is never compiled in any source or compiled-JSX form (KNOWN-1)
    • 근거: css-prop-no-import.tsx emits <div css={{ color: 'red' }} /> and no CSS; css-prop-jsx-runtime.ts retains import { jsx } from '@emotion/react/jsx-runtime' and { css: { color:'red' } }; css-prop-css-result.tsx emits const style="a" but retains <div css={style}>
    • 수정 방향: recognize JSX css attributes independent of imports, Emotion jsx/jsxs factory calls and jsx-runtime subpaths; lower accepted values through the normal style extractor, remove css, and merge into className/style with Emotion precedence
  • EMO-03 (P0, WRONG) Nested composition silently drops serialized styles
    • 근거: react-css-nested-compose.tsx turns css({ '&:hover,&:focus': hotpink }) into export const hover = ""; only the unrelated base .a{color:hotpink} remains, with no hover/focus rule or error
    • 수정 방향: resolve known css-result bindings as nested rule fragments, preserving selector context; otherwise emit an explicit build error instead of empty output
  • SX-03 (P0, WRONG) attrs returns the wrong inline-style representation
    • 근거: Dynamic width produces { class: "b", style: { "--a": ... } }.
    • 수정 방향: Serialize dynamic variable declarations for attrs while retaining object form for React-oriented props.
  • VE-04 (P0, WRONG) companion CSS generators silently bypass Devup
    • 근거: recipe(...), defineProperties(...), and createSprinkles(...) remain verbatim while both per-file and whole-sheet Devup CSS contain no recipe/sprinkle rules. Only exact @vanilla-extract/css is aliased (packages/plugin-utils/src/types.ts:96-103); ordinary node_modules are skipped (packages/plugin-utils/src/shared.ts:46-60, packages/vite-plugin/src/plugin.ts:525-554…
    • 수정 방향: Either integrate/alias companion packages and generate their CSS, or detect these imports and issue a build error telling users to disable the Devup alias/use the vanilla-extract plugin.
  • EMO-12 (P1, ERR-gap) Emotion component selectors fail in both template and object forms
    • 근거: styled-selector-template.tsx errors Cannot place Child; styled-selector-object.tsx errors on [Child]
    • 수정 방향: assign a stable marker only to selector-referenced styled components and resolve bindings/computed keys to that marker; emit the marker in parent selector rules
  • EMO-15 (P1, WRONG) CSS fallback arrays are silently reinterpreted as responsive values
    • 근거: object-fallback-values.tsx turns background:['red','linear-gradient(...)'] into .a{background:red} plus @media(min-width:480px){.b{background:linear-gradient(...)}}; Emotion emits two same-rule declarations as browser fallbacks
    • 수정 방향: in Emotion-aliased rule objects, distinguish property-value arrays (fallback declarations) from top-level style arrays; do not route property arrays through Devup responsive semantics
  • EMO-16 (P1, MISMATCH) @emotion/css and create-instance are entirely outside alias handling despite DECIDED support (KNOWN-12)
    • 근거: every emotion-css-*.tsx probe retains imports/calls and emits no extracted CSS; DEFAULT_IMPORT_ALIASES at packages/plugin-utils/src/types.ts:98-103 lacks @emotion/css and its subpath
    • 수정 방향: add explicit @emotion/css mappings for extractable APIs and a deliberate policy/error for stateful low-level APIs; generate matching ambient declarations

권장 (12)

  • EMO-04 (P1, ERR-gap) Global supports only a direct object, rejecting documented static css-result and array forms
    • 확인 (Verified): fix(extractor): compile Emotion Global forms and styled identity options #922 — on main a8ad4c58 a css() class, a static array and a theme function all compile in <Global styles> (styled_compat_contract::global_class/global_array/global_theme). Follow-up fix(extractor): keep Emotion Global entries in the order they are written #1002 keeps object and css() entries in written order (they sat in different cascade layers)
    • 근거: react-global-css-result.tsx errors that "a" is not usable; react-global-array.tsx rejects a static array; react-global-theme-function.tsx rejects a function
    • 수정 방향: feed Global through the same composition flattener as css; support exact theme paths as CSS variables and retain explicit errors for genuinely runtime-only functions
  • EMO-13 (P1, ERR-gap) Function object styles are rejected although they are a primary Emotion styled form (KNOWN-7)
    • 근거: styled-function-object.tsx errors on props => ({ color: ... }); styled-theme-object.tsx errors on ({theme}) => ..., while the equivalent template interpolation works via CSS variables
    • 수정 방향: lower property-level exact branches to classes/variables using the same machinery as template functions; explicitly reject object shapes that are unknowable at build time
  • SX-04 (P1, ERR-gap) dynamic contextual values are rejected
    • 확인 (Verified): fix(extractor): compile StyleX contextual, typed and named-rule APIs as StyleX defines them #915 — { default, ':hover': size, '@media …': size } in a dynamic namespace gives one CSS variable per condition (probe on main: .d:hover{color:var(--a)}@media(min-width:600px){.c{color:var(--b)}})
    • 근거: A dynamic namespace with color:{default:'red', ':hover':size, '@media (min-width:600px)':size} errors that the object cannot be used at build time.
    • 수정 방향: Recursively decompose contextual objects in dynamic namespaces and bind each dynamic leaf to the generated runtime variable assignment.
  • SX-05 (P1, WRONG) all types.* wrappers lose typed custom-property semantics
    • 확인 (Verified): fix(extractor): compile StyleX contextual, typed and named-rule APIs as StyleX defines them #915 — defineVars emits @property --a{syntax:"<length>";inherits:true;initial-value:1px} per types.* helper; integer is checked (stylex_api_semantics::typed_variables)
    • 근거: Every helper (length, lengthPercentage, color, angle, integer, number, percentage, time, url, image, resolution, transformFunction, transformList) emits only :root{--a:<value>}. Code treats any types.* as a transparent first-argument wrapper (libs/extractor/src/stylex.rs:234-246,585-597).
    • 수정 방향: Carry the helper kind into variable metadata, emit one typed @property, and validate/cast helper-specific values (especially integer).
  • SX-06 (P1, WRONG) explicit global variable names are not preserved
    • 확인 (Verified): fix(extractor): compile StyleX contextual, typed and named-rule APIs as StyleX defines them #915 — defineVars({ '--global': 'black' }) keeps --global and colors['--global'] reads it (probe: :root{--global:black}.a{color:var(--global)})
    • 근거: Output is { "--global": "var(--a)" } plus :root{--a:black}, and use via colors['--global'] is separately rejected as non-static.
    • 수정 방향: Detect dashed custom-property keys before identifier allocation; keep --global in both returned reference and emitted root declaration, and resolve computed literal access.
  • SX-07 (P1, WRONG) positionTry output is semantically wrong and cannot be consumed
    • 확인 (Verified): fix(extractor): compile StyleX contextual, typed and named-rule APIs as StyleX defines them #915 — @position-try --a{position-anchor:--anchor;…} and positionTryFallbacks: fallback resolves to --a (probe on main)
    • 근거: Declaration probe emits @position-try --a{position-anchor:var(--anchor);...} for positionAnchor:'--anchor'; the documented consumption positionTryFallbacks:fallback errors that fallback is not static.
    • 수정 방향: Preserve dashed identifiers for anchor properties and register positionTry bindings as resolvable static identifiers in create.
  • SX-08 (P1, ERR-gap) viewTransitionClass implements the wrong input shape
    • 확인 (Verified): fix(extractor): compile StyleX contextual, typed and named-rule APIs as StyleX defines them #915 — { group, old, new } emits ::view-transition-group/old/new(*.a) rules (probe on main)
    • 근거: {old:{animationDuration:'2s'}, new:{animationDuration:'1s'}} produces two build errors saying nested objects are not static values. The extractor reads one flat declaration object (libs/extractor/src/extractor/extract_style_from_stylex.rs:42-71).
    • 수정 방향: Parse the four documented groups, emit pseudo-element rules, and reject only unsupported nested media queries.
  • SX-09 (P1, ERR-gap) contextual-selector APIs are absent
    • 근거: Dedicated probes for ancestor, descendant, siblingBefore, siblingAfter, and anySibling all error that the computed key “must be known.” The recognized API enum omits when (libs/extractor/src/stylex.rs:15-41).
    • 수정 방향: Implement marker values plus computed-key evaluation for each contextual selector and preserve StyleX's specificity ordering.
  • SX-10 (P1, WRONG) marker APIs escape to runtime
    • 근거: Transformed code still contains stylex.defaultMarker() / stylex.defineMarker() and runtime .flat(...).join(...); no marker CSS/value is generated.
    • 수정 방향: Recognize both APIs, generate deterministic marker references, and consume them from props and when.* without runtime StyleX calls.
  • SX-12 (P1, ERR-gap) media-query constants cannot form contextual keys
  • VE-02 (P1, ERR-gap) globalKeyframes is declared but not callable
    • 근거: globalKeyframes('fade-global', {...}) → JS execution error: TypeError: not a callable function. register_vanilla_extract_apis registers no such function (libs/extractor/src/vanilla_extract.rs:604-665), while packages/react/src/compat/vanilla-extract.d.ts:25-38 declares it.
    • 수정 방향: Register and serialize globalKeyframes(name, frames) in the Boa API; align the ambient declaration and add a stylesheet probe test.
  • VE-05 (P1, ERR-gap) css-utils cannot be evaluated in stylesheet mode
    • 확인 (Verified): fix(extractor): compile @vanilla-extract/css-utils calc to its strings #972 — calc('10px').multiply(2).toString() in a .css.ts gives width:calc(10px * 2) (probe on main)
    • 근거: Importing calc from @vanilla-extract/css-utils gives Cannot load '@vanilla-extract/css-utils' without a module resolver; the default alias table contains only @vanilla-extract/css.
    • 수정 방향: Statically evaluate this pure utility surface, or resolve the package through the stylesheet module resolver and guarantee deterministic output.

선택 (3)

  • EMO-07 (P2, WRONG) Emotion label is discarded in objects and emitted as an invalid CSS declaration in templates
    • 확인 (Verified): fix(extractor): compile Emotion Global forms and styled identity options #922 — label is dropped from objects and templates without emitting a label: declaration (probe on main), and migration/styled-components documents it
    • 근거: react-label-object.tsx yields .a{color:red} with no readable suffix; react-label-template.tsx yields .a{label:template-name}
    • 수정 방향: parse and remove label from rule generation; append a sanitized label only in a compatibility/debug naming mode, or document deterministic minified names and consistently discard it without invalid CSS
  • SX-11 (P2, ERR-gap) stylex.env configuration substitution is absent
    • 근거: stylex.env.tokens.colors.primary in create errors that it is not a literal, theme token, or constant; env is not a recognized API.
    • 수정 방향: Add an explicit Devup StyleX environment option and static member substitution, or document this experimental API as unsupported with a targeted diagnostic.
  • VE-03 (P3, MISMATCH) style debugId is accepted but ignored
    • 확인 (Verified): fix(extractor): name vanilla-extract style debug IDs under debug #959 — under debug, style({ color: 'red' }, 'root debug') adds root_debug-0-0 (probe on main)
    • 근거: style({color:'red'}, 'root debug') under --debug yields class color-0-red--255; sibling APIs produce --token_debug-0-0, area_debug-0-1, and utilities_debug-0-2.
    • 수정 방향: Carry style debug IDs into Devup debug class naming, or document that style debug IDs are intentionally not preserved.

제외 (3)

  • EMO-17 (P2, ERR-gap) Computed styled tag access remains a runtime read of an erased binding (KNOWN-13)
    • 확인 (Verified): fix(extractor): compile styled['div'] as styled.div #970 — styled['div'] compiles as styled.div (probe on main)
    • 근거: styled-bracket.tsx errors that styled is read at runtime
    • 수정 방향: accept static computed string members in styled-factory recognition; retain the explicit error for dynamic computed keys
  • SX-13 (P2, MISMATCH) alternate StyleX resolution policy is unavailable
  • SX-14 (P3, MISMATCH) Devup exposes a non-StyleX include() extension
    • 확인 (Verified): docs(landing): state StyleX resolution policy and legacy include() #969 documents include() as the legacy StyleX API Devup UI keeps
    • 근거: ...stylex.include(base.root) compiles successfully and is exported in Devup's compatibility surface, but the official API index has no JavaScript include; official include is a PostCSS path/glob option.
    • 수정 방향: Document and namespace the extension, or remove it from claims of StyleX API parity.

Activity

  1. 86 remaining items

  2. owjs3901 commented on Nov 18, 2026

    @owjs3901
    ContributorAuthor

    Re-verified every unchecked item against origin/main (a8ad4c58), compiling probes through the same WASM path the plugins use, and running Emotion 11 for upstream behavior.

    Checked now (13, evidence added under each item)

    New fixes

    For the owner to decide (not decided here)

    This issue stays open until #1004 is merged and the two decisions above are made.


    origin/main(a8ad4c58) 기준으로 체크되지 않은 항목을 모두 다시 확인했습니다. 플러그인과 같은 WASM 경로로 probe를 컴파일했고, 원본 동작은 Emotion 11을 실행해 비교했습니다.

    이번에 체크한 항목 (13건, 각 항목 아래에 근거 추가)

    새 수정

    오너 결정이 필요한 것 (여기서 정하지 않음)

    • (필수) 컴포넌트 선택자 "선택자로 참조된 컴포넌트에만 marker": main에서는 같은 파일에서 선택자로 참조된 컴포넌트뿐 아니라 export된 모든 styled 컴포넌트에도 marker가 붙습니다. 다른 파일이 선택자로 쓸 수 있기 때문입니다(docs(extractor): explain why exported styled components keep selector markers #907). 선택지: (a) 이대로 인정하고 체크 (b) 빌드 시작 시 전체 파일 스캔([전수조사/G] 결정성: 같은 소스는 항상 같은 출력 (파일·class 번호) #694)에서 어떤 파일이든 선택자로 참조할 때만 export에 marker 부여 (c) 다른 파일에서 선택자로 쓸 대상은 명시적으로 표시하게 함.
    • SX-09 (when.ancestor/descendant/siblingBefore/siblingAfter/anySibling): 지금은 위치 있는 빌드 에러입니다. 이 API는 조상·형제 요소에 marker class(defaultMarker()/defineMarker())가 필요한데, #682와 SX-10에서 marker API를 빌드 에러로 정했습니다. 선택지: (a) SX-10과 같이 빌드 에러를 유지하고 문서화된 것으로 SX-09 체크 (b) marker API와 when.*를 구현(marker class와 computed key selector, StyleX의 specificity 순서 유지).

    #1004 병합과 위 두 결정이 나올 때까지 이 이슈는 열어 둡니다.

  3. owjs3901 commented on Nov 18, 2026

    @owjs3901
    ContributorAuthor

    Component selectors, decision (b): "drop the marker when the build is certain nothing selects it" (#1009)

    • Certain, done: a styled component a file does not export can only be selected in that file, and the extractor sees every selector there before it gives markers. These components render without a marker unless a selector in the file names it (already the case since fix(extractor): compile Emotion component selectors at build time #730). test(extractor): pin that component-selector markers go only where a selector can read them #1009 pins this for Emotion and styled-components (rendered only, extended only privately, private base of an export, Emotion withComponent).
    • Not certain yet, marker kept: exported components. Each file is compiled without knowing its importers. The start-of-build reservation scan ([전수조사/G] 결정성: 같은 소스는 항상 같은 출력 (파일·class 번호) #694) works from a best-effort inventory, so it is not proof: Next Webpack's function entry gives no entries; root pages//components/, computed import(), require.context, virtual modules and compiled MDX are missed; Turbopack has no scan; Bun skips it in debug. Stripping markers after the build cannot work across client/SSR/RSC compilations. Dropping on the scan's word could break a selector silently.
    • Plan (needs owner OK, since it adds a build error): record the cross-module markers each module selects and filter only marker emission (keep selectors(), so the deterministic names stay stable). Enable it only in one-shot production builds with an inventory that spans every compilation. After transforms, check that every transformed module was in the inventory with the same code and that every marker selected is in the manifest; if not, fail with a located error. Watch/dev, Turbopack and setups without an inventory keep today's behavior.

    컴포넌트 선택자, 결정 (b): "아무도 선택하지 않는다고 확신하면 marker 제거" (#1009)

    • 확실함, 완료: export되지 않은 styled 컴포넌트는 같은 파일에서만 선택될 수 있고, extractor는 marker를 주기 전에 그 파일의 선택자를 모두 봅니다. 파일 안의 선택자가 이름을 부르지 않으면 marker 없이 렌더링됩니다(#730부터 이미 그렇게 동작). #1009에서 Emotion과 styled-components 양쪽으로 고정했습니다(렌더링만, private 확장만, export된 확장의 private base, Emotion withComponent).
    • 아직 확신 불가, marker 유지: export된 컴포넌트. 각 파일은 import하는 쪽을 모른 채 컴파일됩니다. 빌드 시작 예약 스캔([전수조사/G] 결정성: 같은 소스는 항상 같은 출력 (파일·class 번호) #694)은 추정 inventory로 동작하므로 증명이 아닙니다. Next Webpack은 entry가 함수라 entry가 비고, 루트 pages/·components/, 계산된 import(), require.context, 가상 모듈, 컴파일된 MDX가 빠지며, Turbopack은 스캔이 없고 Bun은 debug에서 건너뜁니다. 빌드 후 제거는 client·SSR·RSC 컴파일 사이에서 맞출 수 없습니다. 스캔만 믿고 지우면 선택자가 조용히 깨질 수 있습니다.
    • 계획 (빌드 에러가 새로 생기므로 오너 확인 필요): 각 모듈이 선택하는 다른 모듈의 marker를 기록하고, marker 출력만 거릅니다(selectors()는 유지해 결정적 이름이 바뀌지 않게 함). 한 번에 끝나는 production 빌드에서, 모든 컴파일을 아우르는 inventory가 있을 때만 켭니다. 변환 후 변환된 모든 모듈이 같은 코드로 inventory에 있었는지, 선택된 모든 marker가 manifest에 있는지 확인하고, 어긋나면 위치가 있는 에러로 실패합니다. watch·dev, Turbopack, inventory가 없는 설정은 지금 동작을 유지합니다.
  4. owjs3901 commented on Nov 18, 2026

    @owjs3901
    ContributorAuthor

    Decision: option (b), implemented in #1027.

    A one-shot production build with the Vite or webpack plugin drops a component-selector marker only when it is certain no module selects it. Each transform and the start-of-build scan report the markers they give and select. If a module selects a component but the scan never read it, the build does not fail. It keeps every marker and warns, naming each module and a category for the cause. Next.js with webpack uses the webpack plugin, so it drops them too; dev servers, watch builds, Turbopack, Rsbuild and Bun keep every marker for now.

    Known cases, so we can close them one by one until stripping can be on everywhere:

    Case Category Status
    src/, app/, static entry closure, include — covered
    require.context / import.meta.glob with literal arguments context-module covered (new in #1027)
    computed require.context / import.meta.glob / import() context-module warn + keep
    virtual modules virtual-module warn + keep
    MDX / Vue / Svelte / Astro (compiled before devup reads them) compiled-source warn + keep
    webpack function entry; root pages/ / components/ not imported from src/app outside-scan warn + keep
    scan could not extract a file scan-failed warn + keep
    dev / watch / HMR — keep
    webpack persistent cache (warm builds) — covered (reports restored from buildInfo)
    Next.js Turbopack, Rsbuild, Bun — keep (loaders don't report yet)

    결정: (b) 방식으로 #1027에서 구현했습니다.

    Vite 또는 webpack 플러그인의 일회성 production 빌드는, 어느 모듈도 component-selector marker를 선택하지 않는다고 확신할 때만 그 marker를 제거합니다. 각 transform과 빌드 시작 스캔이 자기가 주는 marker와 선택하는 marker를 보고합니다. 스캔이 읽지 못한 모듈이 컴포넌트를 선택하면 빌드를 실패시키지 않습니다. 모든 marker를 유지하고, 해당 모듈과 원인 카테고리를 경고로 알립니다. Next.js webpack 모드는 webpack 플러그인을 쓰므로 함께 제거됩니다. dev 서버, watch 빌드, Turbopack, Rsbuild, Bun은 당분간 모든 marker를 유지합니다.

    알려진 경우입니다. 하나씩 막아 가서 최종적으로 모든 빌드에서 제거를 켜는 것이 목표입니다.

    경우 카테고리 상태
    src/, app/, static entry closure, include — 커버됨
    리터럴 인자의 require.context / import.meta.glob context-module 커버됨(#1027에서 추가)
    계산된 인자의 require.context / import.meta.glob / import() context-module 경고 + 유지
    virtual 모듈 virtual-module 경고 + 유지
    MDX / Vue / Svelte / Astro(devup보다 먼저 컴파일됨) compiled-source 경고 + 유지
    webpack 함수형 entry, src/app에서 import되지 않는 루트 pages/·components/ outside-scan 경고 + 유지
    스캔이 추출하지 못한 파일 scan-failed 경고 + 유지
    dev / watch / HMR — 유지
    webpack persistent cache(warm 빌드) — 커버됨(buildInfo에서 보고 복원)
    Next.js Turbopack, Rsbuild, Bun — 유지(loader가 아직 보고하지 않음)
  5. owjs3901 commented on Nov 19, 2026

    @owjs3901
    ContributorAuthor

    Ticked:

    Remaining: SX-09 (StyleX contextual-selector APIs).


    체크한 항목:

    남은 항목: SX-09 (StyleX 문맥 선택자 API)

  6. owjs3901 commented on Nov 19, 2026

    @owjs3901
    ContributorAuthor

    SX-09 is fixed by #1012 (StyleX when.* relational conditions and markers compile at build time, no runtime JS). Every item in this issue is now ticked, so I'm closing it.


    SX-09는 #1012로 해결되었습니다(StyleX when.* 관계 조건과 marker를 런타임 JS 없이 빌드 타임에 컴파일). 이 이슈의 모든 항목이 체크되어 닫습니다.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions