@uselagoon/ui-library

A component library based on Shadcn and Tailwind for all things Lagoon related.

ChangeFeed Component

The ChangeFeed component supports dynamic content updates via a GitHub action workflow. This allows for updates via Pull Requests without needing a full release of the ui-library.

Component Usage

Use ChangeFeedContainer to fetch data at runtime:

import { ChangeFeedContainer } from '@uselagoon/ui-library';

export default function ChangeFeed() {
  return (
    <ChangeFeedContainer 
      sourceData="https://raw.githubusercontent.com/your-org/main-app/main/public/data/changefeed.json"
      refetchInterval={600000}
    />
  );
}

Installation 💾

1. Configure npm registry

Create or update .npmrc in your project root:

@uselagoon:registry=https://registry.npmjs.org

2. Install the package

npm install @uselagoon/ui-library tailwindcss @tailwindcss/postcss postcss

Or with yarn:

yarn add @uselagoon/ui-library tailwindcss @tailwindcss/postcss postcss

3. Import styles

Add the UI library styles to your root layout:

import '@uselagoon/ui-library/dist/ui-library.css';

Usage 🔨

Using a component from the library:

import '@uselagoon/ui-library/dist/ui-library.css';
import { Button, SwitchWithDescription } from '@uselagoon/ui-library';


export default () => (
  <>
    <Button variant="ghost" disabled>A spooky disabled button</Button>
    <SwitchWithDescription
      description="This is a switch description."
      id="first"
      label="Switch Text"
    />
  </>
);

Storybook 🎨

View the component documentation on Chromatic (URL available after setup).

Storybook Composition

To include UI library stories in your project's Storybook, add to your .storybook/main.ts:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  // ... your existing config
  refs: {
    'ui-library': {
      title: 'Lagoon UI Library',
      url: 'https://<branch>--<app-id>.chromatic.com/', // Get URL from Chromatic dashboard
    },
  },
};

export default config;

CI/CD

Automated Workflows

Workflow	Trigger	Actions
CI	Push to main, PRs	Type check, lint, format check, build, build Storybook
Publish	GitHub Release published	All CI checks + publish to NPM
Chromatic	Push to main, PRs	Deploy Storybook to Chromatic (when token configured)

Publishing a New Version

1. Update version in package.json
2. Commit and push to main
3. Create a GitHub Release with a new tag (e.g., v2.1.0)
4. The publish workflow automatically builds and publishes to NPM

Development guide 🏗️

Clone the repo locally:

git clone https://github.com/uselagoon/ui-library.git
cd ui-library
npm install
npm run storybook

It is recommended to build components in isolation with the help of storybook (currently V 9.0).

Open your browser and visit http://localhost:6006.

The project structure is as follows:

├── src │ ├── components # React source code and demos (which then get bundled) │ ├── hooks # Custom hooks │ ├── providers # Custom theme and NextLink providers │ ├── stories # Storybook stories │ ├── index.css # Autogenerated tailwind css file │ └── index.ts # Entrypoint for your exported components (that your project then imports) ├── eslint.config.js # Eslint config ├── vite.config.ts # Vite bundler config └── package.json

Given that there's a storybook instance running, navigate to the src directory and modify/create new components with their respective stories.tsx files.

Modify and customize anything with Tailwind and/or custom css files if needed.

Then run the lint and format scripts, and you're ready to go!

npm run typecheck    # TypeScript check
npm run lint         # ESLint
npm run format       # Prettier formatting

Adding Shadcn Components

To add a new component from Shadcn, refer to the Shadcn CLI guide.

Contributing 🤝

PRs and issues are welcome, we invite contributions from everyone.

This guide could come in handy: GitHub contribution guide