kstyled 0.4.0

0.4.0 establishes a stricter compiler and runtime contract. It focuses on predictable native output, lower render-time work, and preserving the APIs developers already use in React Native and Expo applications.

This release is published on the latest dist-tag. The previous 0.3.8 release remains available by exact version for applications that need a staged migration.

Install

Keep the runtime and Babel plugin on the same version:

pnpm add kstyled@0.4.0
pnpm add -D babel-plugin-kstyled@0.4.0

The latest tag resolves to the same versions:

pnpm add kstyled@latest
pnpm add -D babel-plugin-kstyled@latest

Configure kstyled before plugins that must run last, including Reanimated:

babel.config.js

module.exports = {
  presets: ['babel-preset-expo'],
  plugins: [
    ['babel-plugin-kstyled', { strict: true }],
    'react-native-reanimated/plugin',
  ],
};

Use strict: true in CI so unsupported compiler input fails the build instead of silently using the runtime parser.

What changed

More work moves to build time

Function-scoped css templates now compile to native style expressions. Static declarations are registered once, while only prop- or theme-dependent values remain as small runtime functions.

The compiler also handles shortcut attrs, nested transform arrays, shadow offsets, and numeric normalization expected by React Native Fabric.

Composition preserves behavior

Extending a styled component now preserves parent dynamic styles, chained attrs, refs, as, and transient props. Nested styled wrappers collapse to the original render target without losing colliding compiled style keys.

Themes are typed without ceremony

defineTheme preserves the concrete theme shape and useTheme supports an explicit generic when a reusable hook needs it:

const theme = defineTheme({
  colors: { accent: '#087A55', onAccent: '#FFFFFF' },
  space: { control: 12 },
});

type AppTheme = typeof theme;

function useAppTheme() {
  return useTheme<AppTheme>();
}

Package exports are explicit

React Native and CommonJS consumers resolve the CJS build. ESM consumers receive matching modules and declarations. Both packages include source maps and explicit export maps so bundlers do not have to infer entry points.

Migration notes

Most 0.3.x applications do not need source changes. Review these points before upgrading:

1. Upgrade kstyled and babel-plugin-kstyled together.
2. Put the kstyled Babel plugin before Reanimated or other last-run plugins.
3. Enable strict: true in CI and fix any template the compiler reports.
4. Keep style-only values in transient props such as $selected.
5. Remove reliance on wrapper component identity; composed styled components may now render the original native target directly.
6. Treat optimizeStatic, autoHoist, and platformStyles as deprecated. They are accepted for compatibility but no longer select a separate static runtime.

Validation checklist

Before rolling 0.4 across an application, verify:

• a clean Metro cache and production bundle build;
• representative light and dark theme screens;
• pressed, focused, disabled, and loading component states;
• iOS, Android, and React Native Web rendering;
• transient props do not reach native views;
• animated and externally supplied style props preserve Hook ordering;
• compiler output is clean with strict: true.

The repository validates lint, types, runtime and compiler tests, package builds, package contents, and the Expo example before a CI-only npm publish.

Feedback

Report a minimal reproduction in GitHub Issues. Include the React Native or Expo version, Babel configuration, target platform, and the smallest styled template that reproduces the behavior.