seif-ui

v0.1.3

Published

a month ago

A modern React component library built with Next.js, TypeScript, and Tailwind CSS

0High
0Medium
0Low

pmgpathum

ishara_ind

react nextjs component-library ui-components tailwindcss typescript

SEIF UI Component Library

A modern React component library built with Next.js, TypeScript, and Tailwind CSS. This library provides a comprehensive set of UI components for building beautiful and accessible web applications.

Installation

Install the package using npm:

npm install seif-ui

Or using yarn:

yarn add seif-ui

Or using pnpm:

pnpm add seif-ui

Peer Dependencies

This library requires the following peer dependencies to be installed in your project:

@subframe/core >= 1.147.0
react >= 18.0.0
react-dom >= 18.0.0
next >= 13.0.0

Install all peer dependencies:

npm install @subframe/core react react-dom next

Setup

1. Install Tailwind CSS v4

This library requires Tailwind CSS v4 with PostCSS. Install the necessary packages:

npm install -D tailwindcss@^4.1.17 @tailwindcss/postcss@^4.1.17 postcss autoprefixer

2. Configure PostCSS

Create or update your postcss.config.mjs file:

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
};

export default config;

3. Configure Next.js (REQUIRED)

Important: Add the @subframe/core package to the transpilePackages array in your next.config.mjs file. This is required for Next.js to properly process the CSS modules from the package:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@subframe/core'],
};

export default nextConfig;

Without this configuration, the components will not render correctly and may display incorrectly styled text instead of proper UI elements.

4. Import CSS Theme (IMPORTANT: Order Matters!)

The theme CSS must be imported BEFORE Tailwind directives. Import the theme CSS file in your application's root layout or global CSS file:

Option A: In your app/layout.tsx:

import "./globals.css";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

And in your globals.css:

/* Tell Tailwind CSS v4 to scan seif-ui component files */
@source "node_modules/seif-ui/src/ui/**/*.{tsx,ts,jsx,js}";
@source "node_modules/seif-ui/dist/**/*.{js,mjs}";

/* Import seif-ui theme FIRST */
@import "seif-ui/theme.css";

/* Import Tailwind CSS */
@import "tailwindcss";

Option B: In your globals.css (RECOMMENDED):

/* Tell Tailwind CSS v4 to scan seif-ui component files */
@source "node_modules/seif-ui/src/ui/**/*.{tsx,ts,jsx,js}";
@source "node_modules/seif-ui/dist/**/*.{js,mjs}";

/* Import seif-ui theme FIRST - must come before Tailwind directives */
@import "seif-ui/theme.css";

/* Then import Tailwind CSS */
@import "tailwindcss";

/* Your custom styles */
:root {
  --background: #ffffff;
  --foreground: #171717;
}

⚠️ Critical: The import order is:

seif-ui/theme.css (first)
tailwindcss (second)
Your custom styles (last)

5. Configure Tailwind CSS v4

With Tailwind CSS v4, configuration is done via CSS using @source directives. You must add @source directives in your globals.css file to tell Tailwind to scan the seif-ui component files:

/* Add these @source directives BEFORE importing seif-ui/theme.css */
@source "node_modules/seif-ui/src/ui/**/*.{tsx,ts,jsx,js}";
@source "node_modules/seif-ui/dist/**/*.{js,mjs}";

Note: Tailwind CSS v4 uses CSS-based configuration, so you don't need a tailwind.config.ts file. The @source directives in your CSS file tell Tailwind where to scan for class names.

6. Use Components

Import and use components in your Next.js app:

import { Button, TextField, Dialog } from "seif-ui";

export default function MyPage() {
  return (
    <div>
      <Button variant="brand-primary">Click me</Button>
      <TextField placeholder="Enter text..." />
      <Dialog>Dialog content</Dialog>
    </div>
  );
}

Complete Setup Example

Here's a complete example of setting up seif-ui in a Next.js project:

1. Install dependencies:

npm install seif-ui @subframe/core react react-dom next
npm install -D tailwindcss@^4.1.17 @tailwindcss/postcss@^4.1.17 postcss autoprefixer

2. Create postcss.config.mjs:

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
};

export default config;

3. Update app/globals.css:

/* Tell Tailwind CSS v4 to scan seif-ui component files */
@source "node_modules/seif-ui/src/ui/**/*.{tsx,ts,jsx,js}";
@source "node_modules/seif-ui/dist/**/*.{js,mjs}";

/* Import seif-ui theme FIRST */
@import "seif-ui/theme.css";

/* Import Tailwind CSS */
@import "tailwindcss";

/* Your custom styles */
:root {
  --background: #ffffff;
  --foreground: #171717;
}

4. Use components:

import { Button } from "seif-ui";

export default function Page() {
  return <Button variant="brand-primary">Hello</Button>;
}

Troubleshooting

Styles not working?

Check @source directives: You MUST add @source directives in your globals.css to scan seif-ui files:

@source "node_modules/seif-ui/src/ui/**/*.{tsx,ts,jsx,js}";
@source "node_modules/seif-ui/dist/**/*.{js,mjs}";

Check CSS import order: seif-ui/theme.css must be imported BEFORE tailwindcss
Verify PostCSS config: Ensure @tailwindcss/postcss is configured correctly
Check Tailwind version: Must be Tailwind CSS v4 (^4.1.17)
Verify peer dependencies: All peer dependencies must be installed
Restart dev server: After adding @source directives, restart your Next.js dev server

Common Issues

Issue: Components render but styles are missing

Solution:
1. Add @source directives in your globals.css to scan seif-ui files
2. Ensure seif-ui/theme.css is imported before Tailwind directives
3. Restart your dev server after making changes

Issue: PostCSS errors

Solution: Verify @tailwindcss/postcss is installed and configured in postcss.config.mjs

Issue: CSS variables not found

Solution: Check that seif-ui/theme.css is imported and Tailwind CSS v4 is installed

Available Components

The library includes the following components:

Buttons: Button, IconButton, LinkButton
Forms: TextField, TextArea, Select, Checkbox, CheckboxGroup, CheckboxCard, RadioGroup, RadioCardGroup, Switch, ToggleGroup, Slider
Feedback: Alert, Toast, Loader, Progress
Navigation: Breadcrumbs, Tabs, Stepper, VerticalStepper
Overlays: Dialog, FullscreenDialog, Drawer, Tooltip, DropdownMenu, ContextMenu
Data Display: Table, Calendar, TreeView, CustomTreeView, Accordion
Charts: AreaChart, BarChart, LineChart, PieChart
Layout: DefaultPageLayout, DialogLayout, DrawerLayout, SidebarWithSections
Other: Avatar, Badge, SkeletonText, SkeletonCircle, CopyToClipboardButton, IconWithBackground

Development

Building the Library

To build the library for distribution:

npm run build:lib

This will create a dist/ directory with the compiled JavaScript, TypeScript definitions, and CSS files.

Development Server

To run the development server for testing components:

npm run dev

Storybook

To view components in Storybook:

npm run storybook

Requirements

Next.js 13+ (App Router)
React 18+
Tailwind CSS v4 (^4.1.17)
TypeScript (recommended)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.