Skip to main content

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.

Shared library vs. extension

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-next with its cn() helper and design tokens.
  • Storybook 10 (Vite): preview and document each component in isolation.
  • Jest + Testing Library: unit tests with the shared @invent/jest-config preset.
  • Linting and formatting: ESLint, Stylelint, and Prettier via @invent/wl-linters, enforced on every commit by a husky pre-commit hook.

Prerequisites​

RequirementNotes
Node.js18 or newer
GitLab accessA 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​

Let Claude do it

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.

  1. Create a project from the template. In GitLab, choose New project → Create from template, or clone the template and re-point the remote.

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

  3. Install and start Storybook to confirm the example component renders:

    npm install
    npm 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
The export rule

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​

ScriptWhat it does
npm run storybookRun Storybook on port 6006
npm run build-storybookBuild a static Storybook
npm testRun the Jest suite
npm run buildType-check and emit the package to build/
npm run typecheckType-check only
npm run lint / npm run lint:cssESLint / Stylelint
npm run formatFormat 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:

CommitRelease
feat: add GreetingCardminor (1.1.0 → 1.2.0)
fix: correct card paddingpatch (1.1.0 → 1.1.1)
docs:, refactor:, style:, perf:, build:, ci:, test:patch
feat!: or a BREAKING CHANGE: footermajor (1.1.0 → 2.0.0)

Other types, such as chore:, produce no release.

  • Merge to master: CI computes the next version, updates CHANGELOG.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-next setup (any widget scaffolded from the current template already has this)
  • the library's other peer dependencies installed: @invent/tailwind-integration, react-query, and react-use

Conventions​

  • One entity per file or folder, and every folder has an index.ts barrel.
  • Export types with export type.
  • Every component ships a *.stories.tsx with 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​