@voilajsx/uikit

# UIKit CLI Guide **Master the UIKit command-line interface to scaffold, develop, and deploy production-ready React applications with zero configuration.** ## 🚀 Why UIKit CLI? The UIKit CLI is your **development accelerator** that transforms hours of project setup into minutes of productive coding. Unlike other React scaffolding tools that give you a basic skeleton, UIKit CLI provides **production-ready project structures** with built-in routing, theming, and deployment workflows. **Traditional React Setup Problems:** - ⏰ **Hours of configuration** - Webpack, routing, theming, deployment setup - 🔧 **Decision fatigue** - Which router? Which UI library? How to structure files? - 🐛 **Integration issues** - Components don't work together seamlessly - 📱 **Responsive headaches** - Mobile-first design requires extensive CSS work **UIKit CLI Solutions:** - ⚡ **Zero configuration** - Production setup in one command - 🎯 **Opinionated structure** - Battle-tested patterns, no decisions needed - 🎨 **Integrated theming** - 5 professional themes, custom theme generation - 📱 **Mobile-first layouts** - Responsive AdminLayout, PageLayout, AuthLayout - 🚀 **One-command deployment** - Deploy to GitHub Pages, Netlify, Vercel instantly **The result:** Go from idea to deployed application in under 10 minutes. --- ## 📁 Project Templates Overview UIKit CLI provides **4 carefully designed templates** that scale from simple demos to enterprise applications: | Template | Command | Structure | Best For | Key Features | |----------|---------|-----------|----------|--------------| | **Single** | `uikit create myapp` | Single page showcase | Component demos, learning | No routing, simple structure | | **SPA** | `uikit create myapp --spa` | Single-page application | Marketing sites, portfolios | React Router, multiple views | | **Multi** | `uikit create myapp --multi` | Multi-layout application | Business apps, SaaS platforms | Multiple layouts, organized routing | | **FBCA** | `uikit create myapp --fbca` | Feature-based architecture | Enterprise, large applications | Auto-discovery routing, feature isolation | ### Template Decision Guide ``` How complex is your application? Simple Demo/Learning └── Single Template ├── One page with components ├── No routing needed └── Perfect for experimenting Marketing/Portfolio Site └── SPA Template ├── Multiple pages, single layout ├── React Router included └── Clean navigation structure Business Application └── Multi Template ├── Different layouts (Admin, Auth, Page) ├── Organized page structure └── Professional routing Enterprise Application └── FBCA Template ├── Feature-based organization ├── Scalable architecture ├── Auto-discovery routing └── Team collaboration ready ``` --- ## 🏗️ Project Generation ### Single Template ```bash # Generate simple component showcase uikit create demo-app # What you get: # /demo-app # ├── src/ # │ ├── App.tsx # Main component showcase # │ ├── main.tsx # React entry point # │ └── index.css # Tailwind + UIKit styles # ├── index.html # └── package.json ``` **Folder Structure:** - **`src/App.tsx`** - Edit this file to showcase components - **`src/main.tsx`** - Theme configuration and React setup - **`src/index.css`** - Tailwind CSS + UIKit styles import **When to use:** Learning UIKit, component demos, simple prototypes ### SPA Template ```bash # Generate single-page application uikit create portfolio-site --spa # What you get: # /portfolio-site # ├── src/ # │ ├── App.tsx # All pages and router configuration # │ ├── main.tsx # App entry with theme # │ └── index.css # Tailwind + UIKit styles # ├── index.html # └── package.json ``` **Folder Structure:** - **`src/App.tsx`** - Contains all page components (HomePage, ComponentsPage, ThemesPage, DocsPage) and router configuration - **`src/main.tsx`** - Theme and React setup - **`src/index.css`** - Tailwind CSS + UIKit styles import **When to use:** Marketing websites, portfolios, documentation sites, simple applications ### Multi Template ```bash # Generate multi-layout application uikit create business-app --multi # What you get: # /business-app # ├── src/ # │ ├── App.tsx # Router with layout switching # │ ├── main.tsx # App entry with theme # │ ├── router.tsx # Route configuration # │ ├── pages/ # │ │ ├── Home.tsx # Homepage with PageLayout # │ │ ├── About.tsx # About page # │ │ ├── Contact.tsx # Contact page # │ │ ├── Components.tsx # Component showcase # │ │ ├── Themes.tsx # Theme switcher # │ │ ├── Login.tsx # Login with AuthLayout # │ │ ├── Dashboard.tsx # Dashboard with AdminLayout # │ │ └── ErrorPage.tsx # Error page with BlankLayout # │ ├── components/ # │ │ ├── Header.tsx # Site header # │ │ ├── Footer.tsx # Site footer # │ │ └── index.ts # Component exports # │ └── index.css # Tailwind + UIKit styles # ├── public/ # │ ├── favicon.svg # │ └── hero.svg # ├── docs/ # Development guides # ├── index.html # └── package.json ``` **Folder Structure:** - **`src/pages/`** - All page components (Home, About, Contact, Login, Dashboard, etc.) - **`src/components/`** - Shared components (Header, Footer) - **`src/router.tsx`** - Simple route configuration with path/component mapping - **`src/App.tsx`** - Layout wrapper that chooses layout based on current route - **`src/main.tsx`** - Theme configuration and React setup - **`src/index.css`** - Tailwind CSS + UIKit styles import **When to use:** Business applications, SaaS platforms, applications with distinct user roles ### FBCA Template (Recommended for Enterprise) ```bash # Generate feature-based architecture uikit create enterprise-app --fbca # What you get: # /enterprise-app # ├── src/ # │ └── web/ # │ ├── main.tsx # App entry point # │ ├── App.tsx # Root router with PageRouter # │ ├── lib/ # │ │ └── page-router.tsx # Auto-discovery routing engine # │ ├── features/ # │ │ ├── main/ # │ │ │ ├── pages/ # │ │ │ │ ├── index.tsx # Auto-route: / (homepage) # │ │ │ │ └── About.tsx # Auto-route: /about # │ │ │ └── components/ # │ │ │ └── CTASection.tsx # Homepage components # │ │ ├── auth/ # │ │ │ └── pages/ # │ │ │ └── index.tsx # Auto-route: /auth (login) # │ │ ├── gallery/ # │ │ │ ├── pages/ # │ │ │ │ └── index.tsx # Auto-route: /gallery # │ │ │ └── hooks/ # │ │ │ └── useGallery.ts # Gallery logic # │ │ └── docs/ # │ │ └── pages/ # │ │ └── [...slug].tsx # Auto-route: /docs/* (catch-all) # │ ├── shared/ # │ │ ├── components/ # Reusable components # │ │ │ ├── Header.tsx # Site header # │ │ │ ├── Footer.tsx # Site footer # │ │ │ ├── SEO.tsx # SEO component # │ │ │ └── index.ts # Component exports # │ │ └── hooks/ # │ │ └── useSEO.ts # Shared logic # │ ├── styles/ # │ │ └── index.css # Tailwind + UIKit styles # │ └── index.html # ├── public/ # │ ├── favicon.svg # │ └── hero.svg # ├── docs/ # Development guides # └── package.json ``` **FBCA Folder Structure Explained:** #### **Core Concepts:** - **Feature-based organization** - Each business feature is self-contained - **Auto-discovery routing** - File structure = URL structure (like Next.js) - **Shared resources** - Common components and logic in `/shared` - **Scalable architecture** - Easy to add new features without affecting others #### **Key Directories:** **`src/web/features/`** - Business features (auth, dashboard, public, etc.) - Each feature contains its own pages, components, and hooks - **Complete isolation** - features don't depend on each other - **Team-friendly** - different teams can work on different features **`src/web/features/[feature]/pages/`** - Auto-routing pages - **`index.tsx`** = `/feature` route - **`users.tsx`** = `/feature/users` route - **`[id].tsx`** = `/feature/:id` dynamic route (optional) **`src/web/features/[feature]/components/`** - Feature-specific UI components - Only used within this feature - Can import from `/shared/components` for reusable parts **`src/web/features/[feature]/hooks/`** - Feature-specific logic - Custom React hooks for business logic - API calls, state management, data processing **`src/web/shared/`** - Application-wide resources - **`components/`** - Reusable UI components across features - **`hooks/`** - Shared business logic and utilities - **`utils/`** - Helper functions, constants, API clients #### **Auto-Discovery Routing:** ``` File Structure → URL Route /features/main/pages/index.tsx → / (homepage) /features/main/pages/About.tsx → /about /features/auth/pages/index.tsx → /auth (login) /features/gallery/pages/index.tsx → /gallery /features/docs/pages/[...slug].tsx → /docs/* (catch-all dynamic route) ``` #### **Which Files to Edit in FBCA:** **Adding a new feature:** 1. **Create feature folder:** `src/web/features/[feature-name]/` 2. **Add pages:** `src/web/features/[feature-name]/pages/index.tsx` 3. **Add components:** `src/web/features/[feature-name]/components/` 4. **Add logic:** `src/web/features/[feature-name]/hooks/` **Common editing scenarios:** - **Homepage:** Edit `src/web/features/main/pages/index.tsx` - **Login:** Edit `src/web/features/auth/pages/index.tsx` - **Gallery:** Edit `src/web/features/gallery/pages/index.tsx` - **New page:** Create `src/web/features/[feature]/pages/[name].tsx` - **Dynamic routes:** Use `[id].tsx` for `/feature/:id` or `[...slug].tsx` for catch-all **When to use FBCA:** - ✅ **Enterprise applications** with multiple business domains - ✅ **Large teams** working on different features simultaneously - ✅ **Long-term projects** that need to scale and evolve - ✅ **Complex applications** with 10+ pages and distinct feature areas - ✅ **Applications requiring feature flags** or modular deployment **Why FBCA is powerful:** - **Scalability** - Add new features without touching existing code - **Team collaboration** - Multiple developers can work independently - **Maintainability** - Features are isolated and self-contained - **Performance** - Can implement code splitting per feature - **Testing** - Easy to test features in isolation --- ## ⚡ CLI Commands Reference ### Project Creation Choose the right template: Single (learning), SPA (simple sites), Multi (business apps), or FBCA (enterprise). ```bash # Template generation uikit create <app-name> # Single template uikit create <app-name> --spa # SPA template uikit create <app-name> --multi # Multi-layout template uikit create <app-name> --fbca # Feature-based architecture # With theme selection uikit create myapp --theme elegant # Start with elegant theme ``` ### Code Generation (FBCA Only) FBCA projects support automated code generation for consistent architecture. ```bash # Generate new feature uikit generate feature blog # Creates /features/blog/ with pages, components, hooks # Generate individual components uikit generate page dashboard # Creates page component uikit generate component UserCard # Creates reusable component uikit generate hook useAuth # Creates custom React hook ``` ### Development Workflow UIKit CLI provides smart development and build commands with automatic optimizations. `uikit serve` handles port conflicts and bundles themes. `uikit build` compiles TypeScript, processes themes, and generates SEO files. ```bash # Start development server uikit serve # Smart dev server with theme bundling uikit serve --port 3000 # Use specific port # Production build uikit build # Optimized build with TypeScript & themes uikit build --analyze # Include bundle analysis # Preview production build uikit preview # Test production build locally ``` ### Theme Management Create custom themes to match your brand while maintaining UIKit's design system. ```bash # Generate custom theme uikit generate theme brand # Creates custom theme with your brand colors # Bundle themes to CSS uikit bundle # Processes themes and generates CSS uikit bundle --watch # Watch mode for theme development ``` ### Deployment Deploy UIKit applications as static sites. Use `uikit deploy` for manual deployment or `uikit deploy --github` for automated GitHub Pages. **Manual Deployment:** ```bash uikit deploy # Generates /dist folder for any static host ``` Creates optimized build with theme bundling, SPA routing (404.html), and SEO files. **GitHub Pages Deployment:** ```bash uikit deploy --github # Automated GitHub Pages deployment uikit deploy --github --domain example.com # With custom domain ``` Performs all manual deployment steps plus: - Git validation and repository checks - Creates `.nojekyll` and CNAME files - Pushes to `gh-pages` branch automatically - Configures proper base paths for GitHub URLs **Other Hosting:** ```bash uikit build && npx surge dist/ # Surge.sh uikit build && npx vercel --prod # Vercel uikit build # Then drag dist/ to netlify.com/drop ``` --- ## 🔧 Development Workflow ### Daily Development Process ```bash # 1. Start your project cd your-project uikit serve # Start development server # 2. Develop with live reload # Edit files in src/ folder # Browser automatically refreshes with changes # 3. Theme development (if needed) uikit bundle --watch # Watch theme changes in another terminal # 4. Generate new components (FBCA only) uikit generate page settings # Add new pages as needed ``` ### Build and Test Process ```bash # 1. Create production build uikit build # Generates optimized /dist folder # 2. Test production build locally uikit preview # Serve production build # 3. Deploy to production uikit deploy --github # Deploy to GitHub Pages # OR upload /dist folder to your hosting provider ``` ### Theme Customization Workflow ```bash # 1. Generate custom theme uikit generate theme mycustom # Creates theme with default colors # 2. Start theme development uikit bundle --watch # Watch for theme changes # 3. Customize your brand colors # Edit src/themes/presets/theme-mycustom.js # Change primary, secondary colors to match your brand # 4. See changes instantly # Browser updates automatically with new theme ``` --- ## 🚀 Deployment Guide ### GitHub Pages (Recommended) ```bash # Automatic deployment uikit deploy --github # What this does: # 1. Builds your project (uikit build) # 2. Creates gh-pages branch (if needed) # 3. Pushes /dist content to gh-pages branch # 4. Configures GitHub Pages to serve from gh-pages # 5. Your site is live at: https://username.github.io/repository-name ``` ### Manual Static Hosting ```bash # Build your project uikit build # Upload /dist folder contents to: # - Netlify (drag and drop /dist folder) # - Vercel (vercel --prod /dist) # - AWS S3 (aws s3 sync dist/ s3://your-bucket) # - Any static hosting provider ``` ### Custom Domain Setup ```bash # After GitHub Pages deployment # 1. Go to repository Settings > Pages # 2. Add your custom domain (e.g., myapp.com) # 3. Enable "Enforce HTTPS" # 4. Configure DNS: # - CNAME record: www.myapp.com → username.github.io # - A records: myapp.com → GitHub Pages IPs ``` --- ## 🎯 Best Practices ### Project Structure Best Practices ```bash # ✅ DO: Organize by feature (FBCA) /features/auth/pages/login.tsx /features/auth/components/LoginForm.tsx /features/dashboard/pages/index.tsx # ❌ AVOID: Organize by file type /pages/Login.tsx /pages/Dashboard.tsx /components/LoginForm.tsx ``` ### Development Best Practices ```bash # ✅ DO: Use the CLI for generation uikit generate page settings # Consistent structure # ❌ AVOID: Manual file creation # Creates inconsistent patterns and missing boilerplate ``` ### Theme Best Practices ```bash # ✅ DO: Customize existing themes uikit generate theme brand # Start with defaults, customize as needed # ❌ AVOID: Building themes from scratch # Use semantic color system for consistency ``` ### Deployment Best Practices ```bash # ✅ DO: Test production build before deployment uikit build && uikit preview # ✅ DO: Use automated deployment uikit deploy --github # Consistent, repeatable process # ❌ AVOID: Manual FTP uploads # Error-prone and time-consuming ``` --- ## 🔍 Troubleshooting ### Common Issues **"Command not found: uikit"** ```bash # Install UIKit CLI globally npm install -g @voilajsx/uikit # Verify installation uikit --version ``` **"Port 3000 already in use"** ```bash # Kill process on port 3000 npx kill-port 3000 # Or use different port uikit serve --port 3001 ``` **"Build fails with module errors"** ```bash # Clear node_modules and reinstall rm -rf node_modules package-lock.json npm install # Rebuild uikit build ``` **"Theme changes not applying"** ```bash # Rebuild themes uikit bundle # Clear browser cache # Restart development server uikit serve ``` **"Deployment to GitHub Pages fails"** ```bash # Check repository settings # Ensure GitHub Pages is enabled # Verify branch permissions # Manual deployment uikit build # Manually push /dist contents to gh-pages branch ``` --- ## 📚 Related Guides - **[UIKit Theme Guide](./UIKIT_THEME_GUIDE.md)** - Custom theming and colors - **[UIKit Composite UI System](./UIKIT_COMPOSITE_UI_SYSTEM.md)** - Components and layouts - **[UIKit LLM Guide](./UIKIT_LLM_GUIDE.md)** - Complete implementation reference - **[GitHub Repository](https://github.com/voilajsx/uikit)** - Source code and examples --- **Master UIKit CLI and ship production applications in minutes, not hours** ⚡