npm package: @felix-health/vue-components-vue3
Description: A vite based monorepo that contains all of Felix Health's vue components and documentation for those components. Currently supports Vue 3.
Latest version: 3.5.4

# Felix Health Vue Component Library

A vite based monorepo that contains all of Felix Health's vue components and documentation for those components. Currently supports Vue 3.

## To consume in a project

> Currently this project depends on TailwindCSS (and our Tailwind [design system](https://www.npmjs.com/package/@felix-health/felix-app-tailwind-design-system)). Ensure to install that within your project as a pre-requisite.

1. Install the package

```bash
npm i @felix-health/vue-components-vue3
```

2. Import the library css into your main css file:

```css
/* Vue 3 */
@import '@felix-health/vue-components-vue3/dist/style.css';
```

3. Import all of the components in your main js file:

```js
/* Vue 3 */
import * as FelixComponents from '@felix-health/vue-components-vue3';

// Global registration in your main.js/App.vue file
Object.entries(FelixComponents).forEach((name, component) => {
  Vue.component([name, component]);
});
```

⚠️ **Note:** if you want to support server rendering, there are some components that depend on objects like `document` or `window` that are not available on the server. If you want to use this in an SSR context, you may not be able to just import all components at once as per the above, but will have to identify those components and import them separately in a client only context.

## Project Structure

```
vue-components/
├── src/
│   ├── index.ts              # Main entry point (exports all components)
│   ├── components/            # All Vue components
│   │   └── ...
│   ├── assets/               # Styles, fonts, and static assets
│   ├── lib/                  # Utility functions and helpers
│   └── setupTests.ts         # Test configuration
├── dist/                     # Build output (generated)
├── .storybook/              # Storybook configuration
├── vite.config.ts           # Vite build configuration
├── vitest.config.ts         # Test configuration
├── tsconfig.json            # TypeScript configuration
├── package.json             # Package metadata and dependencies
└── README.md
```

## Project local setup

### Install dependencies

```bash
npm install
```

### Set up Git hooks (Husky)

After installing dependencies, set up the Git hooks for automated linting and formatting:

```bash
npm run prepare
```

This will configure Husky to run lint-staged on pre-commit, which automatically formats your staged files with Prettier.

### Building for production

```bash
npm run build
```

### Consuming locally in another project

**1. Build vue-components package**

```bash
## Build with hot reload
npm run build:watch
```

**2. Install package**

from either Charm or Lucky directory:
`npm i /[path-to-project]` (example npm i `../vue-components` if your folder is called "vue-components")

### Testing

We use [Vue Testing Library](https://testing-library.com/docs/vue-testing-library/intro) with [Vitest](https://vitest.dev/) for unit testing. To write a new test, add a `.spec.js` file next to the component file you're working in.

```bash
npm run test
```

### Format files

Files are automatically formatted on commit using `lint-staged` and `husky` (after running `npm run prepare`).

You can also manually format files:

```bash
# checks files for formatting issues
npm run format:check
```

```bash
# fixes formatting issues
npm run format:write
```

## Contributing

### Adding a net new component

There are a few choices to make when introducing a new component / making changes to an existing one. Follow these steps when deciding where to put your new component:

**1. Decide if the component is intended to be shared between applications**
Is the component considered a "building block" and intended to be shared between our applications? If not, consider adding your component directly in the application it's being used in instead of adding it to the library.

**2. Create new component**
Create component inside `src/components` in the directory that best suits it (or create a new directory)

**3. Write component documentation and tests**
Ensure you write a storybook story to document your new component or changes. More information on how to do this in the section below.

**4. Add component to the export files**
Once done, add the component to `src/index.ts` as an export.

### Component Documentation (Developing with Storybook)

Write [Storybook](https://storybook.js.org/) stories in component driven development and construct components that are loosely-coupled and reusable. Emphasize the separation of concerns among components while improving our documentation.

Get started easily with our **Plop** boilerplate templates.

1. Start Storybook
   - `npm run storybook`
2. Run `npm run plop` and select the right template based on the component you are working on.
3. Look for the newly created stories file in **Storybook** and develop your component by adding more stories to it.
4. Document your component as much as possible using **JSDocs** documentation comments. **Storybook** will automatically pick them and add them to the documentation.

#### Building for production

**Vue 3**
`npm run storybook:build`

To test the builds:
`npx http-server ./path/to/build`

### Tools for component development

If you are developing a component that manages lots of **variants**, [cva(class-variance-authority)](https://cva.style/docs) is available for you to use. Also, consider using [tailwind-merge](https://github.com/dcastil/tailwind-merge/blob/v2.5.4/docs/README.md) if you use cva by simply using the `cn`(short for className) utility function in `packages/vue-3/src/lib/utils.ts`. Checkout `AppButton` component for more details.

### Typescript support

Typescript support is only available for `vue-3`. If you are creating new components, please add it to both `index.js` and **`src/index.ts`** as `src/index.ts` is the main file to export typescript types.

## Publishing to npm

1. Head to https://github.com/Felix-Health/vue-components/actions
2. Run the "Publish Vue 3 Package to npm" workflow off the `main` branch