Skip to content
On this page

Contributing

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

Installation

Clone the Kongponents repository

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

Install dependencies

sh
cd kongponents && yarn install --frozen-lockfile
1

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

sh
yarn build:cli
1

Run the docs local dev server with hot-module reload

sh
yarn docs:dev
1

Build the docs and preview the built files locally

sh
yarn docs:preview
1

Perform a full build of all Kongponents and the Docs site

sh
yarn build
1

CLI

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

sh
yarn create-kongponent
1

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

NOTE

If your component is exported via an index.ts file, or anything other than the default {KongponentName}.vue file, you will need to modify /src/components/index.ts accordingly.

Once ran, this will be the resulting file structure:

bash
├── docs/
│   └── components/
│       └── {kongponent}.md
└── src/
    └── components/
        └── {KongponentName}/
          ├── {KongponentName}.cy.ts
          └── {KongponentName}.vue
1
2
3
4
5
6
7
8

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.mdbutton.md
  • kcard.mdcard.md
  • kdatetimepickerdatetime-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.

md
# {Name}

**{KongponentName}** - description
1
2
3

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

ts
// 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}',
        },
        ...
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Importing type declarations and interfaces

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

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

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

    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

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:

sh
yarn commit
1

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.yml here:

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

pre-push:
  commands:
    eslint:
      run: yarn lint

commit-msg:
  commands:
    commitlint:
      run: yarn commitlint --edit "$1"
1
2
3
4
5
6
7
8
9
10
11
12

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

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

We recommend using VSCode along with the Volar extension

Type Support For .vue Imports in TS

Since TypeScript cannot handle type information for .vue imports, they are shimmed to be a generic Vue component type by default. In most cases this is fine if you don't really care about component prop types outside of templates. However, if you wish to get actual prop types in .vue imports (for example to get props validation when using manual h(...) calls), you can enable Volar's .vue type support plugin by running Volar: Switch TS Plugin on/off from VSCode command palette.

Released under the Apache-2.0 License.