@dpa-id-components/dpa-shared-components NPM

DPA shared components library

Collection of vue 3 components for usage across dpa projects.

Pre-requirements

This project requires a node version of 16.x or higher. For Node environments such as nuxt.js Node v20 or higher is required to prevent errors from the missing crypto library, which is needed for uuid.

You need to add and integrate the Inter font that can be found in src/assets/fonts to your project manually. An example how the CSS could look can be found in src/tailwind/fonts.css

Notes

This project uses Typescript version >= 5.0. This upgrade included changes to the module resolution, which are not yet reflected fully in the tsconfig. If your project uses TS 5.0 or higher itself you most likely need to set

"resolvePackageJsonExports": false

to prevent transpiler errors. For more information see the migration guide of ts.

Usage

To use a component just import it from @dpa-id-components/dpa-shared-components like

import { UiBadge } from "@dpa-id-components/dpa-shared-components";

Tailwind

To have the styling working correctly you have to extend the tailwind config in your project.

Please ensure that the version of Tailwind in your host application meets the version specified under peerDependencies in package.json.

import sharedComponentsConfig from '@dpa-id-components/dpa-shared-components/tailwindConfig'
import { Config } from 'tailwindcss'

export default {
  presets: [sharedComponentsConfig],
  content: [
    // ... your content globs ...
    './node_modules/@dpa-id-components/dpa-shared-components/**/*.{js,mjs,cjs}'
  ]
}
satisfies
Config

The tailwind config is located at ./src/tailwind/tailwind.config.ts. Please be aware that used plugins must be listed in the dependencies or the projects using the components have to install it.

ESLint

As of version 11.x.x, this project is setup to use ESLint 9+ which no longer supports the .eslintrc configuration format. The ESLint flat configuration file for this project is located at ./eslint.config.mjs. The base ESLint configuration ./eslint.base.config.mjs is exported in the published npm package as a shareable config file and can be used as the base configuration for host projects. Plugins and third party configs used in ./eslint.base.config.mjs should be added to dependencies in package.json.

Please note the following when configuring the eslint.config.mjs file in a host project:

Project specific third-party plugins and config (updated accordingly for flat config support) should be added as devDependencies
Files to be included or ignored by ESLint should be configured here
Adjust the lint script in package.json to "lint": "eslint . --fix"

To use the shared ESLint config in a host project's eslint.config.mjs:

import sharedConfig from "@dpa-id-components/dpa-shared-components/eslint.config";
// Other project specific plugins
import pluginCypress from "eslint-plugin-cypress/flat";

export default [
  // Files to include or ignore under linting
  {
    files: ["**/*.js", "**/*.mjs", "**/*.ts", "**/*.mts", "**/*.vue"],
  },
  {
    ignores: ["_infrastructure/*", "**/dist/**", "**/coverage/**"],
  },
  ...sharedConfig,
  pluginCypress.configs.recommended,
];

Add a component

To add a new component please add at least the following files:

Readme.md
Component.spec.ts
Component.stories.js
Component.vue

The readme should contain a minimal explanation of the usage and a definition of the api of the component (props, events, slots...). Also don't forget to add an import/export in ./src/components/index.ts to make your component available.

Tests

Tests are based on vitest and Vue Test Utils 2 running in a jsdom environment. To run the tests run

npm run test

The tests automatically are run as a watch task.

Storybook

This project runs on a 6.5 version of Storybook with a vite integration. If you want to change the vite config for storybook, please be aware that storybook overwrites the plugin section of the config in ./.storybook/main.ts, since storybook can't handle the vue plugin.

To start storybook locally run

npm run storybook

A deployed version of the storybook can be found here.

Link the project locally

For a better developer experience and testing in your actual it's recommended to link the package locally. For that run

npm link

in the root of your cloned shared components and

npm link "@dpa-id-components/dpa-shared-components"

in your target project.

Don't forget to run

npm run build

before linking or otherwise you wouldn't have a dist folder.

If linking doesn't seem to work, you can try to clear your vite-cache by deleting the node_modules/.vite folder

SVG icons

To add SVG icons, just copy the .svg file to ./src/assets/icons. Preferably you add the filename also to the ìconNames.ts so it's available in Storybook as option and in the overview. SVGs get loaded by vite-svg-loader, which optimizes the SVGs with svgo. Config can be added in vite.config.ts and ./.storybook/main.ts ( duplicated since Storybook can't handle the vite config plugins). Custom optimizations right now are:

removing dimensions (width/height attributes)
removing fills (to enable styling)

Releasing

To publish a new release just go to the Actions tab and click "Publish new version". You are prompted with the option to choose which version to bump. Behind the scenes it just does one of those commands below. They will still work on their own but the #shared-components Slack channel won't be notified.