npm package: @selfeesas/shared-components
Description: A component library for sharing UI components across Selfeesas company projects. Built on Vue 3 and Quasar, optimized for Vite.
Latest version: 1.5.1

# 🧩 @selfeesas/shared-components

A component library for sharing UI components across Selfeesas company projects. Built on Vue 3 and Quasar, optimized for Vite.

[![npm](https://img.shields.io/npm/v/@selfeesas/shared-components)](https://www.npmjs.com/package/@selfeesas/shared-components)  
[![Storybook](https://img.shields.io/badge/Storybook-online-blue?logo=storybook)](https://selfeesas.github.io/SharedUI)

---

## 🚀 Features

- 🔁 Reusable components for multiple projects
- ⚡ Built on Vue 3 + Quasar + Vite
- 📚 Storybook for visual documentation
- 🎯 TypeScript support
- ✅ Installable via npm
- 🔧 Automated CI/CD, including Semantic Release, SonarCloud, and Storybook GH Pages

---

## 📦 Installation

```bash
npm install @selfeesas/shared-components
# or
yarn add @selfeesas/shared-components
```

> Ensure that `vue`, `vue-router`, and `quasar` are already installed in your project.

---

## ⚙️ Requirements

| Package    | Version   |
| ---------- | --------- |
| Vue        | `^3.5.16` |
| Vue Router | `^4.5.1`  |
| Quasar     | `^2.18.1` |

---

## 🔧 Usage

```ts
import { SharedButton } from '@selfeesas/shared-components'
```

Now you can use the components in your Vue templates:

```vue
<template>
  <SharedButton label="Click me" />
</template>
```

⚠️ Important: To ensure components render correctly, you must import the styles.
Add the following import in your project's root file (e.g., main.ts or main.js):

```bash
import "@selfeesas/shared-components/dist/assets/shared-components.css";
```

---

## 🧱 Available Components

> Examples are available in Storybook:  
> 🔗 [https://selfeesas.github.io/SharedUI](https://selfeesas.github.io/SharedUI)

- `NavButton`
- `CustomTable`
- `SelectSearch`
- `DatePicker`
- and more...

---

## 📖 Storybook

📘 [Open Storybook](https://selfeesas.github.io/SharedUI)

Run locally:

```bash
npm run storybook
```

Build:

```bash
npm run build-storybook
```

---

## 🚨 Linting and Formatting

```bash
npm run lint       # Run ESLint checks
npm run lint:fix   # Fix ESLint errors
npm run format     # Run Prettier + ESLint fix
```

---

## 🔁 CI/CD and Automation

- **GitHub Actions**: Linting, building, and deploying Storybook
- **Semantic Release**: Automated version releases
- **SonarCloud**: Static code analysis

---

## 🧑‍💻 Developer Guide

### CI/CD Pipeline Overview

The CI/CD pipeline is defined in `.github/workflows/main.yml` and automates linting, building, testing, versioning, and deployment. It uses GitHub Actions and is triggered on:

- **Pushes** to the `main` branch
- **Pull requests** targeting the `main` branch
- **Releases** created in the repository

#### Pipeline Jobs

1. **Lint and Build**:
   - Checks out the code and sets up Node.js (v20).
   - Installs dependencies with `npm ci`.
   - Runs ESLint with `npm run lint -- --max-warnings=0` to enforce code quality.
   - Builds the package with `npm run build`.

2. **Semantic Release** (runs only on `main` branch):
   - Uses `cycjimmy/semantic-release-action` to automate versioning and releases.
   - Analyzes commit messages following the **Conventional Commits** format:
     - `fix`: Patches (e.g., `1.0.1`)
     - `feat`: Minor updates (e.g., `1.1.0`)
     - `BREAKING CHANGE`: Major updates (e.g., `2.0.0`)
   - Automatically updates the version in `package.json`.
   - Generates or updates the `CHANGELOG.md` based on commit messages.
   - Publishes the package to npm using the `NPM_TOKEN`.
   - Creates a GitHub release with the new version.

3. **Deploy Storybook** (runs only on `main` branch):
   - Builds Storybook with `npx storybook build`.
   - Deploys the static Storybook site to GitHub Pages using `peaceiris/actions-gh-pages`.

4. **SonarCloud**:
   - Runs static code analysis with SonarCloud to detect bugs, vulnerabilities, and code smells.
   - Requires `SONAR_TOKEN` for authentication.

#### How to Work with the Pipeline

- **Commit Messages**: Use Conventional Commits to ensure Semantic Release works correctly. See the [Conventional Commits](#conventional-commits) section below for details.
- **Local Testing**: Before pushing, run `npm run lint`, `npm run build`, and `npm run storybook` locally to catch issues early.
- **Changelog**: The `CHANGELOG.md` is auto-generated by Semantic Release. Do not edit it manually.
- **Storybook Deployment**: Updates to Storybook are automatically deployed to [https://selfeesas.github.io/SharedUI](https://selfeesas.github.io/SharedUI) on `main` branch pushes.

#### Troubleshooting

- **Pipeline Fails on Lint**: Run `npm run lint:fix` locally and commit fixes.
- **Semantic Release Skips Versioning**: Ensure commit messages follow Conventional Commits. Check the pipeline logs for details.
- **Storybook Deployment Fails**: Verify the `storybook-static` directory is generated correctly with `npm run build-storybook`.
- **SonarCloud Issues**: Check SonarCloud logs for specific issues and ensure `SONAR_TOKEN` is valid.

### Conventional Commits

To ensure proper versioning and changelog generation, all commits must follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/). This standardizes commit messages to make them machine-readable for Semantic Release.

#### Commit Message Structure

A commit message consists of a **type**, optional **scope**, optional **!** for breaking changes, and a **description**. The format is:

```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```

- **type**: Indicates the nature of the change (e.g., `fix`, `feat`, `docs`, `style`, `refactor`, `test`, `chore`).
- **scope**: Specifies the part of the codebase affected (e.g., `SharedButton`, `SharedModal`).
- **!**: Denotes a breaking change (triggers a major version bump).
- **description**: A concise summary of the change.
- **body**: Additional context (optional).
- **footer**: Metadata like `BREAKING CHANGE:` or issue references (optional).

#### Examples

- **Fix (Patch Release)**:

  ```
  fix(SharedButton): resolve alignment issue in dark mode
  ```

  - Triggers a patch release (e.g., `1.0.0` → `1.0.1`).

- **Feature (Minor Release)**:

  ```
  feat(SharedDropdown): add support for multi-select
  ```

  - Triggers a minor release (e.g., `1.0.0` → `1.1.0`).

- **Breaking Change (Major Release)**:

  ```
  feat(SharedModal): add new props for customization
  BREAKING CHANGE: removed deprecated `size` prop
  ```

  - Triggers a major release (e.g., `1.0.0` → `2.0.0`).

- **Documentation Update**:

  ```
  docs(readme): update installation instructions
  ```

  - Does not trigger a release but updates the changelog.

- **Scoped Chore**:

  ```
  chore(deps): update Quasar to 2.18.1
  ```

  - Does not trigger a release but is included in the changelog.

#### Best Practices

- Keep descriptions concise and meaningful.
- Use the `!` or `BREAKING CHANGE:` footer for any change that requires users to update their code.
- Include a scope when possible to clarify the affected component or module.
- Avoid generic messages like `fix: bug`—be specific about the change.
- Run `git commit -m "type(scope): description"` or use a tool like [Commitizen](https://github.com/commitizen/cz-cli) for guided commit messages.

For full details, refer to the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/).

---

## 📄 License

MIT © Selfeesas

---

## 🧬 Repository

[https://github.com/selfeesas/SharedUI](https://github.com/selfeesas/SharedUI)