Squirrel component library
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.
Install the package and its dependencies using pnpm:
``bash`
pnpm i vue vue-i18n vue-router @pequity/squirrel @tanstack/vue-virtual @vuepic/vue-datepicker floating-vue iconify-icon lodash-es vue-currency-input vue-toastification@2.0.0-rc.5
Squirrel requires vue-i18n (already included in the dependency list above). You'll need to install the Squirrel plugin to integrate Squirrel's translations with your i18n instance:
`js
import { createApp } from 'vue';
import { SquirrelPlugin } from '@pequity/squirrel';
const app = createApp(App);
// Install your i18n instance
app.use(i18n);
// Install Squirrel plugin with your i18n instance
app.use(SquirrelPlugin, i18n);
app.mount('#app');
`
Install Tailwind CSS:
`bash`
pnpm i -D tailwindcss
Squirrel uses iconify-icon for icons.
In our consumer project, we need to tell Vue that is a web component.
Example of how to do this in a Vite project:
`js
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:
`css`
@import '@pequity/squirrel/assets/squirrel.css';
Add the "Inter" font to your project's index.html file:
`html`
Use the Squirrel Tailwind configuration as a preset in your project's tailwind.config.js file:
`js
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:
`html
`
If you are using Jest for unit testing, you will need to add the following to your Jest configuration:
`js`
{
moduleNameMapper: {
'^@pequity/squirrel$': '
}
}
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.
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.
`bash`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.ts file of the pequity/frontendv2 already includes the following configuration.
`js
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 folder instead of the node_modules folder and HMR will work as expected.
For optimal development experience, you can use the following VSCode configuration. Add these settings to your .vscode/settings.json file:
`json][^\"'
{
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
},
"[html]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"tailwindCSS.experimental.classRegex": [["([\"'].?[\"'])", "]" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">\"'.?[\"']"]]`
}
This configuration enables:
- Automatic formatting on save using Prettier
- ESLint auto-fixing on save
- Tailwind CSS autocompletion for Tailwind Variants
---
: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 conventional 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.
All components must be documented with comprehensive JSDoc comments following the vue-component-meta standards.
We strive to maintain a high level of code quality, test coverage, and documentation in this project.
This project uses pnpm as the package manager.
`bash`
pnpm install
`bash`
pnpm run dev
`bash`
pnpm run storybook
`bash`
pnpm run test-storybook
`bash`
pnpm run test:unit
`bash`
pnpm run lint
`bash`
pnpm run lint-fix
`bash``
pnpm run typecheck