consensys-ui/packages/config/README.md

Consensys UI component library and design system

# @consensys/ui-config

> 🚧 **Note**: This package is under active development. While we're working hard to make it production-ready, please be aware that APIs and features may change. We welcome your feedback and contributions as we continue to improve!

🔧 **Unified configuration layer for the CUI ecosystem**

Build consistent, type-safe applications across web and React Native with a single configuration layer that handles framework integration, theming, and build tooling.

```tsx
// One configuration. Any platform. Native everywhere.
import { vitePlugin } from '@consensys/ui-config/vite';
import { nativewindPreset } from '@consensys/ui-config/nativewind';
```

## ✨ Standout Features

🔄 **Framework Integration** - Seamless setup for Vite, Expo, and React Native with optimized defaults

🎨 **Theme Integration** - Unified theming system that works across all platforms

🔧 **Build Tooling** - Comprehensive build configurations for web and native development

📱 **Cross-Platform** - Consistent configuration patterns for web and React Native

🛠️ **Type Safety** - Full TypeScript support with comprehensive type definitions

🏗️ **Workspace Support** - Optimized for monorepo setups with proper module resolution

## 🚀 Get Started

```bash
pnpm add @consensys/ui-config
```

### Theme Configuration & Runtime Access

The configuration system follows a three-step process to make your theme available throughout your application:

1. **Configuration**: Define your theme settings in `theme.config.ts`
2. **Processing**: The configuration is processed and transformed into a runtime theme object
3. **Injection**: The theme object is injected into your application's global scope

Each platform has its own way of accessing global variables:
- **Web (Vite)**: See [Vite Plugin](#vite-plugin) section for details
- **React Native (Expo)**: See [Expo Configuration](#expo-configuration) section for details

### Theme Configuration

For detailed theme configuration options, see the [@consensys/ui-theme documentation](../theme/README.md).

```typescript
// theme.config.ts
import { UserConfig } from '@consensys/ui-theme'

export default {
  themes: {
    default: {
      colors: {
        neutral: 'gray',
        primary: 'blue',
        secondary: 'violet',
        error: 'red',
        warning: 'amber',
        success: 'green',
      },
    },
  },
} satisfies UserConfig;
```

## 📚 Configuration Options

### Vite Plugin

The Vite plugin provides optimized defaults for web development:

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import cui from '@consensys/ui-config/vite';
import themeConfig from "./theme.config";

export default defineConfig(({ command }) => ({
  plugins: [
    cui(command, themeConfig),
  ],
}));
```

The plugin automatically:
- Configures React and React Native Web
- Sets up NativeWind babel preset
- Injects theme configuration into `import.meta.env.CUI`
- Optimizes dependencies for [@consensys/ui](../ui/README.md) components

You can access the theme configuration in your application using:
```typescript
const theme = import.meta.env.CUI;
```

See [vite.plugin.ts](src/vite.plugin.ts) for implementation details.
See [vite.config.ts](../../apps/vite-example/vite.config.ts) for usage example.

### NativeWind Preset

The NativeWind preset combines Tailwind and React Native styling:

```javascript
// tailwind.config.js
import nativewindPreset from "@consensys/ui-config/nativewind";
import themeConfig from "./theme.config";

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    './node_modules/@consensys/ui/**/*.{js,jsx,ts,tsx}',
  ],
  presets: [nativewindPreset(themeConfig)]
}
```

See [nativewind.preset.ts](src/nativewind.preset.ts) for implementation details.
See [tailwind.config.js](../../apps/vite-example/tailwind.config.js) for usage example.

### Expo Configuration

Expo-specific configurations for React Native development:

```javascript
// app.config.js
import withCui from '@consensys/ui-config/expo';
import themeConfig from './theme.config';

module.exports = ({ config }) => {
  return withCui({ config, themeConfig });
};
```

The Expo configuration:
- Processes and validates your theme configuration
- Injects the theme into `global.CUI` for runtime access
- Ensures consistent theming across your React Native application

You can access the theme configuration in your application using:
```typescript
const theme = global.CUI;
```

See [expo.preset.ts](src/expo.preset.ts) for implementation details.
See [app.config.js](../../apps/expo-example/app.config.js) for usage example.

### Babel Configuration

```javascript
// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['@consensys/ui-config/expo/babel'],
  };
};
```

The babel preset automatically configures:
- babel-preset-expo with NativeWind support
- NativeWind babel plugin
- Proper JSX handling for React Native

See [babel.preset.ts](src/babel.preset.ts) for implementation details.
See [babel.config.js](../../apps/expo-example/babel.config.js) for usage example.

### Metro Configuration

Metro bundler configuration for React Native:

```javascript
// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withCuiWorkspace } = require('@consensys/ui-config/metro');

const config = getDefaultConfig(__dirname);
module.exports = withCuiWorkspace(config);
```

The Metro configuration:
- Sets up NativeWind processing
- Configures proper module resolution
- Handles monorepo workspace dependencies
- Optimizes build performance

See [metro.config.ts](src/metro.config.ts) for implementation details.
See [metro.config.js](../../apps/expo-example/metro.config.js) for usage example.

For complete examples, see:
- [Vite Example](../../apps/vite-example) - Web implementation
- [Expo Example](../../apps/expo-example) - React Native implementation

## 🏛️ Architecture

@consensys/ui-config provides a unified configuration layer that ties together the entire CUI ecosystem:

1. **Single Source of Truth**
   - One `theme.config.ts` file configures everything
   - Type-safe configuration with `UserConfig` type
   - Consistent theming across all platforms

2. **Framework Integration**
   - Vite for web development
   - Expo for React Native
   - NativeWind for styling
   - Metro for bundling

3. **Workspace Optimization**
   - Monorepo-aware module resolution
   - Shared dependency management
   - Consistent build configuration
   - Development server optimization

## 🛠️ Development

```bash
# Install dependencies
pnpm i

# Watch and build
pnpm dev

# Production build
pnpm build
```

## 🤝 Contributing

We welcome contributions!

## 📜 License

MIT