External Package Theming Support: createTheme with External Tokens

[besSejrani]

External Package Theming Support: createTheme with External Tokens

Problem Summary

I'm building a component library with StyleX and facing limitations when implementing theming across package boundaries. The issue occurs when trying to use createTheme() with tokens imported from an external package.

Current Setup

• Component Library: ioloco-ui package with ~15 components
• Build Tool: Rollup for package bundling
• Tokens: Defined using defineVars() inside the library
• Theme System: Custom wrapper provider for theme switching
• Status: ✅ Components work, ❌ External theming fails

Environment

• StyleX: v0.14.x
• Build Tools: Tried both official PostCSS plugin and community SWC plugin
• Framework: Next.js 15
• Package Manager: npm/pnpm

Additional Context

The defineConsts API works great for shared constants, but theming specifically requires createTheme() which seems to have stricter static analysis requirements for external imports.

What Works vs. What Doesn't

Scenario	Status	Notes
Direct relative import (monorepo)	✅ Works	import { tokens } from '../../../lib/src/tokens.stylex'
Package import	❌ Fails	import { tokens } from 'ioloco-ui'
Local token definitions	✅ Works	Tokens defined in same project

Error Details

Error: Panic occurred during transformation: Only static values are allowed inside of a createTheme() call..

Code that fails:

// app/theme/ui-themes.js
import { uiTokens } from 'ioloco-ui'; // ❌ External package import
const theme = stylex.createTheme(uiTokens, {
  textPrimary: '#000000',
  // ... other overrides
});

Code that works:

// Direct import in monorepo
import { uiTokens } from '../../../packages/ui/src/tokens.stylex'; // ✅ Works
const theme = stylex.createTheme(uiTokens, {
  textPrimary: '#000000',
});

Architecture Overview

Looking for Community Input

I'm currently blocked by this limitation and would greatly appreciate guidance from the community. If you've encountered similar challenges with component library theming, I'd love to hear about your solutions.

Specifically seeking:

• Proven workarounds for external package theming with StyleX
• Architecture patterns that work well for themeable component libraries
• Roadmap insights - are there plans to improve cross-package token resolution?
• Alternative approaches you've successfully implemented

I will appreciate your help, thank you! 🙏

[necolas]

Have you tried exporting only the tokens from a separate file to meet the StyleX requirements?

import { uiTokens } from 'ioloco-ui/tokens.stylex';

[besSejrani]

Hi @necolas — thanks again! You were absolutely right: the issue was that the .stylex suffix was missing from the filename when importing from the package. After correcting that, the theming works correctly in development.

However, I’ve run into a new issue: as soon as I set the dev option to false or build the app with Next.js (next build), the theming stops working in production. Do you have any idea why ?

To help reproduce the issue, I’ve isolated the setup into a minimal monorepo example: 🔗 Monorepo

[nmn]

@besSejrani From what I see you're using the third-party swc plugin for nextjs. We only officially support the postcss plugin for nextjs. Please ask the creator of that repo for help as to why it might not be working as expected.

[besSejrani]

@nmn I solved this by using css variables in theming, beginning with --, like stated in the doc change of last week.

Thank you guys.