Style Adaptation for Taro 3.2 React Native: Architecture, Implementation, and Cross‑Platform Challenges

Taro 3.2 is scheduled for release at the end of March and the team is preparing technical articles; this piece focuses on the inner workings of adapting styles for the React Native target.

Background : Since Taro 3, 58.com has become a strategic partner responsible for the React Native portion of Taro. To improve developer experience, a new architecture was proposed that unifies style handling across platforms.

Adaptation challenges : React Native only supports a subset of CSS, lacks cascade, and does not allow class‑based static styles, which creates friction when porting web or mini‑program styles. The differences include (1) divergent style declaration APIs, (2) converting generic CSS files into JavaScript objects, (3) passing component styles, and (4) handling platform‑specific logic such as iOS shadow vs Android elevation.

Typical code comparison :

import React from "react";
import { StyleSheet, Text, View } from "react-native";

const App = () => (
  <View style={styles.container}>
    <Text style={styles.title}>React Native</Text>
  </View>
);

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#eaeaea" },
  title: { fontSize: 30, fontWeight: "bold" }
});

export default App;

and the equivalent Taro code:

// app.js
import React from "react";
import { Text, View } from "@tarojs/components";
import "./app.css";

const App = () => (
  <View className="container">
    <Text className="title">React Native</Text>
  </View>
);

export default App;

/* app.css */
.container { flex: 1; background-color: "#eaeaea"; }
.title { font-size: 30; font-weight: "bold"; }

Overall design flow (illustrated by a diagram in the original article):

Parse CSS files into an AST and convert each declaration to React Native style properties using css-to-react-native, then export a JavaScript style object.

Validate the generated style objects against the limited set of properties supported by React Native.

Transform className attributes into style attributes via a Babel plugin that rewrites JSX elements.

Key implementation details :

CSS → AST conversion uses the css package; each selector becomes a key in the exported object.

The resulting object is wrapped with StyleSheet.create:

import { StyleSheet } from 'react-native';
const cssObject = {/* ... */};
export default StyleSheet.create(cssObject);

Metro bundler is configured to treat style files as modules (see metro.config.js snippet) and to apply a custom transformer ( @tarojs/rn-style-transformer) that turns CSS strings into JS modules.

When multiple style files are imported, a Babel visitor merges them into a single stylesheet using a helper like mergeStyles(a, b).

The Babel plugin handling className performs three cases: plain string, expression, and coexistence with an existing style prop, converting them into an array of style objects or a runtime getStyle call.

Pre‑processor support : The pipeline also supports Sass, Less, Stylus, and PostCSS. For Sass, node-sass (with a future switch to dart-sass) parses files; Less and Stylus follow a similar pattern, exposing options and additionalData for global configuration.

Style validation : All style files pass through PostCSS plugins for linting (using stylelint-config-taro-rn) and to catch unsupported properties that would cause runtime errors on React Native.

Cross‑platform file handling : Platform‑specific style files are resolved in Metro’s resolver phase, and conditional compilation directives (e.g., #ifndef %PLATFORM%) are processed by a custom PostCSS plugin to include or exclude code based on the target platform.

Conclusion and future work : The current solution greatly improves the developer experience when using Taro with React Native, but limitations remain—especially around selector support and ordering semantics. The article discusses possible directions such as Atomic CSS and CSS‑in‑JS to mitigate these constraints.

References are provided for the underlying libraries and RFCs.