Hazo Config Component Library

A React component library for managing configuration with Storybook for component testing and documentation.

Tech Stack

• React - UI library
• TypeScript - Type safety
• TailwindCSS - Styling
• Shadcn/UI - Component primitives
• Storybook - Component development and testing
• Vite - Build tool

Usage

Installation

npm install hazo_config

Tailwind CSS Setup (Required)

This package uses Tailwind CSS utility classes for styling. You must configure Tailwind in your project.

Tailwind v3 Setup

If using Tailwind v3, no additional setup is required beyond having Tailwind installed.

Tailwind v4 Setup (Critical)

Tailwind v4 uses JIT compilation and only generates CSS for classes found in scanned files. By default, it only scans your project's files, NOT files in node_modules/. This causes all Tailwind classes in this package to have NO CSS generated.

Add the following to your globals.css or main CSS file AFTER the tailwindcss import:

@import "tailwindcss";

/* Required: Enable Tailwind to scan hazo_config package classes */
@source "../node_modules/hazo_config/dist";

Without this directive, the components will have:

• Missing hover states (transparent/invisible)
• Missing colors, spacing, and typography
• Broken layouts

Import Paths (Server/Client Separation)

This package provides separate entry points for server and client code to prevent Next.js bundling errors:

// Client code (React components, browser)
import { ConfigViewer, ConfigEditor, MockConfigProvider } from 'hazo_config'

// Server code (API routes, Next.js server components)
import { HazoConfig } from 'hazo_config/server'

Why? The HazoConfig class uses Node.js fs and path modules. Importing it in client code causes "Module not found: Can't resolve 'fs'" errors. The /server entry point uses the server-only package to prevent accidental client imports.

Example: Server-side Config Loading

// app/api/config/route.ts (Next.js API route)
import { HazoConfig } from 'hazo_config/server'

const config = new HazoConfig({ filePath: './config.ini' })
const dbHost = config.get('database', 'host')

Example: Client-side Config Display

// components/settings.tsx (React component)
import { ConfigViewer, MockConfigProvider } from 'hazo_config'

// Use MockConfigProvider for client-side demos/testing
const mockConfig = new MockConfigProvider({
  database: { host: 'localhost', port: '5432' }
})

export function Settings() {
  return <ConfigViewer config_provider={mockConfig} />
}

Development

Local Setup

Install dependencies:

npm install

Storybook

Run Storybook to develop and test components:

npm run storybook

This will start Storybook on http://localhost:6006

Building

Build the library:

npm run build

Build Storybook for static deployment:

npm run build-storybook

Project Structure

hazo_config/
├── src/
│   ├── components/          # React components (client-safe)
│   │   ├── config_viewer.tsx
│   │   ├── config_editor.tsx
│   │   └── *.stories.tsx
│   ├── lib/                 # Core config management
│   │   ├── config_loader.ts # HazoConfig class (Node.js)
│   │   ├── mock_config_provider.ts # Client-safe mock
│   │   └── types.ts
│   ├── server/              # Server-only entry point
│   │   └── index.ts
│   ├── styles/              # Global styles
│   │   └── globals.css
│   └── index.ts             # Main entry point (client-safe)
├── .storybook/              # Storybook configuration
├── tailwind.config.js       # TailwindCSS configuration
└── tsconfig.json            # TypeScript configuration

Adding Components

1. Create your component in src/components/
2. Create a corresponding .stories.tsx file for Storybook
3. Export the component from src/components/index.ts
4. Export from src/index.ts to make it available in the library

Adding Shadcn/UI Components

Use the Shadcn CLI to add components:

npx shadcn@latest add [component-name]

Code Style

• Use snake_case for file names and variables
• Include file purpose description at the top of each file
• Add comments for functions and major code sections
• Use cls_ prefix for div class names (e.g., cls_example_component)

License

MIT