@cdx-ui/native

Native (Metro / Expo) platform integration for Forge UI — the Expo config plugin that embeds Forge fonts and the Metro config wrapper. Keeps @cdx-ui/styles and @cdx-ui/components platform-neutral so web hosts never pull Expo or font binaries by accident.

No root export — subpaths only

This package ships no . entry. A bare import '@cdx-ui/native' fails at resolution by design: each subpath owns its own dependency lifecycle, and a root barrel would re-aggregate them into exactly the chokepoint this package exists to remove.

| Entry | Exports | Dependency lifecycle | | -------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ | | @cdx-ui/native (config plugin) | Expo config plugin, via app.plugin.js | Build-time — expo/config-plugins (optional peer), font files | | @cdx-ui/native/metro | withForgeMetroConfig, ForgeMetroConfigOptions | Build-time — metro-config, uniwind/metro (optional peers) | | @cdx-ui/native/fonts | useForgeFonts (deprecated) | Runtime — none |

Build-time dependencies are declared as optional peers, never root dependencies, so nothing in this package drags a build tool into a runtime install.

The repository's architecture documentation records the full decision under "Platform Integration Packages".

Installation

npm install @cdx-ui/native

Peer dependencies — install what the subpath you use requires. Platform peers below are optional; react is required (^18.2.0 || ^19.0.0).

| Peer | Version | Required by | Optional | | -------------- | ---------------------- | ------------------------------- | -------- | | react | ^18.2.0 \|\| ^19.0.0 | @cdx-ui/native/fonts | no | | expo | >=52.0.0 | the config plugin | yes | | react-native | >=0.76.0 | the config plugin's native code | yes | | metro-config | >=0.80.0 | @cdx-ui/native/metro | yes | | uniwind | >=1.0.0 | @cdx-ui/native/metro | yes |

Fonts — the config plugin

Add the plugin to your Expo config and rebuild the native app (npx expo prebuild, or any expo run:* / EAS build):

{
  "expo": {
    "plugins": ["@cdx-ui/native"]
  }
}

It embeds every font family the Forge tokens can name — every selectable Display family, and the Android mono family — and registers each one as one family carrying all of its faces, which is what lets font-medium, font-semibold, font-bold and italic select a real face:

• iOS — the face files are bundled and listed in UIAppFonts. iOS groups them by the family name inside each file, so React Native picks the face from fontFamily, fontWeight and fontStyle.
• Android — each family becomes an XML font family registered with React Native's font manager, the only path on which React Native applies numeric weights and italic to a custom font. The system Roboto family is registered the same way, so font-medium and font-semibold reach real system weights instead of collapsing onto regular.

The body and mono families on iOS are the system fonts, which need no embedding. Fonts are selected by the CSS variable layer in @cdx-ui/styles, including a ThemeOverride that switches the Display family at runtime — the plugin has no FI config awareness.

The plugin needs a development build; Expo Go cannot load config plugins. It writes its Android registration in its own MainApplication block, so it coexists with an expo-font plugin entry configured for an app's own fonts.

Web is unaffected. Browser apps register fonts with @cdx-ui/styles/fonts and should not install this package.

Migrating from useForgeFonts

useForgeFonts loaded fonts at runtime through expo-font, which registers each face as a separate family — a shape that cannot carry weight or italic on Android. It is now deprecated and always reports { loaded: true, error: null }. Add the plugin, rebuild, and remove the hook and any rendering gate on loaded.

@cdx-ui/native/metro

withForgeMetroConfig wraps a Metro config with Forge UI's styling-layer configuration. It must be the outermost wrapper if you compose multiple Metro config wrappers.

const { getDefaultConfig } = require('expo/metro-config');
const { withForgeMetroConfig } = require('@cdx-ui/native/metro');

const config = getDefaultConfig(__dirname);

module.exports = withForgeMetroConfig(config, {
  cssEntryFile: './global.css',
  generatedTypesFile: './uniwind-types.d.ts',
});

| Option | Type | Purpose | | -------------------- | -------- | ------------------------------------------------------------ | | cssEntryFile | string | Path to the CSS entry file (e.g. './global.css'). | | generatedTypesFile | string | Optional path for generated Tailwind class type definitions. |

Today this delegates to Uniwind. If the styling layer is swapped, only the internals of this function change — consuming Metro configs stay the same.

Web hosts

Expo web bundles through Metro, so an Expo-web build imports @cdx-ui/native/metro. That is an accepted consequence of the platform axis. Non-Expo web hosts (Vite, Next.js) need neither subpath: they must load fonts through their own web font path (@font-face rules or a web font provider) and configure Tailwind directly.

Related packages

| Package | Owns | | -------------------- | ------------------------------------------------------------------ | | @cdx-ui/styles | Design tokens, CSS artifacts, theming utilities (platform-neutral) | | @cdx-ui/components | Styled cross-platform components (platform-neutral) |