Creating a Shared Library
If you build more than one widget, you'll end up with components, hooks, and utils you want in all of them. Instead of copy-pasting code between projects, put it in a shared library: one versioned, tested, documented npm package that every one of your widgets installs.
Invent provides a template for this: invent/frontend/templates/shared-components. It comes wired with the same stack your widgets use, so a component that works in the library works in your widget.
A shared library is a build-time dependency: each widget installs it and bundles what it imports. If you need a single runtime service instance shared by the host and every widget (no UI, loaded once after login), you want a platform extension instead.
What the template gives you
- A publishable package: versioned automatically with semantic-release and published to the Invent GitLab npm registry when you merge to
master. - The widget UI stack: React 18 + TypeScript 5 + Tailwind v4, built on
@invent/wl-ui-kit-nextwith itscn()helper and design tokens. - Storybook 10 (Vite): preview and document each component in isolation.
- Jest + Testing Library: unit tests with the shared
@invent/jest-configpreset. - Linting and formatting: ESLint, Stylelint, and Prettier via
@invent/wl-linters, enforced on every commit by a huskypre-commithook.
Prerequisites
| Requirement | Notes |
|---|---|
| Node.js | 18 or newer |
| GitLab access | A gitlab.apptrium.io account with a token that can read the npm registry |
@invent/* packages live on the private GitLab npm registry. The template's .npmrc already points the @invent scope there; you only need a token in your user ~/.npmrc:
# ~/.npmrc
//gitlab.apptrium.io/api/v4/packages/npm/:_authToken=<YOUR_GITLAB_TOKEN>
Create the token in GitLab under User Settings → Access Tokens with the read_api scope. Check it works:
npm view @invent/wl-ui-kit-next version
Setting up your library
The create-shared-library skill does every step below for you: it creates the project in your group, renames the package, verifies it, and publishes 1.0.0. The steps here are what it automates.
-
Create a project from the template. In GitLab, choose New project → Create from template, or clone the template and re-point the remote.
-
Rename the package in
package.json. Prefix it with your vendor name so it doesn't collide with other libraries:{"name": "@invent/acme-shared-components"}Don't skip this. A library left with the template's name,
@invent/shared-components-template, publishes under that name and collides with every other library that did the same. -
Install and start Storybook to confirm the example component renders:
npm installnpm run storybook # http://localhost:6006
You're ready to replace example-component with your own.
Project structure
.
├── index.ts # the package's public API, re-exports src/
├── src/
│ ├── index.ts # barrel for everything under src/
│ ├── global.css # Tailwind entry (Storybook / local dev only)
│ ├── components/
│ │ ├── index.ts # barrel for all components
│ │ └── example-component/ # one folder per component
│ │ ├── example-component.tsx
│ │ ├── example-component.stories.tsx
│ │ ├── example-component.spec.tsx
│ │ └── index.ts
│ └── utils/ # hooks, helpers, pure functions
│ ├── index.ts
│ ├── util-name.ts
│ └── util-name.spec.ts
├── .storybook/ # Storybook (Vite) config
└── package.json
Anything consumers should import must be re-exported all the way up to the top-level index.ts. The barrels use named exports (not export *), so a new component or util is not public until it is listed in all three: src/components/index.ts (or src/utils/index.ts), src/index.ts, and the top-level index.ts. If you miss the top-level one, consumers get Module has no exported member.
Adding a component
Create a folder under src/components/<your-component>/ with the component, its story, its test, and an index.ts barrel:
// src/components/greeting-card/greeting-card.tsx
import React, { ReactNode } from 'react';
import { cn } from '@invent/wl-ui-kit-next';
export type GreetingCardProps = {
title: ReactNode;
children: ReactNode;
};
export function GreetingCard({ title, children }: GreetingCardProps): JSX.Element {
return (
<div className={cn('flex flex-col gap-2 rounded-lg p-4', 'bg-card text-card-foreground')}>
<h3 className="text-heading3">{title}</h3>
<p className="text-body2">{children}</p>
</div>
);
}
// src/components/greeting-card/index.ts
export { GreetingCard } from './greeting-card';
export type { GreetingCardProps } from './greeting-card';
Then re-export it up the chain, in all three barrels:
// src/components/index.ts
export { GreetingCard, type GreetingCardProps } from './greeting-card';
// src/index.ts
export { GreetingCard, type GreetingCardProps } from './components';
// index.ts (top level, the package's public API)
export { GreetingCard } from './src';
export type { GreetingCardProps } from './src';
Hooks and utils follow the same pattern under src/utils/: export from src/utils/index.ts, then src/index.ts, then the top-level index.ts.
Style with Tailwind utilities, cn(), and design tokens (bg-card, text-muted-foreground, text-heading3) rather than raw colors or pixel values, and compose from kit primitives (Button, Dialog, Input, typography) where they exist. See Using the Component Library for what the kit provides.
Scripts
| Script | What it does |
|---|---|
npm run storybook | Run Storybook on port 6006 |
npm run build-storybook | Build a static Storybook |
npm test | Run the Jest suite |
npm run build | Type-check and emit the package to build/ |
npm run typecheck | Type-check only |
npm run lint / npm run lint:css | ESLint / Stylelint |
npm run format | Format with Prettier |
Publishing and versioning
You never bump the version or edit CHANGELOG.md by hand. Releases are cut by semantic-release in CI, and your commit messages decide the version:
| Commit | Release |
|---|---|
feat: add GreetingCard | minor (1.1.0 → 1.2.0) |
fix: correct card padding | patch (1.1.0 → 1.1.1) |
docs:, refactor:, style:, perf:, build:, ci:, test: | patch |
feat!: or a BREAKING CHANGE: footer | major (1.1.0 → 2.0.0) |
Other types, such as chore:, produce no release.
- Merge to
master: CI computes the next version, updatesCHANGELOG.md, tags the release, and publishes to the Invent npm registry. - Feature branches: publish prereleases tagged with the branch name, so you can install and test a build in a widget before merging.
For background on how semantic-release works across Invent packages, see NPM Packages Versioning.
Using your library in a widget
Install it like any other @invent package:
npm install @invent/acme-shared-components
import { GreetingCard } from '@invent/acme-shared-components';
The consuming widget needs:
- the same registry token in
~/.npmrc - React 18+ with the Tailwind v4 /
@invent/wl-ui-kit-nextsetup (any widget scaffolded from the current template already has this) - the library's other peer dependencies installed:
@invent/tailwind-integration,react-query, andreact-use
Conventions
- One entity per file or folder, and every folder has an
index.tsbarrel. - Export types with
export type. - Every component ships a
*.stories.tsxwith at least a minimal showcase, and a co-located*.spec.tsx. - File names are kebab-case (
greeting-card.tsx). - Expose the public API only through the top-level
index.ts. - Style with Tailwind,
cn(), and design tokens; no hardcoded colors or sizes. - Don't bypass the pre-commit hook with
--no-verify.
Where to go next
- Scaffold or validate a library with Claude → Creating a Shared Library (
create-shared-libraryskill) - Full template reference → the template's README
- What the UI kit provides → Using the Component Library
- Release mechanics → NPM Packages Versioning
- Runtime shared services → Extensions