@cdx-ui/web

Vite integration for using Forge UI in React web applications.

Installation

Install @cdx-ui/web at the same version as your other Forge UI packages:

npm install --save-dev @cdx-ui/web vite @tailwindcss/vite tailwindcss uniwind

Configure Vite (forge())

Add forge() before the React plugin and point it at your application's CSS entry file:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { forge } from '@cdx-ui/web/vite';

export default defineConfig({
  plugins: [forge({ cssEntryFile: 'src/index.css' }), react()],
});

forge() configures Tailwind and Uniwind, React Native Web resolution, dependency pre-bundling, and compatibility settings required by Forge UI.

forge() options

| Option | Type | Default | Description | | --------------- | --------- | ------- | ------------------------------------------------------ | | cssEntryFile | string | — | Relative path to the application's CSS entry file. | | patchWorklets | boolean | true | Applies the React Native Worklets compatibility patch. |

Testing with Vitest (forgeVitest())

Do not put forge() in vitest.config.ts. Uniwind's Vite adapter aliases react-native in a way that Vitest resolves to the Flow-syntax native package. Use forgeVitest() instead:

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import { forgeVitest } from '@cdx-ui/web/vite';

export default defineConfig({
  plugins: [react(), forgeVitest()],
  test: {
    setupFiles: ['./src/__tests__/setup.ts'],
  },
});

// src/__tests__/setup.ts
import '@testing-library/jest-dom/vitest';
import { afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';

afterEach(() => {
  cleanup();
});

Wrap Forge UI under test in ForgeDesignProvider (Dialog and other overlays need its portal host):

import type { ReactElement } from 'react';
import { render } from '@testing-library/react';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { ForgeDesignProvider } from '@cdx-ui/components';

export function renderWithForgeProviders(ui: ReactElement) {
  return render(ui, {
    wrapper: ({ children }) => (
      <SafeAreaProvider>
        <ForgeDesignProvider config={{ toast: false }}>{children}</ForgeDesignProvider>
      </SafeAreaProvider>
    ),
  });
}

forgeVitest() owns:

• react-native → react-native-web (not Uniwind's Vite alias)
• @react-native-aria/* → ESM lib/module entries
• @cdx-ui/* inlining so Bob ESM directory imports resolve
• jsdom stand-ins for Uniwind, Reanimated, Gesture Handler, Worklets, Safe Area, SVG, Screens, Bottom Sheet, FlashList, Flash Calendar, and Reanimated Carousel

Those stand-ins are import-time boundaries. Tests exercise the real @cdx-ui/components API; they do not validate production CSS, animation timing, or native gestures. See @cdx-ui/web/testing for the mock package list.

A maintained consumer harness lives in examples/forge-ui-mui-vite.

forgeVitest() options

| Option | Type | Default | Description | | ------------------ | ---------- | ------- | ------------------------------------------------- | | optimizerInclude | string[] | [] | Extra Vitest dependency-optimizer include entries |