@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.

React TypeScript Support

When using these web components in React projects with TypeScript, you'll need to add type definitions to get proper IntelliSense and type checking for the custom elements.

Method 1: Using the provided template

Copy the templates/react-types.d.ts file to your React project (e.g., as src/types/lukso-components.d.ts):

import '@lukso/web-components'

// Dynamic type generation based on HTMLElementTagNameMap
type CamelToKebab<S extends string> = S extends `${infer T}${infer U}`
  ? U extends Uncapitalize<U>
    ? `${Lowercase<T>}${CamelToKebab<U>}`
    : `${Lowercase<T>}-${CamelToKebab<U>}`
  : S

type ComponentProps<T> = {
  [K in keyof T as T[K] extends (...args: unknown[]) => unknown
    ? never
    : K]: T[K]
}

type KebabHTMLAttributes<T> = {
  [K in keyof ComponentProps<T> as CamelToKebab<
    K & string
  >]?: ComponentProps<T>[K]
}

type ReactWebComponentProps<T> = T extends HTMLElement
  ? React.DetailedHTMLProps<React.HTMLAttributes<T>, T> & KebabHTMLAttributes<T>
  : never

type CustomElementsOnly = {
  [K in keyof HTMLElementTagNameMap as K extends `${string}-${string}`
    ? K
    : never]: HTMLElementTagNameMap[K]
}

type CustomElements = {
  [K in keyof CustomElementsOnly]: ReactWebComponentProps<CustomElementsOnly[K]>
}

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements extends CustomElements {}
  }
}

Method 2: Manual configuration

1. Ensure @lukso/web-components is imported to register the components
2. Add the type definitions file to your project
3. Make sure your tsconfig.json includes the type definition file

Once configured, you'll get full TypeScript support:

// Full IntelliSense for component properties
<lukso-profile
  profile-url="/path/to/image.jpg"
  has-identicon={true}
  size="large"
/>

Note: The type definitions automatically convert camelCase properties to kebab-case attributes as expected by React.

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';

Icons

We currently support custom icons and the one from Vuesax icon pack. They work almost the same but there is a difference is adding them to library:

Custom icons

They are added as Typescript files. Each icon needs to be wrapped in ts file and dynamic parts like stroke, fill, stroke-width needs to be replaced with placeholders. Icons needs to be registered in the icon index file.

Vuesax icons

Those icon take more modern approach. All it is needed that the svg files have to be placed in correct folder structure under src/components/lukso-icon/vuesax. Then component takes over all the parsing part to make them usable. Since we rely on Figma file the easiest is just to export the whole icon group and copy into the project.

Development workflow

Start the watch mode and Storybook preview

yarn dev

check for the issues after code changes

yarn lint
yarn test

Initial Setup

When cloning the repository for the first time, you'll need to run the build process to generate the package workspace:

# Install dependencies
yarn install

# Build the project (generates package/package.json)
yarn build

# Install dependencies again to register the workspace
yarn install

Note: The package/package.json file is generated dynamically during the build process and is not tracked in git. This prevents version conflicts in pull requests.

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