@lukso/web-components ·

Web Components library address issue of sharing same visual elements and basic style setup across different projects. It's based on following tools

• Tailwind CSS
• Lit
• Storybook

Please check the storybook preview page for full component list and basic styling.

Installation

In order to use library you need to install this as npm package

yarn add @lukso/web-components

Using the library

Library is focused around projects build on top of Tailwind CSS framework. It ships with bunch of components, presets for styles, typography and colors.

Components

For using components you need to first import them either as individual ones:

import('@lukso/web-components/components/dist/lukso-button')
import('@lukso/web-components/components/dist/lukso-card')
import('@lukso/web-components/components/dist/lukso-tag')

or all of them in single import:

import('@lukso/web-components')

Hint: you can make import in root level of your project (app.vue) instead of importing in every component.

Hint: In Frameworks that use SSR you need to import components only when window object is defined.

Use components in the HTML with following rules:

• components are lowercase and with - in name i.e lukso-button
• they need to have closing tag even if they don't use slot
• properties are lowercase and with - in name i.e primary-color="neutral-100"
• boolean properties are working with just a presence is-checked

See example below:

<lukso-example-component primary-color="neutral-100" is-checked></lukso-button>

Under the hood you use Web Components which styles are encapsulated within own shadow DOM (host page doesn't have access to it styles and vice versa). The only thing that components share from are fonts, colors and variables, see more on CSS inheritance.

Styles (Tailwind CSS projects)

1. Add this preset in the config file

// tailwind.config.js
module.exports = {
  presets: [require('@lukso/web-components/tailwind.config')],
  // ...
}

2. Include styles in your main file

// main.scss
$font-file-path: '/assets/fonts';

@import '@lukso/web-components/tools/sass/main.scss';

3. Add script to copy assets in your build config

In order to use other files like fonts or images from library we need to manually copy them to your project. This is ESM limitation that allow to import only js files.

import { copyAssets } from '@lukso/web-components/tools/copy-assets'
import assets from '@lukso/web-components/tools/assets'

copyAssets('./src', assets)

Place this at the top of your build file ie. vite.config.ts

Styles (non Tailwind CSS projects)

Atm the only thing that you can benefit from non Tailwind CSS projects is loading the fonts

// main.scss
$font-file-path: '/assets/fonts';

@import '@lukso/web-components/tools/sass/fonts.scss';

Development workflow

Start the watch mode and Storybook preview

yarn dev

check for the issues after code changes

yarn lint
yarn test

Releasing project

This repo uses Release Please to automate release process. It's important to follow Conventional Commits spec for naming Pull Requests. Once PR is merged into main the release PR will be created. When release PR is merged new package is released in npm.

Linking the library

For local development it's handy to link component library with the project you currently develop. This way you can work with components like in normal app. To make it work you need to first link the library:

yarn link -p ../tools-web-components

The only caveat with linking is that this will add resolution entry into package.json and package.lock` which shouldn't be committed. Make sure to revert this changes or run unlink command

yarn unlink ../tools-web-components