How to Reduce Development Time by Migrating Legacy UI to Asterix
Coexistence of Legacy UI and Asterix
Replacing an entire design system in an existing project is prone to errors. Layouts often break, and functionality can become tangled. By using the StyleX engine, which Meta developed while managing over 13,000 apps over 8 years, you can safely coexist with existing CSS-in-JS.
Separate namespaces to ensure styles do not mix.
- Modify @astryxdesign/build settings so that library source code is compiled with the .astryx- prefix and existing code with the .x- prefix.
- Use CSS @layer, placing layers.css at the very top, and set the priority in the order of [reset, astryx-base, astryx-theme, product].
- Create a matrix that defines the scope of the transition, starting from atomic UI to layouts, and finally complex modules.
Using this isolation structure can save 40% of development time compared to a full refactor.
Syncing Tokens with Designers
If you do not align Figma design tokens with Asterix theme settings, visual discrepancies will persist. Instead of developers fixing code manually, resolve this with a JSON-based pipeline.
- Place a JSON schema in the root of the repository that defines colors, typography, and spacing.
- Configure CI/CD so that a GitHub Action automatically regenerates theme.ts when a designer pushes Figma tokens.
- Set up @stylexjs/eslint-plugin to prevent hardcoded inline values.
Once this process is complete, developers will use token variables like var(--spacing-3) instead of hardcoding. UI fragmentation disappears, and the use of autocomplete reduces errors.
Domain Component Automation
To increase the speed of new page development, you must reduce repetitive business logic and UI assembly. For complex modules, separate the rendering area from the state management logic.
- Separate data fetching and state control into pure React hooks.
- Use the Asterix CLI's swizzle command to eject core components into a local directory to gain full control.
- Connect CLI templates to custom scripts so that page markup and hooks are automatically generated based on API specifications.
By doing this, you can save 2 hours of component creation time for every page you build.
Build-Time Performance Management
Injecting styles at runtime degrades performance as the number of components increases. StyleX extracts atomic CSS at build time to reduce bundle size. According to data from the Meta development team, after adopting static compilation, style bundle sizes decreased by 80%, and rendering efficiency improved by 30%.
- In vite.config.ts, set runtimeInjection: false in the astryxStylex options to force static CSS extraction.
- Separate @astryxdesign and @stylexjs into distinct chunks in rollupOptions.
- Check the INP metric in the Chrome DevTools Performance panel to find style calculation bottlenecks that take over 50ms.
Switching to a static build allows you to provide a stable UI without runtime overhead, even in large-scale services.