{"id":41812116,"url":"https://github.com/nextproduction/npui","last_synced_at":"2026-01-25T07:01:16.743Z","repository":{"id":203055980,"uuid":"708680917","full_name":"NextProduction/npui","owner":"NextProduction","description":"Next Production User Interface","archived":false,"fork":false,"pushed_at":"2025-08-28T20:42:12.000Z","size":2446,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T15:45:38.728Z","etag":null,"topics":["nextproduction","npui","react-component","react-component-library","react-components","react-ui-components"],"latest_commit_sha":null,"homepage":"https://npui.nextproduction.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NextProduction.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-10-23T07:06:06.000Z","updated_at":"2025-08-28T20:47:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"61618095-019a-47bf-b80a-9f94377c0254","html_url":"https://github.com/NextProduction/npui","commit_stats":null,"previous_names":["nextproduction/npui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NextProduction/npui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NextProduction%2Fnpui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NextProduction%2Fnpui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NextProduction%2Fnpui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NextProduction%2Fnpui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NextProduction","download_url":"https://codeload.github.com/NextProduction/npui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NextProduction%2Fnpui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28747308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T05:12:38.112Z","status":"ssl_error","status_checked_at":"2026-01-25T05:04:50.338Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["nextproduction","npui","react-component","react-component-library","react-components","react-ui-components"],"created_at":"2026-01-25T07:01:01.154Z","updated_at":"2026-01-25T07:01:16.734Z","avatar_url":"https://github.com/NextProduction.png","language":"TypeScript","readme":"# npui - Modern Component Library \u0026 Future Design System\n\n\u003c!-- ![npui Logo](public/placeholder.svg?height=150\u0026width=150\u0026text=npui) --\u003e\n\n`npui` is a modern, accessible, and highly customizable component library for React, built with Tailwind CSS. Developed and maintained by **Mahdi Hazrati** as part of **Next Production Dev**, `npui` aims to empower developers to accelerate their UI development with a collection of beautiful, production-ready components, hooks, and utilities. Our vision is to evolve `npui` into a comprehensive design system that provides a unified language for design and development.\n\n## ✨ Features\n\n*   **Extensive Component Library:** A growing collection of UI components (Buttons, Cards, Alerts, Inputs, Carousels, Accordions, Tabs, Dialogs, Dropdown Menus, Checkboxes, Radio Groups, Selects, Sliders, Switches, Tooltips, Avatar, Badge, Progress, Toast, Calendar, Alert Dialog, Hover Card, Separator) designed for various use cases.\n*   **Custom Hooks:** A curated set of React hooks to simplify common logic and enhance application functionality (e.g., `useDebounce`, `useLocalStorage`, `useOutsideClick`, `useMediaQuery`, `usePrevious`, `useCopyToClipboard`, `useEventListener`, `useIsomorphicLayoutEffect`, `useWindowSize`, `useScrollPosition`).\n*   **Utility Functions:** Essential JavaScript utilities for common tasks (e.g., `cn`, `formatDate`, `capitalize`, `truncateString`, `debounce`, `throttle`, `isValidEmail`, `generateRandomId`, `clamp`, `hexToRgba`, `getRandomItem`).\n*   **Tailwind CSS-first:** All components are styled using Tailwind CSS, providing full control over styling and easy customization.\n*   **Full Customization:** Components are installed directly into your project, allowing you to modify them to suit your exact needs without fighting opinionated defaults.\n*   **Accessibility (A11y):** Components are built with accessibility in mind, following WAI-ARIA guidelines to ensure inclusive user experiences.\n*   **Modular \u0026 Composable:** Designed to be easily combined like building blocks to create complex and unique interfaces.\n*   **Comprehensive Documentation:** Detailed documentation for each component, hook, and utility, including props, variants, code examples, and live previews.\n*   **SEO Friendly:** Optimized for search engines with proper metadata and semantic HTML.\n\n## 🚀 Getting Started\n\n### Installation\n\nTo add `npui` components to your project, you'll use the `npui` CLI tool.\n\nFirst, ensure you have `pnpm` installed globally (`npm install -g pnpm`).\n\nThen, you can use `npx` to run the `npui` CLI:\n\n```bash\nnpx @npui/cli add \u003ccomponent-name\u003e\n```\n\nFor example, to add a Button component:\n\n```bash\nnpx @npui/cli add button\n```\n\nThis command will copy the component's code directly into your project, usually under `src/components/ui/`, making it fully customizable.\n\n### Project Setup (Conceptual)\n\n1.  **Next.js Project:** Ensure you have a Next.js project set up (App Router recommended).\n2.  **Tailwind CSS:** Make sure Tailwind CSS is configured in your project. `npui` relies heavily on Tailwind for styling.\n3.  **`globals.css`:** The `app/globals.css` file should include the base Tailwind directives and any custom CSS variables for `npui`'s theming.\n4.  **`tailwind.config.ts`:** Your Tailwind configuration should extend `npui`'s custom colors and other settings.\n\nYou can also run the conceptual `init` command to help set up your project:\n\n```bash\nnpx @npui/cli init\n```\n\n## 💡 Usage\n\n### Components\n\nOnce a component is added to your project, you can import and use it like any other React component:\n\n```tsx\n// components/my-page.tsx\nimport { Button } from \"@/components/ui/button\"; // Or \"@/components/npui-components/button\" if you moved it\n\nexport default function MyPage() {\n  return (\n    \u003cdiv\u003e\n      \u003cButton onClick={() =\u003e alert(\"Hello!\")}\u003eClick Me\u003c/Button\u003e\n      \u003cButton variant=\"secondary\"\u003eLearn More\u003c/Button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nRefer to the `/docs` section of the `npui` platform for detailed usage, props, and examples for each component.\n\n### Hooks\n\nHooks are functions that let you \"hook into\" React state and lifecycle features from function components.\n\n```tsx\n// components/my-component.tsx\nimport { useState } from \"react\";\nimport { useDebounce } from \"@/hooks/use-debounce\"; // Assuming path\n\nexport default function MyComponent() {\n  const [searchTerm, setSearchTerm] = useState(\"\");\n  const debouncedSearchTerm = useDebounce(searchTerm, 500);\n\n  // Use debouncedSearchTerm for API calls or heavy operations\n  // useEffect(() =\u003e {\n  //   if (debouncedSearchTerm) {\n  //     console.log(\"Fetching data for:\", debouncedSearchTerm);\n  //   }\n  // }, [debouncedSearchTerm]);\n\n  return (\n    \u003cinput\n      type=\"text\"\n      placeholder=\"Search...\"\n      value={searchTerm}\n      onChange={(e) =\u003e setSearchTerm(e.target.value)}\n    /\u003e\n  );\n}\n```\n\nExplore the `/hooks` section for a full list of available hooks and their usage.\n\n### Utilities\n\nUtility functions are standalone helpers for common tasks.\n\n```ts\n// my-script.ts\nimport { capitalize } from \"@/lib/utils/capitalize\"; // Assuming path\nimport { isValidEmail } from \"@/lib/utils/is-valid-email\"; // Assuming path\n\nconsole.log(capitalize(\"hello world\")); // Output: \"Hello world\"\nconsole.log(isValidEmail(\"test@example.com\")); // Output: true\nconsole.log(isValidEmail(\"invalid-email\")); // Output: false\n```\n\nCheck the `/utils` section for all available utilities and their examples.\n\n## 📁 Project Structure (Monorepo)\n\nThis project is structured as a monorepo using `pnpm` workspaces:\n\n```\nnpui-monorepo/\n├── pnpm-workspace.yaml       # Defines monorepo workspaces\n├── package.json              # Root package.json for monorepo scripts\n├── apps/\n│   └── web/                  # The Next.js documentation website\n│       ├── package.json      # Website's dependencies and scripts\n│       ├── app/\n│       ├── components/\n│       └── ...\n└── packages/\n    └── cli/                  # The `npui` CLI tool\n        ├── package.json      # CLI's dependencies and metadata for npm publish\n        └── src/\n            └── index.ts      # CLI logic (e.g., `add` command)\n```\n\n### Publishing to npm\n\nTo publish the `@npui/cli` package to npm, you would navigate to the root of the monorepo and run:\n\n```bash\npnpm publish -r --filter=@npui/cli --access public\n```\n\nThis command tells `pnpm` to recursively publish packages, specifically filtering for the `@npui/cli` package, and setting its access to public.\n\n## 🗺️ Roadmap to a Design System\n\nOur goal is to evolve `npui` beyond a component library into a comprehensive design system. This journey involves integrating design principles, guidelines, and tooling to create a unified language for both designers and developers.\n\n### Phase 1: Foundations \u0026 Core Components (Current State \u0026 Near Future)\n\n*   **Establish Design Principles:** Define core values and principles that guide all design and development decisions (e.g., accessibility-first, performance, flexibility, consistency).\n*   **Refine Design Tokens:** Formalize and expand Tailwind CSS configuration into a robust set of design tokens (colors, typography, spacing, shadows, border-radius) that can be consumed by both code and design tools.\n*   **Expand Component Library:** Continue adding a wide range of high-quality, accessible, and customizable React components, covering more UI patterns and use cases.\n*   **Enhance Documentation:** Improve component documentation with clear usage guidelines, accessibility notes, and best practices.\n\n### Phase 2: Design Integration \u0026 Tooling\n\n*   **Design Kit Creation:** Develop and maintain design kits (e.g., Figma, Sketch libraries) that mirror the `npui` component library and design tokens, enabling designers to work with the same building blocks as developers.\n*   **Automated Token Sync:** Explore tools and processes to automatically sync design tokens between design tools and the codebase, ensuring consistency.\n*   **CLI Enhancements:** Extend the `npui` CLI to support scaffolding new components with predefined structures and potentially managing design tokens.\n*   **Usage Guidelines:** Create detailed guidelines for when and how to use each component, including content best practices, interaction patterns, and accessibility considerations.\n\n### Phase 3: Governance \u0026 Maturity\n\n*   **Contribution Model:** Establish a clear contribution model for both design and development, encouraging community involvement while maintaining quality and consistency.\n*   **Version Control \u0026 Release Strategy:** Implement a robust versioning and release strategy for the design system, ensuring backward compatibility and clear communication of changes.\n*   **Performance \u0026 Accessibility Audits:** Regularly conduct performance and accessibility audits to ensure the system remains high-quality and inclusive.\n*   **Community \u0026 Support:** Foster a strong community around `npui`, providing support channels and gathering feedback to drive continuous improvement.\n\nBy following this roadmap, `npui` aims to become an indispensable tool for building consistent, beautiful, and high-performing user interfaces.\n\n## 🤝 Contributing\n\nWe welcome contributions to `npui`! If you have ideas for new components, hooks, utilities, or improvements to existing ones, please feel free to:\n\n1.  **Fork** the repository.\n2.  **Create a new branch** for your feature or bug fix.\n3.  **Implement** your changes, ensuring they adhere to the existing code style and best practices.\n4.  **Write comprehensive documentation** (props, variants, code examples) for any new additions.\n5.  **Submit a pull request** with a clear description of your changes.\n\nFor detailed developer guidelines, refer to the `DEVELOPER.md` file in the repository.\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## ✉️ Contact\n\nFor collaborations, project inquiries, or just to say hello, feel free to reach out to **Mahdi Hazrati** or **Next Production Dev**:\n\n*   **Email:** mahdi@nextproduction.dev\n*   **Portfolio:** [https://nextproduction.dev](https://nextproduction.dev)\n*   **Telegram:** @TheMahdiHazrati\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextproduction%2Fnpui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnextproduction%2Fnpui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnextproduction%2Fnpui/lists"}