CSS parser
@symbiote-native/css-parser compiles a stylesheet — a .css/.module.css file, an inline
<style> block in a Vue SFC or a Svelte component, or an SCSS/Sass/Less/Stylus source — into
React Native style objects at build
time, inside a Metro transformer. The runtime half lives elsewhere: @symbiote-native/engine’s
style-registry (registerRules / resolveClassName) is what turns className="card" back
into a style object at render time. What to write in your stylesheets and how classes resolve per
adapter is covered by the Styling guide and How to: style a
component — this page is about the package itself: how it gets into your
Metro build, and what it exports.
Unlike every other package documented here, this one wraps no native module and ships no component. It is a Node-only build tool: it runs on the build machine and never enters the app’s native JS bundle. There is no per-OS difference, as one transform produces the same compiled style objects for iOS and Android.
Installation
Section titled “Installation”For the Metro transformer: nothing to install. @symbiote-native/react,
@symbiote-native/vue, @symbiote-native/angular, and @symbiote-native/svelte each depend on
@symbiote-native/css-parser directly and re-export it through their own ./metro-css-parser
subpath. An app that already has an adapter installed can point Metro at the transformer with no
extra dependency.
Install it directly only for the two development-time pieces — the css-dts CLI and the
TypeScript plugin, which your app’s own package.json and tsconfig.json reference by name:
pnpm add -D @symbiote-native/css-parserThe SCSS/Sass, Less, and Stylus compilers are optional and lazily loaded. sass, less, and
stylus are devDependencies of this package only, never regular dependencies — a project that
authors plain CSS never installs any of the three. The first compile of a .scss/.less/.styl
file whose compiler is missing throws an install instruction (sass is required for .scss/.sass files. Install it: npm i -D sass) rather than failing at import time.
Wire babelTransformerPath at your adapter’s ./metro-css-parser subpath and add the style
extensions to sourceExts so Metro treats a stylesheet as a source file. The subpath already
calls createCssMetroTransformer() for you — it exports a ready { transform, getCacheKey }
object, not the factory — so no local wrapper file is needed.
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const config = { transformer: { babelTransformerPath: require.resolve('@symbiote-native/react/metro-css-parser'), }, resolver: { sourceExts: [...defaultConfig.resolver.sourceExts, 'css', 'scss', 'sass', 'less', 'styl'], },};
module.exports = mergeConfig(defaultConfig, config);Then import stylesheets from any source file:
import './theme.css'; // plain CSS — registers classes globally, no exportimport styles from './Card.module.css'; // CSS Modules — default export is a name→scopedName map
<view className="card" style={styles.highlight} />A Vue SFC app points babelTransformerPath at @symbiote-native/vue/metro-vue-transformer
instead — the SFC transformer requires @symbiote-native/css-parser itself to handle a
<style> block, and delegates everything else. A Vue TSX app (no .vue files) points at
./metro-css-parser exactly like React.
// metro.config.js — Vue SFCconst { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const config = { transformer: { babelTransformerPath: require.resolve('@symbiote-native/vue/metro-vue-transformer'), }, resolver: { sourceExts: [ ...defaultConfig.resolver.sourceExts, 'vue', 'css', 'scss', 'sass', 'less', 'styl', ], },};
module.exports = mergeConfig(defaultConfig, config);// metro.config.js — Vue TSXtransformer: { babelTransformerPath: require.resolve('@symbiote-native/vue/metro-css-parser'),},Angular needs one extra Metro accommodation on top of the transformer: ngc compiles only
.ts into its own outDir, so a relative import './App.css' survives into the compiled
JS still pointing at the original source location that ngc never copies.
withSymbioteAngularMetroConfig supplies both the sourceExts additions and the
resolveRequest that redirects such an import back to the real source file.
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');const { withSymbioteAngularMetroConfig } = require('@symbiote-native/angular/metro-config');
const projectRoot = __dirname;const defaultConfig = getDefaultConfig(projectRoot);
const config = { transformer: { babelTransformerPath: require.resolve('@symbiote-native/angular/metro-css-parser'), }, resolver: { ...withSymbioteAngularMetroConfig(defaultConfig, projectRoot).resolver, },};
module.exports = mergeConfig(defaultConfig, config);withSymbioteAngularMetroConfig(defaultConfig, projectRoot, { outDir }) defaults outDir to
'build/angular' — pass it explicitly if your tsconfig writes ngc output elsewhere. The
ngc/linker pipeline never sees a .css file, so there is no conflict with the CSS
transformer.
A Svelte app points babelTransformerPath at @symbiote-native/svelte/metro-svelte-transformer
instead. That transformer requires @symbiote-native/css-parser itself, to compile a
component’s own <style> block (via its scoped-styles preprocessor, before the markup reaches
svelte/compiler). It also handles a standalone .css/.scss/.less/.styl import through
the same createCssMetroTransformer React’s transformer uses, and delegates everything else.
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const config = { transformer: { babelTransformerPath: require.resolve('@symbiote-native/svelte/metro-svelte-transformer'), }, resolver: { sourceExts: [ ...defaultConfig.resolver.sourceExts, 'svelte', 'css', 'scss', 'sass', 'less', 'styl', ], },};
module.exports = mergeConfig(defaultConfig, config);Then import stylesheets from any source file, .svelte included:
<script lang="ts"> import './theme.css'; // plain CSS — registers classes globally, no export import styles from './Card.module.css'; // CSS Modules — default export is a name→scopedName map</script>
<view class="card" style={styles.highlight} />Solid needs no SFC/.tsx transformer of its own - JSX compiles through a plain Babel preset
(@symbiote-native/solid/babel-preset), not Metro. The only babelTransformerPath here is
this framework-agnostic stylesheet one, same setup as React’s.
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const config = { transformer: { babelTransformerPath: require.resolve('@symbiote-native/solid/metro-css-parser'), }, resolver: { sourceExts: [...defaultConfig.resolver.sourceExts, 'css', 'scss', 'sass', 'less', 'styl'], },};
module.exports = mergeConfig(defaultConfig, config);Then import stylesheets from any source file:
import './theme.css'; // plain CSS — registers classes globally, no exportimport styles from './Card.module.css'; // CSS Modules — default export is a name→scopedName map
<view class="card" style={styles.highlight} />Typed CSS Modules keys
Section titled “Typed CSS Modules keys”The css-dts bin and the language-service plugin are the devDependency half — wire them once in
package.json and tsconfig.json:
{ "scripts": { "pretypecheck": "css-dts ." } }{ "compilerOptions": { "plugins": [{ "name": "@symbiote-native/css-parser/typescript-plugin" }] }}Both are needed, and why is spelled out in the Styling
guide: a
tsconfig.json plugin is invisible to a standalone tsc/CI run, and an on-disk .d.ts gives no
feedback while you type.
Everything below is exported from the package barrel @symbiote-native/css-parser. All of it is
Node-only, meant to run inside a Metro transformer or a CLI — none of it is importable from app
code that ships to the device.
Metro transformer
Section titled “Metro transformer”| Signature | Description |
|---|---|
createCssMetroTransformer(upstreamTransformer?: IMetroTransformer): IMetroTransformer |
Builds the { transform, getCacheKey } object Metro’s babelTransformerPath expects: compiles a recognized style file, delegates every other file to the upstream transformer unchanged. Defaults the upstream to resolveUpstreamTransformer() |
resolveUpstreamTransformer(): IMetroTransformer |
Resolves @react-native/metro-babel-transformer relative to this package (a real dependency of it), so a custom per-framework transformer can delegate its own passthrough branch without a fragile direct require |
relabelForUpstream(params: IMetroTransformParams, src: string, extension: string): IMetroTransformParams |
Builds the params for the upstream call when a framework transformer hands it compiled JS under a made-up name (Home.vue as Home.vue.tsx). If the app lists the worklets plugin, its entry is added with disableSourceMaps on and its other options kept, as the plugin would otherwise read a file that is not on disk |
transform() is async for every recognized extension, plain .css included — Metro’s own
transform worker awaits the call either way, and Less/Stylus have no synchronous render API.
Compiler core
Section titled “Compiler core”| Signature | Description |
|---|---|
compileCssToRules(css: string, options: ICompileRulesOptions): ICompiledCss |
Compiles plain CSS text with lightningcss into a list of rules, each with its class tokens, specificity, source order and RN style. It also returns the @media and @container condition table, the :root custom properties and the @property rules |
compileScopedCss(css: string, options: IScopedCssOptions): IScopedCss |
The same compile for a scoped block (a Svelte <style>, a Vue <style scoped>). It returns the rules under their scoped names and the name map the markup rewriter resolves class tokens through |
compileCssModule(css: string, filename: string): ICompiledCssModule |
One source compiled as a CSS module: scoped rules, the classMap default export, and the same condition, variable and property tables |
serializeRules(rules: readonly IStyleRule[]): string |
Renders rules as the JS literal a registration call takes |
conditionsArgument(conditions), propertiesCall(properties, conditions) |
Emit helpers for the trailing condition-table argument and the registerProperties(...) call |
hashFilePath(filePath: string): string |
A short deterministic id derived from a file path, used as the scope suffix so two files can each define .card without colliding in the shared runtime registry |
ICompileRulesOptions takes filename: string, an optional remToPx (the root font size used for rem) and an optional CSS Modules pattern
with [local] first. A rule outside any @media or @container has no cond. Otherwise cond indexes ICompiledCss.conditions, and
:root variables and @property rules index the same table.
Standalone stylesheet files
Section titled “Standalone stylesheet files”| Signature | Description |
|---|---|
compileCssFile(source: string, filename: string): Promise<ICompiledCssFile> |
Compiles one stylesheet file into JS module source. A plain file emits a registerRules(...) side-effect module with no export; a .module.* file additionally scopes every class to a per-file hash and default-exports the name→scopedName map. Preprocessor sources are reduced to CSS first |
isCssModuleFile(filename: string): boolean |
Whether a filename’s stem ends in .module (Card.module.scss → true) — the check that decides scoped-with-a-map vs. global-side-effect output |
ICompiledCssFile has one field, code: string — the generated JS module source.
Preprocessors
Section titled “Preprocessors”| Signature | Description |
|---|---|
compile(source: string, lang: IPreprocessorLanguage, filePath?: string): Promise<string> |
Unified entry point: reduces any recognized language down to plain CSS text. lang: 'css' is a passthrough no-op |
compileScss(source: string, filePath?: string): Promise<string> |
Compiles SCSS, or the indented Sass syntax when filePath ends in .sass, to CSS. Sets sass loadPaths to the source file’s own directory so a relative @use/@import resolves as authored |
compileSass |
An alias of compileScss — one compiler entry point serves both syntaxes, picked off the file extension |
compileLess(source: string, filePath?: string): Promise<string> |
Compiles Less to CSS. Async because Less ships no synchronous render API |
compileStylus(source: string, filePath?: string): Promise<string> |
Compiles Stylus to CSS, wrapping its callback-based render in a Promise |
detectLanguage(filename: string): IPreprocessorLanguage |
Extension → language. .scss/.sass → 'scss', .less → 'less', .styl/.stylus → 'stylus'; anything unrecognized falls back to 'css' |
isStyleFile(filename: string): boolean |
Whether an extension is a stylesheet the transformer should claim at all — the “should I even look at this file?” check |
IPreprocessorLanguage is 'css' | 'scss' | 'less' | 'stylus'.
CSS Modules typing
Section titled “CSS Modules typing”| Signature | Description |
|---|---|
generateModuleDts(source: string, filename: string): Promise<string | null> |
Produces the .d.ts source for one CSS Modules file. Returns null for a non-.module.* file, which has no default export to type |
classNamesToDtsSource(classNames: readonly string[]): string |
Renders a sorted class-name list into .d.ts text — a readonly field per class, deliberately with no index signature, so a typo is a real TS2339 |
| CLI | Description |
|---|---|
css-dts [--watch] <dir-or-file> [...more] |
Walks the given paths and writes a sibling <file>.d.ts next to every .module.css/.module.scss/.module.less/.module.styl it finds, skipping node_modules, build, .git, and dot-directories. --watch regenerates on filesystem events, for live editor autocomplete without a running Metro |
| Subpath | Description |
|---|---|
@symbiote-native/css-parser/typescript-plugin |
A TypeScript language-service plugin synthesizing a virtual .d.ts for a .module.css import, so the IDE’s own TS server gives per-class autocomplete and typo errors on every keystroke |
- Node-only, never in the bundle. Nothing here is importable from app code that ships to the
device. The runtime counterpart — resolving a class name back to a style object — is
@symbiote-native/engine’sstyle-registry. - The transformer is delegating, not replacing. Any file whose extension
isStyleFiledoes not recognize is passed straight through to the upstream RN Babel transformer. Wiring it asbabelTransformerPathdoes not change how your.ts/.tsxfiles are compiled. sourceExtsis the half that’s easy to forget. Without the extension additions Metro never routes a.cssimport to the transformer at all, and the import fails to resolve. Note thatdetectLanguagealso recognizes.stylus; add it tosourceExtstoo if you use that spelling rather than.styl.@mediaand@containerstay on the rule as a condition, andvar()ships as raw text. The engine resolves them on the device, see the guide.@supportsand any selector carrying a pseudo-class (.card:hover) are dropped with a console warning before the rule walk. RN has no hover concept, and keeping the other declarations would merge hover-only styles into the base style.- The TypeScript plugin covers plain
.module.cssonly.getScriptSnapshotmust be synchronous, and Less and Stylus have no sync compile API —.module.scss/.less/.stylstill get their on-disk.d.tsfromcss-dtsatpretypechecktime, just no live per-class completion. The plugin’s regex extractor also splits a compound (.btn.primary) or descendant (.card .title) selector into two keys where the real compiler produces one. css-dtsis deliberately not wired into Metro. Metro’s transform is content-hash-cached and only touches files reached by the bundle graph it happens to be building; atsc/vue-tscrun in CI has no Metro at all.pretypecheckruns before every typecheck, local or CI, with no dev server involved.- No Tailwind. Whole-project class scanning and JIT utility generation is a different shape from “one source file reduces to CSS text” and is out of scope for this package.
How it works
Section titled “How it works”Two halves, split across build time and runtime:
.css / .module.css / .scss / .sass / .less / .styl className / class / addClass │ build time, inside Metro │ runtime, all adapters ▼ ▼@symbiote-native/css-parser @symbiote-native/engine's style-registry preprocessors -> compileCssToRules -> JS module source registerRules() / resolveClassName()A preprocessor source is reduced to plain CSS text first, so compileCssToRules is the single downstream
consumer either way. Scoping, :global() and CSS Modules behave the same regardless of source language.
compileCssFile then emits JS module source that calls registerRules(...).
That call is what lands in the bundle, and the compiler itself does not.
Each adapter’s metro-css-parser.cjs is a one-line re-export:
module.exports = require('@symbiote-native/css-parser').createCssMetroTransformer();That indirection is load-bearing. Node resolves a require() relative to the requiring file’s
location, so require.resolve('@symbiote-native/react/metro-css-parser') in your app’s
metro.config.js resolves @symbiote-native/css-parser from inside the adapter package, where it
is a real dependency — not from your app’s node_modules, which never needs to declare it. The
file is .cjs because the adapter packages are "type": "module" while Metro loads a
babelTransformerPath with require().