{"id":37833184,"url":"https://github.com/xraph/forgeui","last_synced_at":"2026-04-02T16:20:02.094Z","repository":{"id":329889061,"uuid":"1120812985","full_name":"xraph/forgeui","owner":"xraph","description":"A Pure SSR UI framework for Golang inpsired by Shadcn and Flutter","archived":false,"fork":false,"pushed_at":"2026-03-28T04:24:21.000Z","size":1301,"stargazers_count":6,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T09:37:47.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xraph.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T01:37:38.000Z","updated_at":"2026-03-28T04:19:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xraph/forgeui","commit_stats":null,"previous_names":["xraph/forgeui"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/xraph/forgeui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforgeui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforgeui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforgeui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforgeui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xraph","download_url":"https://codeload.github.com/xraph/forgeui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xraph%2Fforgeui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31309834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T15:50:56.646Z","updated_at":"2026-04-02T16:20:02.067Z","avatar_url":"https://github.com/xraph.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ForgeUI\n\nForgeUI is a comprehensive SSR-first UI framework for Go, built on [templ](https://templ.guide) with [templui](https://templui.io) components, Tailwind CSS styling, and shadcn-inspired design patterns. It provides everything you need to build modern, interactive web applications entirely in Go.\n\n## Features\n\n### Core Framework\n- ✅ **SSR-First**: Pure Go component rendering with zero client-side dependencies required\n- ✅ **Type-Safe**: Full Go type safety with templ templates\n- ✅ **templui Components**: shadcn-inspired component library via templui\n- ✅ **Tailwind CSS**: Utility-first CSS styling with built-in processing\n- ✅ **35+ Components**: Production-ready UI components\n\n### Frontend Integration\n- ✅ **Alpine.js Integration**: Directives, stores, magic helpers, and plugins\n- ✅ **Client-Side Routing**: Pinecone Router integration for SPA navigation\n- ✅ **HTMX Support**: Complete HTMX attribute helpers and server-side utilities\n- ✅ **Icons**: 1600+ Lucide icons with customization options\n- ✅ **Animation System**: Tailwind animations, transitions, and keyframes\n\n### Backend Features\n- ✅ **Router**: Production-ready HTTP routing with middleware support\n- ✅ **Bridge**: Go-JavaScript RPC bridge for calling Go functions from client-side\n- ✅ **Plugin System**: Extensible plugin architecture with dependency management\n- ✅ **Theme System**: Customizable themes with CSS variables and color tokens\n\n### Developer Tools\n- ✅ **Assets Pipeline**: Built-in esbuild, Tailwind CSS, and file fingerprinting\n- ✅ **Dev Server**: Hot-reload development server with file watching\n- ✅ **CLI**: Command-line tools for project scaffolding and management\n- ✅ **Layout Helpers**: Page builder with meta tags, scripts, and structured layouts\n\n## Why ForgeUI?\n\n- 🚀 **Go All The Way**: Write your entire frontend in Go with templ templates\n- 🎯 **Type Safety**: Catch errors at compile time, not runtime\n- ⚡ **SSR Performance**: Server-rendered HTML with optional progressive enhancement\n- 🎨 **Beautiful by Default**: shadcn-inspired design that looks great out of the box\n- 🔧 **Full Stack**: Router, RPC, assets, themes - everything you need\n- 📦 **Zero Config**: Works out of the box with sensible defaults\n- 🔌 **Extensible**: Plugin system for adding custom functionality\n- 🎭 **Progressive**: Start with pure SSR, add Alpine.js/HTMX as needed\n\n## Installation\n\n```bash\ngo get github.com/xraph/forgeui\n```\n\n## Quick Start\n\n### 1. Create Your First Application\n\n**main.go:**\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"net/http\"\n\n    \"github.com/a-h/templ\"\n    \"github.com/xraph/forgeui\"\n    \"github.com/xraph/forgeui/router\"\n)\n\nfunc main() {\n    // Create ForgeUI app\n    app := forgeui.New(\n        forgeui.WithDebug(true),\n        forgeui.WithThemeName(\"default\"),\n    )\n\n    // Register routes\n    app.Get(\"/\", HomePage)\n\n    // Start server\n    log.Println(\"Server running on http://localhost:8080\")\n    http.ListenAndServe(\":8080\", app.Handler())\n}\n\nfunc HomePage(ctx *router.PageContext) (templ.Component, error) {\n    return HomePageView(), nil\n}\n```\n\n**home.templ:**\n\n```templ\npackage main\n\ntempl HomePageView() {\n    \u003c!DOCTYPE html\u003e\n    \u003chtml lang=\"en\"\u003e\n        \u003chead\u003e\n            \u003cmeta charset=\"UTF-8\"/\u003e\n            \u003ctitle\u003eForgeUI App\u003c/title\u003e\n        \u003c/head\u003e\n        \u003cbody\u003e\n            \u003cdiv class=\"container mx-auto p-8\"\u003e\n                \u003ch1 class=\"text-4xl font-bold\"\u003eWelcome to ForgeUI\u003c/h1\u003e\n                \u003cp\u003eBuild beautiful UIs with Go and templ.\u003c/p\u003e\n                \u003ca href=\"/about\" class=\"btn btn-primary\"\u003eGet Started\u003c/a\u003e\n            \u003c/div\u003e\n        \u003c/body\u003e\n    \u003c/html\u003e\n}\n```\n\n### 2. Run Your Application\n\n```bash\ngo run main.go\n```\n\nVisit `http://localhost:8080` to see your app!\n\n### 3. Add Interactivity (Optional)\n\nAdd Alpine.js for client-side interactivity in your `.templ` files:\n\n```templ\npackage main\n\nimport \"github.com/xraph/forgeui/alpine\"\n\ntempl InteractivePage() {\n    \u003c!DOCTYPE html\u003e\n    \u003chtml lang=\"en\"\u003e\n        \u003chead\u003e\n            \u003ctitle\u003eInteractive App\u003c/title\u003e\n            @alpine.Scripts()\n        \u003c/head\u003e\n        \u003cbody\u003e\n            \u003cdiv x-data=\"{ count: 0 }\"\u003e\n                \u003cbutton @click=\"count++\"\u003eIncrement\u003c/button\u003e\n                \u003cspan x-text=\"count\"\u003e\u003c/span\u003e\n            \u003c/div\u003e\n        \u003c/body\u003e\n    \u003c/html\u003e\n}\n```\n\n## Components\n\n### Layout Primitives\n- ✅ **Box** - Polymorphic container with responsive props\n- ✅ **Flex** - Flexbox layout with direction and alignment\n- ✅ **Grid** - CSS Grid layout with responsive columns\n- ✅ **Stack** - VStack/HStack for vertical/horizontal layouts\n- ✅ **Center** - Centered container with responsive centering\n- ✅ **Container** - Responsive container with max-width\n- ✅ **Text** - Typography primitive with semantic HTML\n- ✅ **Spacer** - Flexible spacer for layouts\n\n### Buttons \u0026 Actions\n- ✅ **Button** - All variants (Primary, Secondary, Destructive, Outline, Ghost, Link)\n- ✅ **Button Group** - Grouped buttons with gap control\n- ✅ **Icon Button** - Compact icon-only buttons\n\n### Content Display\n- ✅ **Card** - Compound component (Header, Title, Description, Content, Footer)\n- ✅ **Badge** - Status indicators and labels\n- ✅ **Avatar** - User avatars with image and fallback\n- ✅ **Alert** - Alert messages with variants (Info, Success, Warning, Error)\n- ✅ **Separator** - Horizontal/vertical dividers\n- ✅ **Empty State** - Empty state placeholders\n- ✅ **List** - List containers with list items\n\n### Navigation\n- ✅ **Navbar** - Navigation bar component\n- ✅ **Breadcrumb** - Breadcrumb navigation\n- ✅ **Tabs** - Tabbed navigation and content\n- ✅ **Menu** - Menu and menu items\n- ✅ **Sidebar** - Collapsible sidebar navigation\n- ✅ **Pagination** - Page navigation controls\n\n### Forms\n- ✅ **Form** - Form wrapper with validation helpers\n- ✅ **Label** - Accessible form labels\n- ✅ **Input** - Text inputs with variants and validation states\n- ✅ **Input Group** - Input with icons and addons\n- ✅ **Textarea** - Multi-line text input\n- ✅ **Checkbox** - Checkbox inputs with labels\n- ✅ **Radio** - Radio buttons with radio groups\n- ✅ **Switch** - Toggle switches\n- ✅ **Select** - Native select dropdowns\n- ✅ **Slider** - Range sliders\n\n### Overlays\n- ✅ **Modal** - Modal dialogs\n- ✅ **Dialog** - Dialog component\n- ✅ **Alert Dialog** - Confirmation dialogs\n- ✅ **Drawer** - Slide-out panels\n- ✅ **Sheet** - Bottom/side sheets\n- ✅ **Dropdown** - Dropdown menus\n- ✅ **Context Menu** - Right-click context menus\n- ✅ **Popover** - Floating popovers\n- ✅ **Tooltip** - Hover tooltips\n- ✅ **Toast** - Toast notifications with toaster\n\n### Feedback\n- ✅ **Spinner** - Loading spinners\n- ✅ **Skeleton** - Loading placeholders\n- ✅ **Progress** - Progress bars\n\n### Data Display\n- ✅ **Table** - Data tables with header, body, rows, and cells\n- ✅ **DataTable** - Advanced tables with sorting, filtering, and pagination\n\n## Usage Examples\n\n### Button (templui)\n\n```templ\nimport \"github.com/xraph/forgeui/components/button\"\n\n// Primary button\n@button.Button(button.Props{Variant: button.VariantDefault}) {\n    Save\n}\n\n// Destructive button\n@button.Button(button.Props{Variant: button.VariantDestructive, Size: button.SizeLg}) {\n    Delete\n}\n```\n\n### Card (templui)\n\n```templ\nimport \"github.com/xraph/forgeui/components/card\"\n\n@card.Card(card.Props{}) {\n    @card.Header() {\n        @card.Title() { Settings }\n        @card.Description() { Manage your account settings }\n    }\n    @card.Content() {\n        // Your content here\n    }\n    @card.Footer() {\n        @button.Button(button.Props{}) { Save Changes }\n    }\n}\n```\n\n### Layout with Primitives\n\n```templ\nimport \"github.com/xraph/forgeui/primitives\"\n\n@primitives.Container(primitives.ContainerProps{}) {\n    @primitives.Stack(primitives.StackProps{Direction: \"vertical\", Gap: \"8\"}) {\n        @primitives.Text(primitives.TextProps{As: \"h1\", Size: \"text-4xl\", Weight: \"font-bold\"}) {\n            Dashboard\n        }\n        @primitives.Grid(primitives.GridProps{Cols: 1, ColsMD: 2, ColsLG: 3, Gap: \"6\"}) {\n            // Grid items here\n        }\n    }\n}\n```\n\n## Router\n\nProduction-ready HTTP routing with pattern matching and middleware:\n\n```go\napp := forgeui.New()\n\n// Static routes\napp.Get(\"/\", HomePage)\napp.Get(\"/about\", AboutPage)\n\n// Path parameters\napp.Get(\"/users/:id\", UserProfile)\napp.Get(\"/users/:userId/posts/:postId\", PostDetail)\n\n// Wildcards\napp.Get(\"/files/*filepath\", ServeFile)\n\n// Middleware\napp.Use(router.Logger())\napp.Use(router.Recovery())\napp.Use(router.CORS(\"*\"))\n\n// Route-specific middleware\nroute := app.Get(\"/admin\", AdminDashboard)\nroute.WithMiddleware(AuthMiddleware)\n\n// Named routes for URL generation\napp.Router().Name(\"user.post\", route)\nurl := app.Router().URL(\"user.post\", userID, postID)\n```\n\n### PageContext\n\nAccess request data with rich context utilities:\n\n```go\nfunc UserProfile(ctx *router.PageContext) (templ.Component, error) {\n    // Path parameters\n    id := ctx.Param(\"id\")\n    userID, _ := ctx.ParamInt(\"id\")\n\n    // Query parameters\n    query := ctx.Query(\"q\")\n    page, _ := ctx.QueryInt(\"page\")\n\n    // Headers and cookies\n    auth := ctx.Header(\"Authorization\")\n    cookie, _ := ctx.Cookie(\"session\")\n\n    // Context values (set by middleware)\n    uid := ctx.GetInt(\"user_id\")\n\n    return UserProfileView(id), nil\n}\n```\n\nSee [router/README.md](router/README.md) for complete documentation.\n\n## Bridge - Go to JavaScript RPC\n\nCall Go functions directly from JavaScript using JSON-RPC 2.0:\n\n### Server Side\n\n```go\nb := bridge.New()\n\n// Register Go functions\nb.Register(\"createUser\", func(ctx bridge.Context, input struct {\n    Name  string `json:\"name\"`\n    Email string `json:\"email\"`\n}) (struct {\n    ID   int    `json:\"id\"`\n    Name string `json:\"name\"`\n}, error) {\n    user := createUserInDB(input.Name, input.Email)\n    return struct {\n        ID   int    `json:\"id\"`\n        Name string `json:\"name\"`\n    }{ID: user.ID, Name: user.Name}, nil\n})\n\n// Function options\nb.Register(\"adminAction\", handler,\n    bridge.RequireAuth(),\n    bridge.RequireRoles(\"admin\"),\n    bridge.WithRateLimit(10),\n    bridge.WithTimeout(10*time.Second),\n)\n\n// Enable bridge on router\nbridge.EnableBridge(app.Router(), b)\n```\n\n### Client Side\n\n```templ\n// Include bridge scripts in your layout\n@bridge.BridgeScripts(bridge.ScriptConfig{\n    Endpoint: \"/api/bridge\",\n    CSRFToken: csrfToken,\n    IncludeAlpine: true,\n})\n\n// Alpine.js integration\n\u003cbutton @click=\"result = await $bridge.call('createUser', {name, email})\"\u003e\n    Create User\n\u003c/button\u003e\n```\n\n**Features:**\n- HTTP (JSON-RPC 2.0), WebSocket, and SSE transports\n- Built-in authentication, authorization, and rate limiting\n- Automatic parameter validation\n- CSRF protection\n- Caching support\n- Alpine.js magic helpers\n\nSee [bridge/README.md](bridge/README.md) for complete documentation.\n\n## HTMX Integration\n\nComplete HTMX support with type-safe attribute helpers:\n\n```templ\n// In your layout templ file\n@htmx.Scripts()\n\n// HTMX attributes on elements\n\u003cbutton { htmx.HxGet(\"/api/users\")... } { htmx.HxTarget(\"#user-list\")... } { htmx.HxSwap(\"innerHTML\")... }\u003e\n    Load Users\n\u003c/button\u003e\n\n// Advanced triggers\n\u003cinput { htmx.HxTriggerDebounce(\"keyup\", \"500ms\")... } { htmx.HxGet(\"/search\")... }/\u003e\n```\n\nServer-side detection and response headers work the same:\n\n```go\nfunc handler(w http.ResponseWriter, r *http.Request) {\n    if htmx.IsHTMX(r) {\n        renderPartial(w)\n    } else {\n        renderFullPage(w)\n    }\n}\n\nhtmx.TriggerEvent(w, \"refresh\")\nhtmx.SetHTMXRedirect(w, \"/login\")\n```\n\nSee [htmx/README.md](htmx/README.md) for complete documentation.\n\n## Alpine.js Integration\n\nSeamless Alpine.js integration with directives, stores, and plugins:\n\n```templ\n// Include Alpine.js in your layout\n@alpine.Scripts()\n\n// Alpine directives on elements\n\u003cdiv x-data=\"{ count: 0 }\"\u003e\n    \u003cbutton @click=\"count++\"\u003eIncrement\u003c/button\u003e\n    \u003cspan x-text=\"count\"\u003e\u003c/span\u003e\n\u003c/div\u003e\n\n// Or use the helper functions for programmatic attributes\n\u003cdiv { alpine.XShow(\"isVisible\")... } { alpine.XTransitionSimple()... }\u003e\n    Content\n\u003c/div\u003e\n```\n\nAlpine stores and custom directives in Go:\n\n```go\nalpine.Store(\"app\", map[string]any{\n    \"user\": nil,\n    \"isLoggedIn\": false,\n})\n\nalpine.Directive(\"click-outside\", `(el, {expression}, {evaluate}) =\u003e {\n    // directive implementation\n}`)\n```\n\n## Icons\n\n1600+ Lucide icons with full customization:\n\n```templ\n// Basic usage in templ files\n@icons.Check()\n@icons.Search()\n@icons.User()\n\n// Customization\n@icons.Check(icons.WithSize(24), icons.WithColor(\"green\"), icons.WithClass(\"text-green-500\"))\n\n// In buttons\n@button.Button(button.Props{}) {\n    @icons.Plus(icons.WithSize(16))\n    Add Item\n}\n\n// Loading spinner\n@icons.Loader(icons.WithSize(20), icons.WithClass(\"animate-spin\"))\n```\n\nSee [icons/README.md](icons/README.md) for complete documentation.\n\n## Plugin System\n\nExtensible plugin architecture with dependency management:\n\n```go\n// Create a plugin\ntype MyPlugin struct {\n    *plugin.PluginBase\n}\n\nfunc New() *MyPlugin {\n    return \u0026MyPlugin{\n        PluginBase: plugin.NewPluginBase(plugin.PluginInfo{\n            Name:    \"my-plugin\",\n            Version: \"1.0.0\",\n            Dependencies: []plugin.Dependency{\n                {Name: \"other-plugin\", Version: \"\u003e=1.0.0\"},\n            },\n        }),\n    }\n}\n\nfunc (p *MyPlugin) Init(ctx context.Context, r *plugin.Registry) error {\n    // Initialize plugin\n    return nil\n}\n\n// Use plugins\nregistry := plugin.NewRegistry()\nregistry.Use(\n    myplugin.New(),\n    otherplugin.New(),\n)\nregistry.Initialize(ctx)\ndefer registry.Shutdown(ctx)\n```\n\n**Plugin Types:**\n- Component plugins (extend UI components)\n- Alpine plugins (scripts, directives, stores)\n- Theme plugins (custom themes and fonts)\n- Middleware plugins (HTTP middleware)\n\nSee [plugin/README.md](plugin/README.md) for complete documentation.\n\n## Assets Pipeline\n\nBuilt-in asset management with Tailwind CSS, esbuild, and fingerprinting:\n\n```go\napp := forgeui.New()\n\n// Configure assets\napp.WithAssets(assets.Config{\n    Enabled:      true,\n    OutputDir:    \"./dist\",\n    Minify:       true,\n    Fingerprint:  true,\n    Tailwind: assets.TailwindConfig{\n        Input:     \"./styles/input.css\",\n        Output:    \"./dist/styles.css\",\n        ConfigFile: \"./tailwind.config.js\",\n    },\n    ESBuild: assets.ESBuildConfig{\n        EntryPoints: []string{\"./js/app.js\"},\n        Outdir:     \"./dist/js\",\n    },\n})\n\n// Development server with hot-reload\nif err := app.StartDevServer(\":3000\"); err != nil {\n    log.Fatal(err)\n}\n```\n\n**Features:**\n- Tailwind CSS compilation\n- JavaScript bundling with esbuild\n- File fingerprinting for cache busting\n- Hot-reload development server\n- Asset manifest generation\n\nSee [assets/README.md](assets/README.md) for complete documentation.\n\n## Theme System\n\nCustomizable themes with CSS variables:\n\n```go\n// Use built-in theme\napp := forgeui.New(\n    forgeui.WithThemeName(\"default\"),\n)\n\n// Create custom theme\ncustomTheme := theme.Theme{\n    Colors: theme.ColorTokens{\n        Primary:   \"#3b82f6\",\n        Secondary: \"#64748b\",\n        Background: \"#ffffff\",\n        Foreground: \"#0f172a\",\n    },\n    Radius: theme.RadiusTokens{\n        Default: \"0.5rem\",\n        Button:  \"0.375rem\",\n        Card:    \"0.75rem\",\n    },\n}\n\napp.RegisterTheme(\"custom\", customTheme)\n```\n\n## CLI Tools\n\nCommand-line tools for project management:\n\n```bash\n# Create new project\nforgeui new myproject\n\n# Create new component\nforgeui create component MyComponent\n\n# Create new page\nforgeui create page HomePage\n\n# Run development server\nforgeui dev\n\n# Build for production\nforgeui build\n```\n\n## Architecture\n\nForgeUI follows a layered architecture designed for scalability and maintainability:\n\n```text\n┌─────────────────────────────────────┐\n│  Application Layer                  │\n│  (Your App, Examples, CLI)          │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│  Integration Layer                  │\n│  (Router, Bridge, HTMX, Alpine)     │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│  Components Layer                   │\n│  (UI Components, Icons, Layouts)    │\n└──────────────┬──────────────────────┘\n               │\n┌──────────────▼──────────────────────┐\n│  Foundation Layer                   │\n│  (Primitives, CVA, Theme, Assets)   │\n└─────────────────────────────────────┘\n```\n\n### Design Principles\n- **Composability**: All components are composable templ components\n- **Type Safety**: Full Go type checking at compile time\n- **Minimal Dependencies**: Core components have zero client-side dependencies\n- **Progressive Enhancement**: Add interactivity with Alpine.js and HTMX\n- **Unidirectional Flow**: Higher layers depend on lower layers, never the reverse\n\n## Testing\n\nForgeUI includes comprehensive test coverage across all packages:\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run with coverage\ngo test -cover ./...\n\n# Run with race detection\ngo test -race ./...\n\n# Run specific package tests\ngo test ./components/button/...\ngo test ./router/...\n\n# Generate coverage report\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n```\n\n### Test Structure\n\nComponents and features include:\n- **Unit tests**: Testing individual functions and components\n- **Integration tests**: Testing component interactions\n- **HTTP tests**: Using `httptest` for router and bridge testing\n- **Golden files**: Snapshot testing for component output\n\n## Configuration\n\n### Application Configuration\n\n```go\napp := forgeui.New(\n    // Core options\n    forgeui.WithDebug(true),\n    forgeui.WithThemeName(\"default\"),\n    forgeui.WithStaticPath(\"/static\"),\n    forgeui.WithDefaultSize(forgeui.SizeMD),\n    forgeui.WithDefaultVariant(forgeui.VariantDefault),\n    forgeui.WithDefaultRadius(forgeui.RadiusMD),\n    \n    // Assets configuration\n    forgeui.WithAssets(assets.Config{\n        Enabled:     true,\n        OutputDir:   \"./dist\",\n        Minify:      true,\n        Fingerprint: true,\n    }),\n)\n\n// Initialize the application\nif err := app.Initialize(context.Background()); err != nil {\n    log.Fatal(err)\n}\n\n// Start HTTP server\nhttp.ListenAndServe(\":8080\", app.Router())\n```\n\n### Environment-Specific Config\n\n```go\nvar cfg forgeui.Config\n\nif os.Getenv(\"ENV\") == \"production\" {\n    cfg = forgeui.Config{\n        Debug:      false,\n        StaticPath: \"/static\",\n        Assets: assets.Config{\n            Enabled:     true,\n            Minify:      true,\n            Fingerprint: true,\n        },\n    }\n} else {\n    cfg = forgeui.Config{\n        Debug:      true,\n        StaticPath: \"/static\",\n        Assets: assets.Config{\n            Enabled:    true,\n            Minify:     false,\n            Fingerprint: false,\n        },\n    }\n}\n\napp := forgeui.NewWithConfig(cfg)\n```\n\n## Examples\n\nThe `example/` directory contains complete working examples:\n\n```bash\ncd example\ngo run main.go\n```\n\nVisit `http://localhost:8080` to see:\n- **Component Showcase**: All UI components with variations\n- **Dashboard Demo**: Real-world dashboard layout\n- **Interactive Examples**: Alpine.js and HTMX integration\n- **Router Demo**: Client-side routing with Pinecone Router\n- **Bridge Demo**: Go-JavaScript RPC examples\n- **Assets Demo**: Asset pipeline in action\n\n## Documentation\n\nEach package includes comprehensive documentation:\n\n- [Router](router/README.md) - HTTP routing system\n- [Bridge](bridge/README.md) - Go-JavaScript RPC bridge\n- [HTMX](htmx/README.md) - HTMX integration\n- [Icons](icons/README.md) - Icon system\n- [Plugin](plugin/README.md) - Plugin architecture\n- [Assets](assets/README.md) - Asset management\n- [Components](components/) - Individual component docs\n\n## Project Structure\n\n```text\nforgeui/\n├── alpine/           # Alpine.js integration\n├── animation/        # Animation and transition utilities\n├── assets/          # Asset pipeline (CSS, JS, Tailwind)\n├── bridge/          # Go-JavaScript RPC bridge\n├── cli/             # Command-line tools\n├── components/      # UI components\n│   ├── button/\n│   ├── card/\n│   ├── form/\n│   └── ...\n├── example/         # Example applications\n├── htmx/           # HTMX integration\n├── icons/          # Icon system (Lucide)\n├── htmx/           # HTMX integration\n├── plugin/         # Plugin system\n├── primitives/     # Layout primitives\n├── router/         # HTTP router\n├── theme/          # Theme system\n└── ...\n```\n\n## Contributing\n\nForgeUI welcomes contributions! Follow these guidelines:\n\n### Code Style\n1. **Follow Go conventions**: Use `gofmt`, `golangci-lint`\n2. **Use templ templates**: Write UI in `.templ` files with Props structs\n3. **Use templui components**: Leverage templui as the base component library\n4. **Documentation**: Document all exported functions with examples\n5. **Type safety**: Leverage Go's type system\n\n### Component Development\n1. **Respect architecture layers**: Components should only import from lower layers\n2. **Test thoroughly**: Aim for 80%+ coverage\n3. **Include examples**: Add examples to component documentation\n4. **Accessibility**: Follow ARIA guidelines\n5. **Mobile-first**: Ensure responsive design\n\n### Running Tests\n\n```bash\n# Run tests\ngo test ./...\n\n# Run with coverage\ngo test -cover ./...\n\n# Run linter\ngolangci-lint run\n```\n\n### Pull Request Process\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Write tests for your changes\n4. Ensure all tests pass\n5. Update documentation\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## Best Practices\n\n### Component Composition\n\n```templ\n// ✅ Good: Compose templ components\n@button.Button(button.Props{}) {\n    @icons.Plus(icons.WithSize(16))\n    Add Item\n}\n```\n\n### Error Handling\n\n```go\n// ✅ Good: Return errors from handlers\nfunc UserProfile(ctx *router.PageContext) (templ.Component, error) {\n    user, err := getUser(ctx.Param(\"id\"))\n    if err != nil {\n        return nil, err\n    }\n    return UserProfileView(user), nil\n}\n\n// ❌ Bad: Don't panic or ignore errors\n```\n\n### Context Usage\n\n```go\n// ✅ Good: Pass context through the stack\nfunc handler(ctx *router.PageContext) (templ.Component, error) {\n    user := ctx.GetString(\"user_id\")\n    return UserView(user), nil\n}\n\n// ❌ Bad: Don't use global variables\n```\n\n## Performance\n\nForgeUI is designed for performance:\n\n### Server-Side Rendering\n- **Fast**: Pure Go rendering with minimal overhead\n- **Efficient**: No JavaScript runtime required for basic pages\n- **Scalable**: Handles thousands of requests per second\n\n### Asset Pipeline\n- **Optimized**: Built-in minification and fingerprinting\n- **Cached**: Long-lived browser caching with cache busting\n- **Small**: Tailwind CSS purging removes unused styles\n\n### Progressive Enhancement\n- **Lightweight**: Start with 0KB of JavaScript\n- **Optional**: Add Alpine.js (15KB) or HTMX (14KB) only when needed\n- **Lazy**: Load components on demand\n\n### Benchmarks\n\nTypical performance on modest hardware (4 core, 8GB RAM):\n\n- **Simple page render**: ~0.5ms\n- **Complex dashboard**: ~2ms\n- **Component with children**: ~0.1ms per child\n- **Throughput**: 10,000+ req/s\n\n## Production Checklist\n\nBefore deploying to production:\n\n- [ ] Set `WithDebug(false)`\n- [ ] Enable asset minification\n- [ ] Enable asset fingerprinting\n- [ ] Use HTTPS (TLS)\n- [ ] Set up proper logging\n- [ ] Configure CORS if needed\n- [ ] Set up rate limiting\n- [ ] Enable CSRF protection\n- [ ] Configure proper caching headers\n- [ ] Test with production data\n- [ ] Set up monitoring and alerts\n\n## Troubleshooting\n\n### Common Issues\n\n**Components not rendering?**\n- Check if you've initialized the app with `app.Initialize(ctx)`\n- Verify Tailwind CSS is included in your HTML\n\n**Styles not applying?**\n- Ensure Tailwind CSS is properly configured\n- Check if the asset pipeline is enabled\n- Verify the CSS file is being served\n\n**HTMX not working?**\n- Include `htmx.Scripts()` in your HTML head\n- Check browser console for errors\n- Verify HTMX attributes are correct\n\n**Alpine.js not working?**\n- Include `alpine.Scripts()` in your HTML head\n- Check for JavaScript errors in console\n- Verify Alpine syntax is correct\n\n## Community \u0026 Support\n\n- **GitHub Issues**: [Report bugs and request features](https://github.com/xraph/forgeui/issues)\n- **Discussions**: [Ask questions and share ideas](https://github.com/xraph/forgeui/discussions)\n- **Examples**: Check the `example/` directory for working code\n\n## Roadmap\n\nPlanned features and improvements:\n\n- [ ] More component variants and customization options\n- [ ] Server-side validation helpers\n- [ ] Form builder with automatic validation\n- [ ] More built-in plugins\n- [ ] WebSocket utilities\n- [ ] Admin panel template\n- [ ] CLI improvements (scaffolding, generators)\n- [ ] Performance monitoring utilities\n- [ ] i18n support\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## Credits \u0026 Inspiration\n\nForgeUI stands on the shoulders of giants:\n\n- **[templ](https://templ.guide)** - Type-safe HTML templating for Go\n- **[templui](https://templui.io)** - shadcn-inspired component library for templ\n- **[shadcn/ui](https://ui.shadcn.com/)** - Design inspiration and component patterns\n- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework\n- **[Alpine.js](https://alpinejs.dev/)** - Lightweight JavaScript framework\n- **[HTMX](https://htmx.org/)** - High power tools for HTML\n- **[Lucide](https://lucide.dev/)** - Beautiful icon library\n\nMade with ❤️ for the Go community","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fforgeui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxraph%2Fforgeui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxraph%2Fforgeui/lists"}