Hazo Config Component Library

A React component library for managing configuration with database-backed storage, supporting both INI files and app configuration. Includes React UI components with JSON editing capabilities.

Tech Stack

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

Quick Start

1. Install the package:
``bash
npm install hazo_config
`

2. Add CSS custom properties to your globals.css:
`css
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
--muted: 210 40% 96.1%;
--muted-foreground: 215.4 16.3% 46.9%;
--accent: 210 40% 96.1%;
--accent-foreground: 222.2 47.4% 11.2%;
--border: 214.3 31.8% 91.4%;
--input: 214.3 31.8% 91.4%;
}
}
`

3. If using Tailwind v4, add the @source directive to globals.css:
`css
@import "tailwindcss";

@source "../node_modules/hazo_config/dist";
`

4. Import and use components:
`typescript
// Client components
import { AppConfig, ConfigViewer, MockConfigProvider } from 'hazo_config'

// Server-side (API routes, server components)
import { HazoConfig } from 'hazo_config/server'
`

See detailed setup instructions below.

Usage

$3

`bash
npm install hazo_config
`

$3

This package uses Tailwind CSS utility classes for styling. You must configure both Tailwind and CSS custom properties.

#### CSS Custom Properties (Required for All Versions)

Add these CSS custom properties to your globals.css or main CSS file. These are used for theming and dark mode support:

`css
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
--muted: 210 40% 96.1%;
--muted-foreground: 215.4 16.3% 46.9%;
--accent: 210 40% 96.1%;
--accent-foreground: 222.2 47.4% 11.2%;
--border: 214.3 31.8% 91.4%;
--input: 214.3 31.8% 91.4%;
--card: 0 0% 100%;
--card-foreground: 222.2 84% 4.9%;
}

.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--primary: 210 40% 98%;
--primary-foreground: 222.2 47.4% 11.2%;
--muted: 217.2 32.6% 17.5%;
--muted-foreground: 215 20.2% 65.1%;
--accent: 217.2 32.6% 17.5%;
--accent-foreground: 210 40% 98%;
--border: 217.2 32.6% 17.5%;
--input: 217.2 32.6% 17.5%;
--card: 222.2 84% 4.9%;
--card-foreground: 210 40% 98%;
}
}
`

#### Tailwind v3 Setup

If using Tailwind v3, ensure your tailwind.config.js includes:

`js
module.exports = {
content: [
'./app/*/.{js,ts,jsx,tsx}',
'./components/*/.{js,ts,jsx,tsx}',
],
// ... rest of config
}
`

#### 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:

`css
@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

$3

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

`typescript
// Client code (React components, browser)
import { ConfigViewer, ConfigEditor, AppConfig, MockConfigProvider } from 'hazo_config'
import type { AppConfigItem, AppConfigContext, ConfigType } 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.

$3

v2.0.0 introduces breaking changes with database-backed configuration support:

- New Component: AppConfig for database-backed configuration with JSON value support
- Schema Change: Replaces org_id with scope_id for flexible scoping
- JSON Support: Store structured configuration as JSON with in-UI editing
- Type System: New ConfigType ('general' | 'json') for value type management

See MIGRATION_V2.md for detailed migration guide from v1.x.

$3

`typescript
// 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')
`

$3

`typescript
// 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
}
`

$3

`typescript
// app/settings/page.tsx (Next.js server component)
'use client'

import { AppConfig } from 'hazo_config'
import type { AppConfigContext, AppConfigItem, ConfigType } from 'hazo_config'
import { fetch_config, save_config, delete_config } from '@/lib/config_actions'

export default function SettingsPage() {
const context: AppConfigContext = {
scope_id: 'your-scope-id',
user_id: 'optional-user-id'
}

return (
title="Application Settings"
context={context}
fetch_config={fetch_config}
save_config={save_config}
delete_config={delete_config}
/>
)
}
`

The AppConfig component supports:
- JSON and text configuration values
- In-line editing with validation
- Sensitive field masking (passwords, tokens, keys)
- Section-based organization
- Type conversion between general and JSON

Development

$3

Install dependencies:

`bash
npm install
`

$3

Run Storybook to develop and test components:

`bash
npm run storybook
`

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

$3

Build the library:

`bash
npm run build
`

Build Storybook for static deployment:

`bash
npm run build-storybook
`

Project Structure

`
hazo_config/
├── src/
│ ├── components/ # React components (client-safe)
│ │ ├── config_viewer.tsx # INI config viewer
│ │ ├── config_editor.tsx # INI config editor
│ │ ├── app_config.tsx # Database-backed config (v2.0+)
│ │ ├── use_app_config.ts # Hook for app config
│ │ └── *.stories.tsx
│ ├── lib/ # Core config management
│ │ ├── config_loader.ts # HazoConfig class (Node.js)
│ │ ├── mock_config_provider.ts # Client-safe mock
│ │ ├── types.ts # ConfigProvider interfaces
│ │ └── app_config_types.ts # AppConfig interfaces (v2.0+)
│ ├── 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:

`bash
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