<tuix-webcomponents>

This webcomponent follows the open-wc recommendation.

Installation

npm i tuix-webcomponents

Usage

Webbundle version

Webbundle Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/[email protected]
Styles Link: https://tuix-webcomponents.s3.eu-central-1.amazonaws.com/[email protected]

React

The package ships generated @lit/react wrappers, one per element, so nothing has to be wrapped by hand. @lit/react is a peer dependency:

npm i tuix-webcomponents @lit/react

import 'tuix-webcomponents/dist/assets/tuix-styles.css';
import { TuixButton, TuixText } from 'tuix-webcomponents/react';
import { IconName, MainVariant, TextSize } from 'tuix-webcomponents';

function App() {
  return (
    <>
      <TuixText size={TextSize.XL}>Test text</TuixText>
      <TuixButton
        variant={MainVariant.PRIMARY}
        iconLeft={IconName.SAVE}
        onCustomClick={() => console.log('clicked')}
      >
        Save
      </TuixButton>
    </>
  );
}

The props are the element's own properties, so objects and arrays pass through untouched, and each custom event arrives as an on* prop. Because those properties are typed with the exported enums, pass MainVariant.PRIMARY rather than the string 'primary'.

The wrappers are generated by scripts/build-react.ts during npm run build and land in package-build/src/react; src/react/ is gitignored. Nothing about them is hand-kept: the generator reads src/, so every element with a @customElement decorator gets a wrapper, and every event it dispatches gets its on* prop, typed with the detail type written at the dispatch site.

Fonts

The components render in Rubik, served from the Tuix CDN. The design tokens stylesheet imports it, so import 'tuix-webcomponents/dist/assets/tuix-styles.css' is enough. To start the request earlier, add the link to the document head:

<link rel="preconnect" href="https://hccdn.tuix.ch" />
<link rel="stylesheet" href="https://hccdn.tuix.ch/rubik_d444e2375d.css" />

Repository setup

npm install          # the package
npm run docs:install # the documentation site, which is its own npm project

docs/ carries its own package.json and lockfile, so a root npm install does not reach it, and npm run docs:dev and npm run docs:build fail until docs:install has run once. scripts/build.sh runs it for the same reason before it builds the site in CI. Nothing else needs a second install: the package build and Storybook run off the root dependencies, and docs/ resolves lit and the component sources through them.

Documentation

The developer documentation site (Fumadocs, statically exported) lives in docs/ as its own npm project:

npm run docs:install # once, and whenever docs/package-lock.json changes
npm run docs:dev     # http://localhost:3000/en/developers
npm run docs:build   # static export into docs/dist

All three are npm --prefix docs, so the same commands run from inside docs/ do the same thing, with one difference: docs:install is npm ci, a clean install of exactly what docs/package-lock.json pins. Adding or bumping a dependency therefore means an npm install inside docs/, to write the lockfile that docs:install then reproduces.

It carries step-by-step integration guides for React/Next.js, Vue and Angular, and a page per component with live previews of every variant, in English and German. Pages are MDX files in docs/content/docs/ (*.mdx English, *.de.mdx German), ordered by meta.json and meta.de.json.

The site is public-facing: it shows and documents the components, and carries no contributor workflow. That lives here and in docs/src/modules/docs/README.md, which covers how the site is put together: content locations, the live previews, the framework selector and the locales.

Building the package

npm run build

writes package-build/, and npm run stage:package copies that into dist/, which is what npm publish ships (files: ["dist"]):

| Path | Entry point | | ----------------------------- | ------------------------------------------------------------------- | | dist/src/index.js + .d.ts | tuix-webcomponents, the custom elements | | dist/src/react/index.js | tuix-webcomponents/react, the wrappers | | dist/assets/tuix-styles.css | tuix-webcomponents/dist/assets/tuix-styles.css, the design tokens |

The two steps are separate on purpose: dist/ is also where the site is assembled, so the package build never writes it. Only the staging step does, and that runs in bin/publish.sh, i.e. in the publish job, after the site has already been uploaded from its own job.

The steps behind it: cem analyze refreshes custom-elements.json, scripts/build-react.ts regenerates src/react/, tsc -p tsconfig.publish.json compiles both entry points with their declarations, build:css renders the tokens, and tsc-esm-fix adds the .js extensions Node's ESM resolver needs.

Releases

Releases are automatic, from CircleCI. bin/publish.sh takes the newest feat(, feat!( or fix( subject out of the last ten commits and derives the version from it:

| Commit prefix | Bump | | ------------- | ----- | | feat!( | major | | feat( | minor | | anything else | patch |

Commit subjects are linted by commitlint against Conventional Commits, so the prefix is not optional.

The branch decides the dist-tag, and the two paths differ:

| Branch | Dist-tag | Version | Also does | | ------------ | --------- | --------------------------------------------- | --------------------------------------------------------------------------- | | master | latest | bumped from the commit subject, per the table | uploads the web bundle to S3, rewrites the two links below, tags v<version> | | anything else| staging | always a patch bump off staging | uploads the web bundle to S3 |

Both paths build the bundle as build-<short hash>@<version>.{js,css} and upload it, so every deployment is immutable. Only latest rewrites the Webbundle Link: and Styles Link: lines under Usage and commits them, which is why those two lines are the one place in the repository that tracks the current bundle. docs/scripts/build-bundle-links.ts reads them at docs build time rather than copying the URLs into a page, so the documentation cannot fall a release behind.

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Demoing with Storybook

To run a local instance of Storybook for your component, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

That writes dist/storybook, which is where the deployed site serves it from. The site root is the documentation, and the Storybook sidebar brand links back to it. scripts/build.sh is what assembles both into dist/ for CI.

Two builds, two folders, so neither clears the other: the site into dist/ (scripts/build.sh: Storybook under dist/storybook, the docs export at the root) and the npm package into package-build/ (npm run build). dist/ is reused for the package only by npm run stage:package, which bin/publish.sh runs in the publish job.

Tooling configs

For most of the tools, the configuration is in the package.json to reduce the amount of files in your project.

If you customize the configuration a lot, you can consider moving them to individual files.