@cdx-ui/native

Native (Metro / Expo) platform integration for Forge UI — the Expo font loader 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.

| Subpath | Exports | Dependency lifecycle | | ---------------------- | ------------------------------------------------- | ----------------------------------------------------------------- | | @cdx-ui/native/fonts | useForgeFonts | Runtime — expo-font, @expo-google-fonts/* | | @cdx-ui/native/metro | withForgeMetroConfig, ForgeMetroConfigOptions | Build-time — metro-config, uniwind/metro (optional peers) |

Build-time dependencies are declared as optional peers, never root dependencies, so importing @cdx-ui/native/fonts for a runtime concern never drags a build tool into the install.

See docs/internal/architecture.md § "Platform Integration Packages" for the full decision record.

Installation

npm install @cdx-ui/native

Peer dependencies, all optional — install only what the subpath you use requires:

| Peer | Required by | | -------------- | ---------------------- | | expo-font | @cdx-ui/native/fonts | | react-native | @cdx-ui/native/fonts | | metro-config | @cdx-ui/native/metro | | uniwind | @cdx-ui/native/metro |

@cdx-ui/native/fonts

useForgeFonts loads all nine display font families with weight and italic variants, plus the web platform fonts (Inter, IBM Plex Mono) when running on web. It wraps Expo's useFonts; the registered font names match the --font-* CSS variable values in @cdx-ui/styles' theme.css, so typography tokens resolve to loaded files on every platform.

import { useForgeFonts } from '@cdx-ui/native/fonts';

export default function RootLayout() {
  const { loaded, error } = useForgeFonts();

  if (!loaded && !error) {
    return null;
  }

  return <Stack />;
}

The hook is a pure loader with no FI config awareness — font selection is handled by the CSS variable layer in @cdx-ui/styles. Call it once in your root layout and gate rendering 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) |