https://github.com/kstepien3/ng-zen
ng-zen is a versatile Angular library and CLI tool offering UI-kit Angular schematics for streamlined integration into projects. The tool is currently in the Alpha phase. ⚠️ See more info here https://github.com/Kordrad/ng-zen/issues/62
https://github.com/kstepien3/ng-zen
Last synced: 15 days ago
JSON representation
ng-zen is a versatile Angular library and CLI tool offering UI-kit Angular schematics for streamlined integration into projects. The tool is currently in the Alpha phase. ⚠️ See more info here https://github.com/Kordrad/ng-zen/issues/62
- Host: GitHub
- URL: https://github.com/kstepien3/ng-zen
- Owner: Kordrad
- License: bsd-2-clause
- Created: 2024-04-22T16:59:42.000Z (about 1 year ago)
- Default Branch: develop
- Last Pushed: 2024-09-15T02:54:41.000Z (9 months ago)
- Last Synced: 2024-10-04T03:11:27.023Z (8 months ago)
- Language: TypeScript
- Homepage:
- Size: 863 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-angular - ng-zen - A versatile Angular library and CLI tool offering UI-kit Angular schematics for streamlined integration into projects. The tool is currently in the Alpha phase. (Table of contents / Third Party Components)
- fucking-awesome-angular - ng-zen - A versatile Angular library and CLI tool offering UI-kit Angular schematics for streamlined integration into projects. The tool is currently in the Alpha phase. (Table of contents / Third Party Components)
README
# @ng-zen/cli
[](https://github.com/kstepien3/ng-zen/actions/workflows/ci.yml)
[](https://github.com/kstepien3/ng-zen/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@ng-zen/cli)
[](https://www.npmjs.com/package/@ng-zen/cli)
[](https://github.com/kstepien3/ng-zen/blob/master/LICENSE)
[](https://github.com/kstepien3/ng-zen)
[](https://kstepien3.github.io/ng-zen/)
Generate modern, customizable Angular UI components and elements directly into your project 🚀
Built with the best practices and developer experience in mind 💡
## Table of Contents
1. [Features](#features)
2. [Ideal for](#ideal-for)
3. [Quick Start](#quick-start)
4. [Installation](#installation)
5. [Usage](#usage)
6. [Why @ng-zen/cli?](#why-ng-zencli)
7. [Examples](#examples)
8. [Documentation](#documentation)
9. [Project Status](#project-status)
10. [Contributing](#contributing)
11. [License](#license)
12. [Author](#author)
13. [See also](#see-also)
14. [FAQ](#faq)
## Features
- 🧩 **Component Schematics:** Generates ready-to-use UI component code (`.ts`, `.html`, `.scss`).
- 🎨 **Fully Customizable:** Easily theme and modify components via CSS variables and editable SCSS.
- 📱 **Responsive Design:** Components designed to adapt across various screen sizes.
- 📚 **Comprehensive Documentation:** Includes Storybook examples, JSDoc annotations, and `README.md` per component.
- ✅ **Test Coverage:** Generated components include unit tests (`.spec.ts`).
- 🚀 **Modern Angular:** Leverages standalone components, `OnPush` change detection, signals, and current best practices.
- 🛠 **Extensible:** Planned support for generating directives, pipes, services, and more.
## Ideal for
- 🏢 **Enterprise UI Kits:** A great starting point for building consistent, internal component libraries.
- 📈 **Custom Projects:** Accelerates development when custom UI elements are needed, avoiding vendor lock-in.
- 👩💻 **Developers:** Speeds up UI creation and ensures adherence to modern Angular patterns.
## Quick Start
The easiest way to add `@ng-zen/cli` and its schematics to your project:
```bash
ng add @ng-zen/cli
```
This command installs the package and performs initial setup.
## Installation
Alternatively, you can install it manually:
```bash
# For the latest stable version
pnpm add -D @ng-zen/cli
# For the latest pre-release version (includes newest features/fixes)
pnpm add -D @ng-zen/cli@next
```
## Usage
### Generating Components
Use the Angular CLI schematic:
```bash
ng generate @ng-zen/cli:component
```
This interactive prompt guides you through selecting and configuring the desired component(s) 📊.
To see available options without running interactively:
```bash
ng generate @ng-zen/cli:component --help
```
### Future Generators
Support for generating other Angular building blocks is planned:
- 📝 Directives
- 💧 Pipes
- 🛠 Services
- ... and more!
## Why @ng-zen/cli?
Unlike pre-compiled UI libraries, `@ng-zen/cli`:
- **Generates Source Code:** You get actual, editable component code in your project, not opaque `` tags.
- **Full Control:** Modify the generated code and styles freely to perfectly match your application's needs.
- **Modern Foundation:** Built on current Angular features (standalone, signals, etc.).
- **Transparency:** Understand exactly how components work and evolve them with your project.
- **Developer Experience:** Focuses on ease of use, customization, and maintainability.
## Examples
Each generated component set includes:
- Angular component code (`.ts`, `.html`, `.scss`)
- Unit tests (`.spec.ts`)
- Storybook stories (`.stories.ts`) for visual development and documentation.
- An `index.ts` for easy exporting.
- A component-specific `README.md` (generated from a template).
## Documentation
- **Storybook:** The primary source for visual examples and interactive demos: [View Storybook Demo](https://kstepien3.github.io/ng-zen/)
- **JSDoc:** Code includes documentation comments.
- **READMEs:** Project-level (`README.md`, `DEVELOPMENT.md`, `CONTRIBUTING.md`) and component-level READMEs.
- **Changelog:** Automatically generated history of changes: [CHANGELOG.md](https://github.com/kstepien3/ng-zen/blob/master/CHANGELOG.md)
## Project Status
🚧 **Actively Developed** 🚧
- The core schematics and existing components are functional but continuously improved.
- New generators (directives, pipes, etc.) are planned.
- The `master` branch represents the latest **stable** release.
- The `next` branch contains **pre-release** versions with the newest features and fixes – use `@ng-zen/cli@next` to try them out.
Since the tool generates code directly into your project, you own and control that code. Updates to `@ng-zen/cli` itself primarily bring new generator features or improvements to the generation process, not breaking changes to already generated components.
## Contributing
Contributions are highly welcome! If you'd like to help improve `@ng-zen/cli`, please read our **[Contribution Guidelines (CONTRIBUTING.md)](https://github.com/kstepien3/ng-zen/blob/master/CONTRIBUTING.md)** for details on the workflow, commit message requirements, and setup. 🤝
## License
This project is licensed under the [BSD 2-Clause License](https://github.com/kstepien3/ng-zen/blob/master/LICENSE) 📜.
## Author
Maintained by Konrad Stępień.
- GitHub: [@kstepien3](https://github.com/kstepien3)
- LinkedIn: [Konrad Stępień](https://www.linkedin.com/in/konradstepien/) 👥
- Email: [[email protected]](mailto:[email protected]?subject=%5BNG-ZEN%5D%20Query) 📨
## See also
- [ngx-schematic-builder](https://github.com/kstepien3/ngx-schematic-builder) - A custom Angular builder for compiling and bundling Angular schematics.
## FAQ
### How do I customize a generated component?
Generated components reside entirely within your project's source code. You can directly edit the `.ts`, `.html`, and `.scss` files. Components are structured to use CSS variables and SCSS for easier theming and modification.