@felix-health/vue-components-vue3

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). Ensure to install that within your project as a pre-requisite.

1. Install the package

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

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

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

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

/* 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

npm install

Set up Git hooks (Husky)

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

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

npm run build

Consuming locally in another project

1. Build vue-components package

## 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 with Vitest for unit testing. To write a new test, add a .spec.js file next to the component file you're working in.

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:

# checks files for formatting issues
npm run format:check

# fixes formatting issues
npm run format:write

If you get an error about dependency being too new

You can bypass the minimum release age requirement this way:

npm config set min-release-age 0
npm install <package-name>
# Then set it back
npm config set min-release-age <original value in .npmrc>

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 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) is available for you to use. Also, consider using tailwind-merge 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