Contributing ​

In this section we will focus on the steps and nuances of developing Kongponents. Lets start with installation.

Installation ​

Clone the Kongponents repository

git clone https://github.com/Kong/kongponents.git

Install dependencies

cd kongponents && yarn install --frozen-lockfile

Next, let's generate the CLI that can be used to easy scaffold new Kongponent components. This likely was ran automatically after installing dependencies.

yarn build:cli

Run the docs local dev server with hot-module reload

yarn docs:dev

Build the docs and preview the built files locally

yarn docs:preview

Perform a full build of all Kongponents and the Docs site

yarn build

Perform a full build of all Kongponents and output a /bundle-analyzer/stats-treemap.html to view the output.

yarn build:visualize

CLI ​

It is highly recommended to utilize the included CLI when creating new Kongponents as it will scaffold all the necessary files.

yarn create-kongponent

Create a new Kongponent ​

When creating a new component with the CLI it will perform the following actions:

• Creates /src/components/{KongponentName}/ directory with the following files:
  • {KongponentName}.cy.ts - Cypress Component Test file
  • {KongponentName}.vue - Component file
• Adds /src/components/{KongponentName}/{KongponentName}.vue to the exports in /src/components/index.ts
• Creates a VitePress markdown file at /docs/components/{kongponent}.md (you have to manually add this file to the VitePress sidebar in docs/.vitepress/config.ts).

Once ran, this will be the resulting file structure:

├── docs/
│   └── components/
│       └── {kongponent}.md
└── src/
    └── components/
        └── {KongponentName}/
          ├── {KongponentName}.cy.ts
          └── {KongponentName}.vue

Important: Type Exports ​

You must manually add the new component type to the module export located at src/global-components.ts. Just add your new component to the bottom of the list.

// src/global-components.ts
import type * as components from './components'

declare module '@vue/runtime-core' {
  export interface GlobalComponents {
    KAlert: typeof components.KAlert
    KBadge: typeof components.KBadge
    KBreadcrumbs: typeof components.KBreadcrumbs
    KButton: typeof components.KButton
    YourNewComponent: typeof components.YourNewComponent
  }
}

Add the doc file to the sidebar ​

Although the CLI will create a file in the docs directory, the new doc file is not automatically added to the docs sidebar config.

Add the component to the desired location in the sidebar

// docs/.vitepress/config.ts

sidebar: {
  // Components sidebar
  '/components/': [
    {
      text: 'Components',
      collapsible: true,
      items: [
        ...
        {
          // The name of the rendered element, e.g. "Alert"
          text: '{Component Name}',
          // The name of the `.md` markdown file without the extension, e.g. "/components/alert.md"
          link: '/components/{component-name}',
        },
        ...
      ]
    }
  ]
}

Edit the Doc file ​

Each component has an associated file in the /docs/components directory. After scaffolding the new component file, a doc file should be present named the same as your new component. Below are the steps to add the file to the docs site and how to get started editing.

Renaming the file (if needed) ​

The docs markdown file should be named correctly if generated from the create-kongponent CLI. If necessary, rename the file to correspond to what type of component it is. For documentation purposes page names should be based on what the component is vs its Kongponent K name.

Examples ​

• kbutton.md → button.md
• kcard.md → card.md
• kdatetimepicker → datetime-picker.md

Update the page title ​

Update the first line of the doc to match the file name. This is what is displayed as the page title & in the sidebar.

# {Name}

**{KongponentName}** - description

Importing type declarations and interfaces ​

When importing type declarations or interfaces, you can use a relative path instead of the @/ alias so that the types are properly resolved within consuming packages. See the example below:

import { StepperState } from './KStepState.vue'

This repository utilizes tsc-alias to replace these paths during the build; however, either method is acceptable.

Style guidelines ​

In order to prevent component styles from leaking out into the consuming application, all component styles MUST adhere to one of the following rules:

1. (Preferred) All styles must be scoped within your components with <style lang="scss" scoped>.

   1. If you need to target nested components (e.g. Kongponents) to override styles, you'll need to utilize deep selectors
   html

   <style lang="scss" scoped>
   .your-component-class {
     :deep(.k-button) {
       /* KButton override styles go here */
       border-color: red;
     }
   }
   </style>

   1
   2
   3
   4
   5
   6
   7
   8
   

2. All component styles must be wrapped in a unique wrapper class so that styles do not leak out into the consuming application.

   The class name should follow the syntax .k-{component-name}-*

   This is a good practice even if you go with option one outlined above.

   html

   <style lang="scss">
   .k-button {
     /* All other styles must go inside the wrapper */
   }
   </style>

   1
   2
   3
   4
   5
   

Relative units ​

Kongponent styles should never use relative font units; specifically, do not use rem or em units.

We cannot control the html base font size and therefore these relative units are not predictable within a host application. Use px (pixels) or a similar unit instead.

Testing your component ​

You're free to play around with your component on the local instance of the docs site by running yarn docs:dev; however, you may also want to test your local changes in a consuming application.

1. Run yarn link from the root of the Kongponents repository

   sh

   yarn link
   
   yarn link v1.22.17
   success Registered "@kong/kongponents".
   info You can now run `yarn link "@kong/kongponents"` in the projects where you want to use this package and it will be used instead.
   ✨  Done in 0.04s.

   1
   2
   3
   4
   5
   6
   

2. Build the Kongponents package

   sh

   yarn build:kongponents

   1
   

   Note

   Alternatively, if you do not need to rebuild the types and would prefer to watch for changes, you can run just the vite build command with the --watch flag to automatically rebuild when you save changes.

   sh

   yarn vite build --watch

   1
   

3. As the instructions above outline, next, inside your consuming application, run yarn link "@kong/kongponents"

   sh

   yarn link "@kong/kongponents"
   
   yarn link v1.22.19
   success Using linked package for "@kong/kongponents".
   ✨  Done in 0.04s.

   1
   2
   3
   4
   5
   

   Now that the dependency is linked, your local project will utilize the local build.

   Note

   You may need to clear the vite cache using the --force flag in your host app in order to pick up the newly built files. You will also need to restart your Vite server after every rebuild of Kongponents to pull in the changes.

   TIP

   If your project utilizes Vite, you may need to dedupe your dependency tree to avoid errors when running locally. Inside your vite.config.ts file, insert the following configuration:

   ts

   export default defineConfig({
     resolve: {
       // Use this option to force Vite to always resolve listed dependencies to the same copy (from project root)
       // Allows utilizing `yarn link "{package-name}"` without throwing errors
       dedupe: ['vue']
     },
   })

   1
   2
   3
   4
   5
   6
   7
   

4. When you're finished testing, don't forget to run yarn unlink inside the Kongponents directory.

   sh

   yarn unlink
   
   yarn unlink v1.22.17
   success Unregistered "@kong/kongponents".
   info You can now run `yarn unlink "@kong/kongponents"` in the projects where you no longer want to use this package.
   ✨  Done in 0.04s.

   1
   2
   3
   4
   5
   6
   

5. At this point it is recommended you delete the node_modules folder in your consuming app and rerun yarn install --frozen-lockfile to fully clear the linkage.

Sandbox ​

The sandbox mode in Kongponents provides developers with a controlled environment to test and ensure that no styles from the docs app leak through into the component library. This feature guarantees that the components look and function as intended, without any external interference.

By using the sandbox mode, you can have confidence that components maintain their visual consistency, regardless of the context in which they are used.

yarn dev:sandbox

Committing Changes ​

This repo uses Conventional Commits.

Commitizen and Commitlint are used to help build and enforce commit messages.

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

yarn commit

This will trigger the Commitizen interactive prompt for building your commit message and will allow you to preview your commit.

Enforcing Commit Format ​

Lefthook is used to manage Git Hooks within the repo. See see the current /lefthook.yaml here:

# Reference:
# https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md

pre-push:
  parallel: true
  commands:
    stylelint:
      skip:
        - merge
        - rebase
      run: yarn stylelint
    eslint:
      skip:
        - merge
        - rebase
      run: yarn lint

commit-msg:
  parallel: true
  commands:
    commitlint:
      skip:
        - merge
        - rebase
      run: yarn commitlint --edit "$1"

A commit-msg hook is automatically setup that enforces commit message stands with commitlint.

A pre-push hook is configured to run Stylelint and ESLint before pushing your changes to the remote repository.

Recommended IDE Setup ​

We recommend using VSCode along with a few suggested extensions (VSCode should automatically show a notification suggesting to install the recommended extensions when you open the project folder for the first time).

Type interfaces for Vue components ​

All types related to components must be included in the /src/types/ folder in a corresponding {Kongponent-name}.ts type file (without the k prefix).

All files must be exported from the /src/types/index.ts file.

── src/
    └── types/
     ├── {Kongponent-name}.ts
     └── index.ts

When importing a type for use in a component, we use import with type prefix

import type { SomeType } from '@/types'

Tips when typing Vue components ​

• Instead of setting prop type as String, set it as String Literal Types e.g. when we want to set via prop a mode, we can set it as light | dark | none instead of String
• Avoid using Object type as props, use an interface instead.