squirrel

The Squirrel component library is a comprehensive suite of feature-rich UI components that encapsulate the styling of the Pequity Squirrel Design System.

The library is built using Vue 3 and Tailwind CSS and is designed to be used in Vue 3 projects. Vite is used as the build tool for the library and Storybook is used for component development and documentation.

Installation and Usage

Install the package and its dependencies using pnpm:

pnpm i vue vue-router @pequity/squirrel @tanstack/vue-virtual @vuepic/vue-datepicker dayjs floating-vue lodash-es vue-currency-input [email protected]

Install Tailwind CSS:

pnpm i -D tailwindcss

Squirrel uses iconify-icon for icons.
In our consumer project, we need to tell Vue that <iconify-icon> is a web component.

Example of how to do this in a Vite project:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'iconify-icon',
        },
      },
    }),
  ],
});

Import the Squirrel CSS to your project's main.css file:

@import '@pequity/squirrel/assets/squirrel.css';

Add the "Inter" font to your project's index.html file:

<link rel="preconnect" href="https://rsms.me/" /><link rel="stylesheet" href="https://rsms.me/inter/inter.css" />

Use the Squirrel Tailwind configuration as a preset in your project's tailwind.config.js file:

import { squirrelTailwindConfig } from '@pequity/squirrel';

export default {
  presets: [squirrelTailwindConfig],
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx,mdx}',
    './node_modules/@pequity/squirrel/dist/**/*.{vue,js,ts,jsx,tsx,mdx}',
  ],
};

Import and use the components you need in your Vue 3 project:

<template>
  <PBtn type="secondary">Button</PBtn>
</template>

<script setup lang="ts">
  import { PBtn, PRingLoader } from '@pequity/squirrel';
</script>

If you are using Jest for unit testing, you will need to add the following to your Jest configuration:

{
  moduleNameMapper: {
    '^@pequity/squirrel$': '<rootDir>/node_modules/@pequity/squirrel/dist/cjs',
  }
}

Developing Squirrel components while working on a consumer project

When working on a consumer project that relies on Squirrel components and requires experimentation and adjustments, our goal is to promptly test changes without the need to edit the library directly within the node_modules folder or publish a new version of it. To facilitate this process, we can utilize Vite aliases and point the entry point of the library to the source code of the library that resides inside the squirrel directory within the Squirrel repo.

After we're happy with the changes, we can then commit them to the Squirrel repository and publish a new version.

Setting up Vite aliases for local development

First you'll need to have the Squirrel repository cloned to your local machine.

Then, in your consumer project's .env.local file, add an VUE_APP_SQUIRREL_LOCAL_PATH variable that points to the squirrel folder inside the Squirrel repository:

Make sure to replace /home/user/development/pequity/squirrel/squirrel with the actual path to the squirrel folder in your local Squirrel repository.

# Map squirrel path for local development - uncomment when you need to work on Squirrel components locally
# VUE_APP_SQUIRREL_LOCAL_PATH=/home/user/development/pequity/squirrel/squirrel

Finally, in your project's vite.config file, add the following:

Heads up! The vite.config.mts file of the pequity/frontendv2 already includes the following configuration.

import { defineConfig, searchForWorkspaceRoot } from 'vite';

const squirrelLocalPath = process.env.VUE_APP_SQUIRREL_LOCAL_PATH;

export default defineConfig({
  // Other Vite config options...
  resolve: {
    alias: {
      ...(squirrelLocalPath && {
        '@squirrel': squirrelLocalPath,
        '@pequity/squirrel': squirrelLocalPath,
      }),
    },
  },
  ...(squirrelLocalPath && {
    server: {
      fs: {
        allow: [searchForWorkspaceRoot(process.cwd()), squirrelLocalPath],
      },
    },
  }),
});

Now, when you want to work on Squirrel components, you can uncomment the VUE_APP_SQUIRREL_LOCAL_PATH in your .env.local file and restart the dev server.
The Squirrel components will be loaded from the local <squirrel_repo_path>/squirrel folder instead of the node_modules folder and HMR will work as expected.

Contributing

:fire: HEADS UP! This repo uses conventional commits and semantic-release to automate the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package to npm.
Commit messages have to follow the commit message format when contributing.

When adding a new component to the library, please make sure to add unit tests and Storybook stories for it.
We strive to maintain a high level of code quality and test coverage in this project.

Project setup for development

This project uses pnpm as the package manager.

Install dependencies

pnpm install

Start the dev server

pnpm run dev

Run Storybook

pnpm run storybook

Run Storybook tests

pnpm run test-storybook

Run unit tests

pnpm run test:unit

Lint files

pnpm run lint

Lint and fix files

pnpm run lint-fix

Run Typechecks

pnpm run typecheck