Config wrapper with error handling
npm install hazo_configA 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.
- React - UI library
- TypeScript - Type safety
- TailwindCSS - Styling
- Shadcn/UI - Component primitives
- Storybook - Component development and testing
- Vite - Build tool
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.
`bash`
npm install hazo_config
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
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.
v2.0.0 introduces breaking changes with database-backed configuration support:
- New Component: AppConfig for database-backed configuration with JSON value supportorg_id
- Schema Change: Replaces with scope_id for flexible scopingConfigType
- JSON Support: Store structured configuration as JSON with in-UI editing
- Type System: New ('general' | 'json') for value type management
See MIGRATION_V2.md for detailed migration guide from v1.x.
`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')
`
`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
}
`
`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 (
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
Install dependencies:
`bash`
npm install
Run Storybook to develop and test components:
`bash`
npm run storybook
This will start Storybook on http://localhost:6006
Build the library:
`bash`
npm run build
Build Storybook for static deployment:
`bash`
npm run build-storybook
``
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
1. Create your component in src/components/.stories.tsx
2. Create a corresponding file for Storybooksrc/components/index.ts
3. Export the component from src/index.ts
4. Export from to make it available in the library
Use the Shadcn CLI to add components:
`bash`
npx shadcn@latest add [component-name]
- 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`)
MIT