Kongponents is a Vue component library of frequently needed UI elements. They were developed to solve Kong's application needs, but are generic enough to use in any web application.

Installation

To begin using Kongponents, start by installing the package into your project using yarn or npm.

# Make sure you pass the beta tag
yarn add @kong/kongponents@beta

# Make sure you pass the beta tag
npm install @kong/kongponents@beta

If you choose to utilize any of the CSS custom properties (variables) included in the @kong/kongponents package and your project uses PostCSS, you will likely need use the postcss-custom-properties PostCSS plugin so that the variables are preserved in their original form.

yarn add postcss-custom-properties --dev

npm install postcss-custom-properties --save-dev

Next, add a postcss.config.js file to your project with the following content

// postcss.config.js

module.exports = () => ({
  plugins: {
    'postcss-custom-properties': {
      preserve: true
    }
  }
})

Usage

There are two ways to use Kongponents in your project: globally install all Kongponents, or register individual Kongponents as needed.

Regardless of which method you choose you will first need to import the Kongponents CSS (Vite does not currently support CSS in JS when building in library mode).

The easiest place to import the styles is inside your Vue entry file (e.g. main.ts). For more examples of utilzing Kongponent styles, including importing the Sass and CSS variables and even scoping the styles, see the other usage examples.

Globally install all Kongponents

If you plan to use a majority of the Kongponent components, you can import the package and install as a Vue Plugin to register all components and make them globally available in your app.

This method is only ideal if you are using a majority of the Kongponents in your project, as the unused components will not be tree-shaken.

// main.ts (or Vue entry file)

import { createApp } from 'vue'
import Kongponents from '@kong/kongponents'

// Import Kongponents styles (path may vary)
import '../node_modules/@kong/kongponents/dist/style.css'

const app = createApp(App)

// Install and register all Kongponents as a plugin
app.use(Kongponents)

app.mount('#app')

Register individual Kongponents

Alternatively, you can import and register just the components you intend to use.

Import and registration can be done globally in your Vue entry file (e.g. main.ts), or locally, just in the component where it will be used.

// main.ts (or Vue entry file)

import { createApp } from 'vue'
import { KButton } from '@kong/kongponents'

// Import Kongponents styles (path may vary, shown here for Vite)
import '../node_modules/@kong/kongponents/dist/style.css'
// If using Vue-CLI and webpack, you can likely use this path instead: import '~@kong/kongponents/dist/style.css'

const app = createApp(App)

// Register an individual Kongponent
app.component('KButton', KButton)

app.mount('#app')

<script lang="ts">
// YourComponent.vue

import { defineComponent } from 'vue'
import { KButton } from '@kong/kongponents'

export default defineComponent({
  name: 'YourComponent',
  components: { KButton },
})
</script>

<style>
/* Import Kongponents styles (path may vary, shown here for Vite) */
@import "../../node_modules/@kong/kongponents/dist/style.css";
/* If using Vue-CLI and webpack, you can likely use this path instead: import '~@kong/kongponents/dist/style.css' */
</style>

Webpack

Depending on your project setup, you may need to transpile the @kong/kongponents package in your project. If your project already has a vue.config.ts file, just add the following transpileDependencies entry

// vue.config.ts

module.exports = {
  transpileDependencies: [
    /@kong\/kongponents/
  ]
}

If your project does not have a vue.config.ts file and instead uses webpack config files, you can add a loader rule (for example, for babel-loader) similar to the following (only showing the relevant entries)

// webpack.config.js

module.exports = (env) => {
  return {
    module: {
      loaders: [
        // transpile @kongponents packages
        {
          test: /\.js$/,
          include: /(node_modules)\/(@kong\/kongponents)/,
          loader: 'babel-loader',
        },
        // process all .js files, but ignore all other node_modules not listed above
        {
          test: /\.js$/,
          exclude: /(node_modules)/,
          loader: 'babel-loader'
        },
      ]
    }
  }
}

Without Bundle System

You can also use Kongponents in a project where there is no build system as long as Vue is included on the page.

Note

You must import the CSS from the @kong/kongponents package along with Vue.