Sharing styled-components theme and components between React DOM and React Native: what is the safe boundary?

Answer

The only portable part of styled-components across React DOM and React Native is the ThemeProvider and the plain JavaScript theme object it consumes. All other API surface – component definitions, CSS syntax, runtime helpers – is platform‑specific. Therefore:

• Theme sharing – export a plain theme object (e.g. { colors: { primary: '#ff0000' } }) and import it in both projects.
• Component sharing – not supported. A component created with styled.div cannot be rendered in React Native, and vice‑versa. Define platform‑specific wrappers (e.g. Button.web.js and Button.native.js) and expose a single name via Platform.select.
• Helpers that do work on both – css, attrs, as prop, and transient props ($$) are available in both packages, but features that rely on CSS pseudo‑selectors, media queries, or descendant selectors are only functional on the web. keyframes is a no‑op in the native package.
• SSR – ServerStyleSheet and other SSR APIs exist only in the web package.

Explanation

Styled‑components ships two distinct runtimes: styled-components for the browser and styled-components/native for React Native. Each runtime implements the same public API surface, but the underlying rendering engine differs. The ThemeProvider uses React context, which is identical on both platforms, so a shared theme object is safe. However, component definitions are tied to the underlying element type (<div>, <View>, etc.) and to CSS parsing. Mixing imports or attempting to render a web component in a native app throws a runtime error.

When sharing helper functions that do not import styled (e.g. token utilities, color helpers), you can keep them in a common module and import them wherever needed. Avoid importing styled or css from the web package into a native project.

Version‑Specific Nuances

• v5 vs v6 – v6 introduced a separate styled-components/native package. Ensure you install the correct dependency for each target.
• Transient props – added in v5.1. Older versions treat them as normal props and may emit warnings.
• SSR APIs – ServerStyleSheet is web‑only. Using it in a native bundle will throw a ReferenceError.
• Stylis – the web package uses Stylis for CSS parsing; the native package uses StyleSheet directly, so any Stylis‑specific features (e.g. nested selectors) are unavailable on native.

Practical Steps for Your Project

1. Create a shared theme.js exporting a plain object:

   export default {
     colors: { primary: '#0066ff', secondary: '#ff6600' },
     spacing: { sm: 8, md: 16, lg: 24 },
     typography: { h1: { fontSize: 32 } },
   };

2. In the web app, wrap the root with <ThemeProvider theme={theme}> from styled-components.
3. In the native app, wrap the root with <ThemeProvider theme={theme}> from styled-components/native.
4. Define platform‑specific styled components in separate files (e.g. Button.web.js and Button.native.js) and expose a single name via Platform.select in an index.js.
5. Export only pure helper functions (e.g. colorHelpers.js) that do not import styled from either package.