UI-Chakra

This is the foundational UI component library, built on top of Chakra UI.

It exports a theme for @chakra-ui/react, composite components that address common requirements in BurnsRED projects. Components which have third-party dependencies are defined in their own package.

To develop, fire up @burnsred/styleguide, and consume the UI library from there.

Installing in a client project

npm i @burnsred/engage-ui

Installing fonts

npm install @fontsource/open-sans @fontsource/montserrat

Include fonts:

// src/App.tsx

// whichever weights required
import '@fontsource/montserrat/700.css';
import '@fontsource/open-sans/400.css';

Configure the theme:

// src/theme/index.ts
export const theme: Partial<ChakraTheme> = extendTheme({
  // ...

  fonts: {
    heading: `'Montserrat', sans-serif`,
    body: `'Open Sans', sans-serif`,
  },

  // ...
});

Optional dependencies

# recommended - tree-shakable, includes Material icons and many more
# https://react-icons.github.io/react-icons/
npm i react-icons

Developing

npm -w @burnsred/ui-chakra run dev
npm -w @burnsred/ui-chakra run test
npm -w @burnsred/ui-chakra run build

Note that whilst we're building the library with the Typescript compiler, vite is installed to facilitate testing via vitest, which is configured via tsconfig.node.json.

Gotcha: consuming local engage-ui in client projects

When actively developing engage-ui and testing consumption in a client project, the development cycle may look like this:

• update code in engage-ui
  • npm run clean && npm run build
• consume the functionality in the client project
  • rm -rf node_modules/@burnsred && npm i && npm run dev

GOTCHA in development (only), vite pre-bundles dependencies:

Vite converts ESM dependencies with many internal modules into a single module to improve subsequent page load performance

https://vitejs.dev/guide/dep-pre-bundling.html

Vite may not identify changes to engage-ui code even when rebuilt as above, resulting in errors like:

Uncaught SyntaxError: The requested module '/node_modules/.vite/deps/@burnsred_ui-chakra.js?v=25e3c47a' does not provide an export named 'recentlyUpdated' (at myFile.tsx:5:10)

To resolve this, refresh vite's pre-bundled dependencies by running vite --force.

Suggest adding the following dev:clean script to client's package.json:

{
  "scripts": {
    "dev": "vite --port 3000",
    "dev:clean": "vite --port 3000 --force # refresh engage-ui files"
  }
}

Add a "vite clean" command · Issue #10986 · vitejs/vite

Relative imports are required in library code

In consuming apps, it's convenient to import via barrel files at the top level of the project (facilitated by compilerOptions.baseUrl in tsconfig.json), but attempting such imports in sharable components in this library may produce an error in the consuming app:

Failed to resolve import "components" from "../../packages/ui-chakra/dist/components/CompositeComponent.js". Does the file exist?

Hence, compilerOptions.baseUrl is not configured in @burnsred/ui-chakra; instead use relative links, preferably from barrel files:

// components/index.ts (barrel file)
export * from './MyComponent';

// components/CompositeComponent.tsx
import { MyComponent } from '..';

Publishing to NPM

Note: $version is not provided below, because you must decide the appropriate version according to the Semantic Versioning spec.

Usually, you'd use pass an option to npm version to bump by either major, minor, or patch (eg npm version patch), and the version operation would automatically git tag for you, BUT in a monorepo we're required to do git tag manually (see notes below).

When reading the steps below (until this is scripted), take note of the version produced by npm version, and use it in the git tag call.

# merge feature to main, then
git checkout main

# build and test
npm -w @burnsred/ui-chakra i && \
  npm -w @burnsred/ui-chakra run build && \
  npm -w @burnsred/ui-chakra test

# https://docs.npmjs.com/cli/v8/commands/npm-version
npm -w @burnsred/ui-chakra version $version

# Note that `npm version` does not git commit or tag in a monorepo - see comments below
git commit package*.json packages/ui-chakra/package*.json -m "[@burnsred/ui-chakra] v$version"
git tag "release/@burnsred/ui-chakra/$version"
git push && git push --tags

# login as `burnsred`; see 1password
npm login
npm -w @burnsred/ui-chakra publish

Success is indicated by the last line of output displaying the package and version number:

npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
+ @burnsred/[email protected]

Additional reading: How to publish packages to npm (the way the industry does things) | Zell Liew

Error: No matching version found for...

npm version 2.0.0-beta

npm ERR! notarget No matching version found for @burnsred/ui-chakra@^0.0.0

Pre-release tags don't seem to be matched, resulting in this error; note that if npm version returns an error, then the root package-lock.json will not be updated.

Behavior of npm version in a monorepo

...npm version -w x does not generate a git commit. The decision was made at the time of implementing npm version for workspaces to do this because the existing git tag config wasn't very conducive to workspaces.

tag-version-prefix defaults to v, and is not something that can be templated or otherwise changed per workspace in a single command. Rather than block npm version for workspaces altogether it was implemented bypassing git tagging altogether.

[BUG] Wrong behaviour of npm version inside workspaces · Issue #4017 · npm/cli

[RRFC] workspace-tag-version-prefix config · Issue #570 · npm/rfcs

Tag naming conventions

To allow use to differentiate between package releases, tags should be named:

"release/@burnsred/$package_name/$version"

tags are organized in directories and files (all git references are, run tree .git/refs/tags to see that), so I would suggest naming the tags:

myapp1/1.0.0
myapp1/1.0.1
 ...
myapp2/2.1.0
myapp2/2.2.0

This will group versions for each app together, and some commands will treat the numbers "naturally"

git - Monorepo Version Tags Conventions - Stack Overflow