Repository files navigation

Monorepo foropen-source Kong UI components and utilities.

• What goes here
• Creating a package
• Package Publishing
• Development
  • Requirements
  • Setup
  • Dev Server
  • Stylelint
  • ESLint
  • Type Checking
  • Testing
  • Preview sandbox build
  • Build for production
  • Committing Changes
  • Generating type interface documentation
  • Preview components
  • Running consuming application with local copy of the package
• Moving packages to the public/private repo
• Host App Troubleshooting
  • Analytics Packages are blocked by some ad-blockers

Here are some criteria to help figure out if your code belongs to this mono-repository. If all of the following are true, you are welcome to create a new package:

• Your code is open-source and/or at a minimum available to the public, and UI-related. If you are writing the code to be used privately at Kong, thenshared-ui-components is the better choice.

View the guide on creating a new package within the monorepo here

View the reference on how packages are versioned and published independently within the monorepo here

All packages must be created utilizing thepnpm run create-package CLI.See here for more details.

Be sure to familiarize yourself with theComponent Requirements, including style rules.

If you need to bump a version of a dependency for ALL consuming packages in this repo, use this command:

pnpm --recursive update {package-name}@{version}

Note that it will bump version of said dependency ONLY for those packages that have it as adependency ordevDependency, it won't add said dependency to package dependencies if it doesn't already have it.

• NodeJS >= 18.x
• pnpm 8.x (Why pnpm?). We recommend installing via the command shown here, substituting8.6.12 with the version listed in thepackage.json > volta.pnpm field. For example, for version8.6.12 you would use the commandcurl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=8.8.0 sh -

It is recommended to alsoglobally installlerna withpnpm (though not absolutely required)

To get started, install dependencies

pnpm install

Next, make sure all dependent packages (from the monorepo itself) are built and available

pnpm run build

You can also runpnpm install-completion to integratepnpm autocompletion into your command line tools.

Run the dev server in yourpackages/{workspace}/{package-name}/sandbox/ directory with hot-module reload

pnpm --filter"@kong-ui-public/{package-name}" run dev

Stylelint package files

# Lint onlypnpm --filter"@kong-ui-public/{package-name}" run stylelint# Lint and fixpnpm --filter"@kong-ui-public/{package-name}" run stylelint:fix

Lint package files

# Lint onlypnpm --filter"@kong-ui-public/{package-name}" run lint# Lint and fixpnpm --filter"@kong-ui-public/{package-name}" run lint:fix

Type check your package

pnpm --filter"@kong-ui-public/{package-name}" run typecheck

Run Component or Unit tests.

• Unit test files should be named*.spec.ts and will be run with Vitest
• Component test files should be named*.cy.ts and will be run with Cypress component test runner.

# Component testspnpm --filter"@kong-ui-public/{package-name}" run test:component# Component tests (with UI)pnpm --filter"@kong-ui-public/{package-name}" run test:open# Unit testspnpm --filter"@kong-ui-public/{package-name}" run test:unit# Unit tests (with UI)pnpm --filter"@kong-ui-public/{package-name}" run test:unit:open

Build yourpackages/{package-name}/sandbox/ directory for production and serve locally

pnpm --filter"@kong-ui-public/{package-name}" run build:sandboxpnpm --filter"@kong-ui-public/{package-name}" run preview

pnpm --filter"@kong-ui-public/{package-name}" run build

This repo usesConventional Commits.Commitizen andCommitlint are used to help build and enforce commit messages.

It ishighly recommended to use the following command in order to create your commits:

pnpm commit

For more information on different components that compose our commit messages, please reference thePackage Publishing docs

Lefthook is used to manage Git Hooks within the repo.

• Acommit-msg hook is automatically setup that enforces commit message stands withcommitlint, seelefthook.yml
• Apre-push hook is used that runsstylelint andeslint before allowing you to push your changes to the repository

Additionally, CI will usecommitlint to validate the commits associated with a PR in theLint and Validate job.

This only applies to TypeScript-only packages

If your package generatestypes, then add abuild:docs script to yourpackage.json file similar to the one in@kong-ui-public/analytics-utilities

"scripts": {... other scripts"build:docs":"{your command for generating docs}"}

Please run thebuild:docs command manually to generate the docs and then commit them to your PR.

You are working on the PR and changing component project. Let's say@kong-ui-public/i18n. You want to try to deploy consuming application (khcp-ui for example) that uses your changed code without merging your changes to main and publishing new version of@kong-ui-public/i18n. Here are the steps:

1. Look at your PR where your changes for@kong-ui-public/i18n. Every time PR is getting built, NPM preview of package is getting deployed, and there is an updated PR comment created:

Preview components from this PR in consuming applicationIn consuming application project install preview versions of shared packages generated by this PR:// we are adding the version tagged on npm with your PR number@kong-ui-public/i18n@pr-456

Install the preview version of the package in consuming application, let that PR be deployed, and see PR preview of consuming application utilizing@kong-ui-public/i18n code from your shared-ui-components PR branch.

Never merge consuming application code that uses preview version of the package. PR versions will be deprecated and unpublished when your PR is closed.

You are developing shared component (let's say@kong-ui-public/forms) and you need to run consuming application with the current version of the code you have locally in yourpublic-ui-components/packages/{workspace}/forms branch. Here is how to do it:

1. in the folderpublic-ui-components/packages/{workspace}/forms run

   pnpm link -g

2. make sure your package is getting build in watch mode, for this in the folderpublic-ui-components/packages/{workspace}/forms run:

   pnpm build:package --watch

3. In the root folder of the host application/package run:

   pnpm link -g @kong-ui-public/forms

4. Run your consuming application as usual and enjoy your forms code changes visible in your local env immediately.

   yarn run dev

In some cases HMR (hot module reloading) is not working out of the box in this configuration, to force it you might need following changes invite.config.ts of consuming application:

1. addwatch: ignored into theserver config:

   server:{watch:{ignored:['!**/node_modules/@kong-ui-public/forms/**']}}

2. addoptimizeDeps into the root of the config:

   optimizeDeps:{exclude:['@kong-ui-public/forms']}

   Please do not commit these changes

   And finally, when you done working with local (linked copy) of yourpublic-ui-components package, unlink it:

3. In the folderpublic-ui-components/packages/{workspace}/forms run

   pnpm remove -g @kong-ui-public/forms

4. In the root folder of the host application/package run:

   pnpm unlink -g @kong-ui-public/formspnpm install

Sometimes packages are initially created inKong/shared-ui-components where they areprivately published, but need to be moved into thepublicKong/public-ui-components OSS repository so that the source code and npm package can be consumed by anyone.

View the docs on how to move packages between the private/public repositories here

Some ad blockers inadvertently block build files with the stringanalytics in the name. As a proactive measure, thevite.config.ts files in our packages utilize asanitizePackageName utility that replaces instances of the stringanalytics withvitals in generated filenames and global variables.

If your host applicationstill has issues with ad blockers, you can try addingbuild rules to your host application'svite.config.js (or similar) to replace instances of the strings in components and packages:

// vite.config.tsimport{defineConfig}from'vite'// Replace any variation of string 'Analytics' in assets and chunks. Replacements are in order to preserve capitalization.// The third replacement is a catch-all in case a string like `ANALYTICS` is presentconstreplaceAnalytics=(str:string)=>str.replace(/Analytics/g,'Vitals').replace(/analytics/gi,'vitals')exportdefaultdefineConfig({// ...build:{rollupOptions:{output:{chunkFileNames:(chunkInfo)=>{constname=replaceAnalytics(chunkInfo.name||'')return`${name}.[hash].js`},assetFileNames:(assetInfo)=>{// Replace any instances of `analytics` in the external package nameconstfilename=replaceAnalytics(assetInfo.name||'').split('.')[0]return`assets/${filename}.[hash].[ext]`},},},},})