--- name: typo3-stylex description: Install, configure, or repair skom/stylex-connector with Vite in a Composer TYPO3 project, including manifest/class lookup and integration with existing CSS frameworks. Also use its token and recipe guidance for generic StyleX work; for Astryx-specific structure, themes, or design-system changes, use typo3-astryx. license: CC-BY-4.0 compatibility: Requires a Composer-based TYPO3 project with DDEV, a sitepackage, and Node.js with the project's package manager available in the DDEV web container. --- # TYPO3 StyleX Set up or repair the generic StyleX Connector/Vite pipeline and prove the CSS/manifest pair reaches Fluid. This skill applies whether or not the project uses the Astryx extension: treat Astryx as an optional integration, not a prerequisite. Keep the project's existing package manager, Vite plugins, sitepackage (when present), templates and asset delivery. For TYPO3 Astryx structure, built-in themes, token families or block ownership, use the companion [typo3-astryx skill](../typo3-astryx/SKILL.md); this skill supplies shared Connector/Vite and StyleX authoring guidance rather than a second Astryx manual. ## 1. Identify the live configuration Inspect composer.json and lockfiles, DDEV, active Site Sets or TypoScript, sitepackage package metadata, the actual rendered page layout, Vite entrypoints, and current CSS asset imports. Determine the TYPO3/package versions, asset owner, integration target and any existing StyleX source/manifest producer. Read the installed connector's current Vite setup and integration guides from vendor/skom/stylex-connector/Documentation/ or its checked-out source package. Treat those guides as authoritative for connector APIs and version-specific integration. If the project is TYPO3 Astryx, also use the [typo3-astryx skill](../typo3-astryx/SKILL.md) and its package-specific map; do not replace its existing entrypoints or theme bridge with a generic scaffold. For integration choices, read [integrations.md](references/integrations.md). Use typo3-ddev-vite for a base Vite AssetCollector pipeline issue that is independent of StyleX. Completion: the project root, rendered layout, sitepackage, asset delivery path, connector version and integration branch are identified from files or a running page. ## 2. Prepare TYPO3 and DDEV Follow the current connector setup guide before changing dependencies. Start DDEV and check TYPO3 and the web-container Node/package-manager version. Preserve existing Vite plugins and entrypoints. Confirm the sitepackage is Composer installed and its Site Set dependency is active on TYPO3 13/14; for TYPO3 12, use the connector's documented TypoScript path. Completion: the page renders before asset changes, and DDEV can execute the selected package manager. ## 3. Wire Vite asset delivery Follow the current connector guide for package versions, Vite AssetCollector and sidecar requirements. Ensure Configuration/ViteEntrypoints.json points to a real private entrypoint, that entry imports its JavaScript and CSS, and that the layout TYPO3 actually renders calls vite:asset once for that EXT: entrypoint. Do not register the same CSS/JS again through TypoScript or a second layout. Completion: the target layout loads exactly the selected entrypoint, and the development Vite endpoint is configured. ## 4. Compile StyleX and expose manifest keys Follow the connector guide for the installed version of @stylexjs/unplugin, the Vite StyleX plugin and its manifest adapter. Keep manifest output aligned with `StylexRegistry::registerManifest()` in the package that owns manifest registration (often the sitepackage). Use the project's existing Node dependency root; do not create package-local node_modules. Import a small stylex.create() recipe from the entrypoint and make its generated key available through the project's manifest. In Fluid, use stylex:class or the project's documented wrapper ViewHelper. In development, load the connector's virtual CSS once after the entrypoint imports. Avoid also enabling StylexConnector.includeCssViaTypoScript when Vite already delivers the same CSS. Completion: the key exists in the manifest, the corresponding compiled CSS is in the entry output, and the Fluid template uses the same key. ## 5. Author tokens and recipes without drift When this pipeline task includes StyleX authoring, use these defaults in any TYPO3 project. They are general authoring guidance, not requirements imposed by the connector. For Astryx-specific source paths and runtime contracts, follow the [typo3-astryx skill](../typo3-astryx/SKILL.md). ### Tokens and themes - Use `stylex.defineVars` for shared values that need themes or runtime scope, and `stylex.defineConsts` for shared compile-time values that do not. Keep declarations statically analyzable by the installed compiler and group tokens by semantic family, such as color, typography, spacing, layout, shape, effect and motion. - Name public tokens by semantic role and intended use, not raw value, current visual treatment, theme or mode. Follow the project's public namespace and lowercase kebab-case convention; a useful shape is `--{namespace}-{domain}-{role}-{variant}-{property}`, omitting segments that do not help explain use. For example, a text color token should describe the text role, not a hex value or a specific theme. Keep component-private custom properties distinct from the public token namespace. - Keep token meaning stable across themes and vary values in theme definitions. Keep theme identity separate from color mode; use mode-aware values (such as `light-dark()` for color where supported) instead of encoding modes into token names or creating duplicate theme identities for each mode. Theme overrides should preserve the same semantic contract and provide all values required by the project's theme-boundary strategy, including nested scopes. - Do not promote every local literal to a public token. Tokenize values that are reused or form a deliberate theming/customization contract; keep one-off recipe details local. Component-specific tokens are appropriate when they are an intentional public customization surface, not merely because a component has styles. - When adding a token, edit its owning `defineVars` family; register a new family in the project's token/build registry and import it wherever token declarations must be emitted. Recipes should import and reference the exported StyleX variable. If an integration stylesheet needs the same value, use the public custom property there rather than defining a duplicate. Put theme-specific overrides in the project's supported theme source and regenerate any generated token bridge through its documented build step. ### Recipes, ownership and build sources - Use `stylex.create` recipes to apply values to elements and define component layout, appearance, responsive behavior, states and finite variants. Tokens define values; recipes define how elements use them. Import token groups and reference their exported variables instead of repeating shared values or hard-coding generated CSS variable identifiers. - Use finite, static, meaningful recipe keys and the project's supported StyleX composition/ViewHelper pattern. Never hard-code generated atomic class names. Keep recipe module filenames lowercase kebab-case with the `.stylex.js` suffix when this matches the project's build convention. Where a manifest adapter exposes basename aliases, keep basenames unique in each merged manifest. A basename change may alter Fluid-facing keys, so update callers and validate the rebuilt manifest together. - Keep each source with the package or feature that owns and consumes it: shared recipes and tokens in the shared styling package, site styling with the site, component-only styling with that component, and integration styles at the integration boundary. A public reusable component can justify a shared recipe even if it has one current consumer; a generic filename alone does not make a single-use recipe shared. Import every source from the Vite entrypoint that needs it; an unreferenced source is not compiled. - Edit authored StyleX, token, theme and narrowly justified CSS sources. Treat compiled CSS, generated theme bridges, Vite and StyleX manifests, and packaged assets as build output. Regenerate these using the project's pipeline; do not hand-edit generated files. ### CSS boundary StyleX is the default for controlled component styling. Keep hand-authored CSS for a specific requirement that the installed compiler and Fluid rendering path cannot express or reliably apply. Examples include arbitrary rich-text/editor descendants (where the editor owns the markup or requires a stylesheet), font-face registration and resets/global defaults, browser constructs unsupported by the installed compiler, or third-party markup with no stable styling hook. For opaque third-party markup, first check whether its controller or owner can apply known StyleX classes; retain CSS only when that route is unavailable or unsafe. Document the technical reason beside the exception, keep it small and scoped, and use shared token values where possible. Do not retain CSS solely because it is familiar, block-specific, shorter to write, or already imported. Preserve the existing cascade-layer and stylesheet-order contract when moving rules; import aggregators should not become homes for component declarations. Do not assume the Connector compiles StyleX or infers every theme class. The configured build producer owns compiled CSS and manifest contents. Verify that every key used by server-rendered Fluid is emitted by the selected producer and that its CSS is delivered by the intended asset path. Completion: values and recipes have clear ownership, imported modules compile into the requested output, and the chosen manifest producer exports every Fluid key used by the template. ## 6. Prove the pipeline works Run the development server and open the rendered TYPO3 page. Confirm the HTML contains the generated class and the correct Vite entrypoint. Request the virtual StyleX CSS only after loading the entry and its imports; require a nonempty stylesheet with the expected selector. A 200 response with an empty body does not establish compilation. Stop the development server before the production build. Build with the existing package manager, flush TYPO3 caches, and inspect both the Vite manifest and registered StyleX manifest. Check that the entry lists CSS, referenced files exist, and the Fluid key is present. For production delivery, disable the development URI using the project's existing configuration, request the page while Vite is stopped, and confirm the emitted CSS/JS URLs work. Restore any temporary setting and flush caches after the check. Check a representative integration component if FSC, Bootstrap Package or standalone Bootstrap is present. Use integrations.md for cascade/layering decisions and inspect computed styles, not just build output. Repair failed stages and repeat the affected checks. Report commands and observed results. If DDEV, database or browser access is unavailable, name the blocked check and do not claim successful rendering from file presence alone. ## Safety Do not remove an existing stylesheet/framework, change database state or disable production delivery as an assumed side effect. Make temporary delivery changes only when the check requires them, record the original value, and restore it. Treat manifests and compiled CSS as build output. ## Related workflow - For Astryx package structure, installation/configuration, tokens, recipes, theme catalogues and site overrides, use the sibling [typo3-astryx skill](../typo3-astryx/SKILL.md). - For a base DDEV/Vite issue independent of StyleX, invoke typo3-ddev-vite. - For reusable sitepackage structure and Site Sets, invoke typo3-sitepackage. - For block schemas/templates beyond style wiring, invoke typo3-content-blocks.