Installation

Get started with FlexiUI by installing it in your React project. This guide covers automatic setup, manual configuration, and troubleshooting.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18.x or higher
React 18 or React 19
Tailwind CSS 4.x

Check Your Environment

Verify your setup with these commands:

node --version  # Should be 18.x or higher
npm --version   # Should be 8.x or higher

Quick Installation

The fastest way to get started is by installing the core packages:

npm

npm install @flexi-ui/theme @flexi-ui/system

pnpm

pnpm add @flexi-ui/theme @flexi-ui/system

yarn

yarn add @flexi-ui/theme @flexi-ui/system

bun

bun add @flexi-ui/theme @flexi-ui/system

Framework-Specific Setup

Next.js (App Router)

For Next.js 13+ with App Router:

Install dependencies:

npm install @flexi-ui/theme @flexi-ui/system

Configure Tailwind CSS (tailwind.config.ts):

import type { Config } from 'tailwindcss'
import { flexiui } from '@flexi-ui/theme'
 
const config: Config = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [flexiui()],
}
 
export default config

Add Provider (app/providers.tsx):

'use client'
 
import { FlexiUIProvider } from '@flexi-ui/system'
 
export function Providers({ children }: { children: React.ReactNode }) {
  return <FlexiUIProvider>{children}</FlexiUIProvider>
}

Wrap your app (app/layout.tsx):

import { Providers } from './providers'
import './globals.css'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

Next.js (Pages Router)

For Next.js with Pages Router:

Install dependencies (same as above)
Configure Tailwind CSS (same as above)
Add Provider (pages/_app.tsx):

import type { AppProps } from 'next/app'
import { FlexiUIProvider } from '@flexi-ui/system'
import '@/styles/globals.css'
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <FlexiUIProvider>
      <Component {...pageProps} />
    </FlexiUIProvider>
  )
}

Vite + React

For Vite projects:

Install dependencies:

npm install @flexi-ui/theme @flexi-ui/system

Configure Tailwind CSS (tailwind.config.js):

import { flexiui } from '@flexi-ui/theme'
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [flexiui()],
}

Add Provider (src/main.tsx):

import React from 'react'
import ReactDOM from 'react-dom/client'
import { FlexiUIProvider } from '@flexi-ui/system'
import App from './App'
import './index.css'
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <FlexiUIProvider>
      <App />
    </FlexiUIProvider>
  </React.StrictMode>,
)

Remix

For Remix projects:

Install dependencies (same as above)
Configure Tailwind CSS (tailwind.config.js):

import { flexiui } from '@flexi-ui/theme'
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [flexiui()],
}

Add Provider (app/root.tsx):

import { FlexiUIProvider } from '@flexi-ui/system'
import styles from './tailwind.css?url'
 
export const links: LinksFunction = () => [{ rel: 'stylesheet', href: styles }]
 
export default function App() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <FlexiUIProvider>
          <Outlet />
        </FlexiUIProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  )
}

Manual Setup

If you prefer to set up FlexiUI manually or need more control:

Step 1: Install Tailwind CSS

If you haven't already installed Tailwind CSS:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Step 2: Install FlexiUI Packages

npm install @flexi-ui/theme @flexi-ui/system

Step 3: Configure Tailwind CSS

Update your tailwind.config.js:

import { flexiui } from '@flexi-ui/theme'
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [flexiui()],
}

Important: Make sure to include the FlexiUI theme path in your content array so Tailwind can detect and generate the necessary styles.

Step 4: Import CSS

Add Tailwind directives to your CSS file (e.g., globals.css):

@import 'tailwindcss';

Or if using Tailwind CSS v3 syntax:

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 5: Add Provider

Wrap your app with FlexiUIProvider:

import { FlexiUIProvider } from '@flexi-ui/system'
 
function App() {
  return (
    <FlexiUIProvider>
      {/* Your app content */}
    </FlexiUIProvider>
  )
}

Installing Individual Components

FlexiUI uses a modular architecture. Install only the components you need:

# Install specific components
npm install @flexi-ui/button @flexi-ui/input @flexi-ui/spinner

Then import and use them:

import { Button } from '@flexi-ui/button'
import { Input } from '@flexi-ui/input'
import { Spinner } from '@flexi-ui/spinner'
 
function MyComponent() {
  return (
    <div>
      <Button color="primary">Click me</Button>
      <Input label="Email" />
      <Spinner />
    </div>
  )
}

TypeScript Configuration

FlexiUI is built with TypeScript. For the best experience, ensure your tsconfig.json is properly configured:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

CSS Variables

FlexiUI uses CSS variables for theming. These are automatically injected when you use the FlexiUI plugin. You can customize them in your theme configuration.

Verify Installation

Test that FlexiUI is working correctly:

import { Button } from '@flexi-ui/button'
 
export default function TestPage() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">FlexiUI Test</h1>
      <Button color="primary" onPress={() => alert('FlexiUI is working!')}>
        Click Me
      </Button>
    </div>
  )
}

If the button renders with proper styling, you're all set!

Troubleshooting

Styles Not Applying

Problem: Components render but have no styles.

Solutions:

Check Tailwind content path:

// Make sure this path is included
content: [
  './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
]

Verify CSS import:

Make sure you're importing your CSS file in your app:

import './globals.css' // or your CSS file

Check Tailwind directives:

Ensure your CSS file has Tailwind directives:

@import 'tailwindcss';

Clear build cache:

# For Next.js
rm -rf .next
 
# For Vite
rm -rf dist node_modules/.vite

Module Not Found Errors

Problem: Cannot find module '@flexi-ui/theme' or similar errors.

Solutions:

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Check package installation:

npm list @flexi-ui/theme @flexi-ui/system

Verify imports:

Make sure you're importing from the correct package:

// Correct
import { flexiui } from '@flexi-ui/theme'
import { FlexiUIProvider } from '@flexi-ui/system'
 
// Incorrect
import { flexiui } from '@flexi-ui/react'  // This package doesn't exist

TypeScript Errors

Problem: Type errors or missing type definitions.

Solutions:

Update TypeScript:

npm install -D typescript@latest

Check tsconfig.json:

Ensure moduleResolution is set to "bundler" or "node":

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Restart TypeScript server:

In VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

Provider Issues

Problem: Components don't work or context is undefined.

Solution:

Make sure FlexiUIProvider wraps your entire app:

// Correct - Provider at the root
function App() {
  return (
    <FlexiUIProvider>
      <YourApp />
    </FlexiUIProvider>
  )
}
 
// Incorrect - Provider inside component
function SomeComponent() {
  return (
    <FlexiUIProvider>
      <Button>Click</Button>
    </FlexiUIProvider>
  )
}

Build Errors

Problem: Build fails with PostCSS or Tailwind errors.

Solutions:

Update dependencies:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Check PostCSS config:

Ensure you have a postcss.config.js:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Clear build cache and rebuild:

rm -rf .next dist node_modules/.vite
npm run build

SSR Issues (Next.js/Remix)

Problem: Hydration errors or styles not working on server-side.

Solutions:

Use client directive for interactive components:

'use client'
 
import { Button } from '@flexi-ui/button'

Ensure Provider is properly placed:

For Next.js App Router, create a separate providers.tsx file marked with 'use client'.

Check CSS imports:

Make sure global CSS is imported in the root layout, not in client components.

Use tree-shaking by importing individual components
Avoid importing from @flexi-ui/react (if it exists), use specific packages
Consider code-splitting for large applications

Getting Help

If you're still experiencing issues:

Check the documentation - Most common issues are covered in our guides
Search GitHub Issues - Someone may have encountered the same problem
Ask for help - Open a GitHub Discussion
Report bugs - Create an issue if you found a bug

Next Steps

Now that FlexiUI is installed, explore:

Components - Browse all available components
Theme Customization - Customize colors, spacing, and more
Dark Mode - Add dark mode support
Framework Guides - Framework-specific tips and examples

Installation

Prerequisites

Check Your Environment

Quick Installation

npm

pnpm

yarn

bun

Framework-Specific Setup

Next.js (App Router)

Next.js (Pages Router)

Vite + React

Remix

Manual Setup

Step 1: Install Tailwind CSS

Step 2: Install FlexiUI Packages

Step 3: Configure Tailwind CSS

Step 4: Import CSS

Step 5: Add Provider

Installing Individual Components

TypeScript Configuration

CSS Variables

Verify Installation

Troubleshooting

Styles Not Applying

Module Not Found Errors

TypeScript Errors

Provider Issues

Build Errors

SSR Issues (Next.js/Remix)

Common Issues

Dark Mode Not Working

Custom Theme Not Applied

Performance Issues

Getting Help

Next Steps