Component library for NeuRIS | π Demo | π¦ npm | π€ PrimeVue Docs
RUI UI contains three things:
- a theme for Vue 3 components from PrimeVue 4;
- custom components;
- a preset and plugin for Tailwind that sets some global styling and exposes the design tokens used by the theme, so you can build custom UI that looks consistent with the components.
Vue and PrimeVue are required for RIS UI to work (you'll see a warning about missing peer dependencies if you're trying to use RIS UI without them). Tailwind is optional. To get started, install:
# Vue and PrimeVue if you haven't installed them already. Tailwind is optional.
npm install vue primevue tailwindcss
# RIS UI
npm install @digitalservicebund/ris-ui
Note
If you're using Nuxt, follow the instructions for Nuxt below instead.
Import and apply the RIS UI theme, styling, and fonts where you set up your application (typically main.ts
):
// main.ts
import { createApp } from "vue";
import PrimeVue from "primevue/config";
+ import { RisUiTheme, RisUiLocale } from "@digitalservicebund/ris-ui/primevue";
+ import "@digitalservicebund/ris-ui/primevue/style.css";
+ import "@digitalservicebund/ris-ui/fonts.css";
const app = createApp().use(PrimeVue, {
+ unstyled: true,
+ pt: RisUiTheme,
+ locale: RisUiLocale.deDE
})
If using Nuxt, skip the Vue setup above.
Install the Nuxt PrimeVue module:
npm install @primevue/nuxt-module
Add the PrimeVue module and configure it in nuxt.config.ts
:
// nuxt.config.ts
export default defineNuxtConfig({
// your other configuration
modules: [
+ "@primevue/nuxt-module",
],
+ primevue: {
+ usePrimeVue: false, // configured in plugins/ris-ui.ts
+ },
})
Add a new Nuxt plugin to configure PrimeVue:
// plugins/ris-ui.ts
import { RisUiTheme } from "@digitalservicebund/ris-ui/primevue";
import PrimeVue from "primevue/config";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(PrimeVue, {
pt: RisUiTheme,
unstyled: true,
});
});
Finally, add the styles (e.g. assets/main.css
):
@import "@digitalservicebund/ris-ui/primevue/style.css";
@import "@digitalservicebund/ris-ui/fonts.css";
/* Your other CSS */
If not using Tailwind, you may also add these styles directly to the css
section of nuxt.config.ts
.
If you want, also install the Tailwind preset (for colors, spacings, etc.) and plugin (for typography classes, etc.):
// tailwind.config.js
+ import { RisUiPreset, RisUiPlugin } from "@digitalservicebund/ris-ui/tailwind";
export default {
+ presets: [RisUiPreset],
+ plugins: [RisUiPlugin],
// your other configuration
};
To avoid issues with conflicting @layer
directives, make sure to integrate the postcss-import
module in your PostCSS configuration:
See Adding custom styles - Tailwind CSS.
If you're using Nuxt, you may add the postcss-import
module to your nuxt.config.ts
file:
// nuxt.config.ts
postcss: {
plugins: {
+ "postcss-import": {},
tailwindcss: {},
autoprefixer: {},
},
},
To make changes to RIS UI, you'll need the current Node.js LTS along with npm installed on your machine.
To get started, first clone this repository:
git clone https://github.com/digitalservicebund/ris-ui.git
Then install dependencies:
npm install
# This will populate the public/fonts folder. See public/fonts/.gitkeep
# for more information.
npm run sync-fonts
You can now run a local preview to see any changes you make to the code:
npm run storybook
Check out package.json for additional scripts.
RIS UI uses the following tools:
- Storybook, a playground for previewing components and styling
- Tailwind for styling
- Vite as our dev server and bundler
- Unplugin Icons for providing SVG icons as components
- TypeScript
- ESLint and Prettier for code consistency
- Vitest as our test runner
You can find more in package.json, but the above are the ones you'll work with the most.
In terms of files and folders, you'll find:
Folder | Contents |
---|---|
(root) | General docs and configuration |
.github/ |
GitHub Actions configuration |
.storybook/ |
Storybook setup |
src/components |
Custom Vue components |
src/primevue |
The RIS UI preset for PrimeVue |
src/tailwind |
The RIS UI preset and plugin for Tailwind |
src/lib |
Internal tools and helpers |
If you're using VS Code with the official Tailwind extension, you can get autocompletions and more by adding this to your VS Code settings:
{
// other settings
"tailwindCSS.experimental.classRegex": ["tw`([^`]*)`"],
}
This will detect Tailwind CSS classes in template strings tagged with tw
such as:
import { tw } from "@/lib/tags";
const classes = tw`bg-blue-200 px-16`;
See tags.ts for more information.
Before making your first commit, you'll need some additional prerequisites installed. These help us with code consistency and quality:
- GitHub CLI: Used for checking the pipeline status before pushing
- jq: Used by our license check, which ensures all our dependencies use allowed licenses only
- Lefthook: Runs Git commit hooks
- Talisman: Validates you're not accidentially committing secrets
Once they're installed, run:
# In ./ris-ui
lefthook install
When you make a commit now, Lefthook will ensure your changes and commit message adhere to our coding guidelines:
- Code is formatted with Prettier
- ESLint passes without warnings
- The commit message follows the Conventional Commits specification. If you're making changes to a component, please use the component name as the scope (multiple scopes are allowed).
Keep in mind that your commit messages will be used for generating changelogs and inferring version numbers when making a release. If you made multiple changes, please consider squashing them to keep the history, as well as the changelogs, tidy and readable.
To release a new version, run the "Release to npm" action. This will:
- Build the project
- Publish the build to npm
- Create a Git tag and GitHub release
- Generate a changelog based on the commits since the last release
Releases are created automatically by semantic-release. Please refer to their documentation to learn more about how version numbers are inferred and how changelogs are created.
See CONTRIBUTING.md.