Vue 3 Plugin and Native HTML Web Components used for KAuth UI implementation in Kong apps
Install the package as a dependency in your app
yarn add @kong/kong-auth-elementsThe default exports have a bundle filename of *.vue.{umd|es}.js where we internalize Vue for consumption by the plugin (i.e. the bundle includes the Vue core).
We also provide kong-auth-elements.{umd|es}.js bundles that do NOT internalize (bundle) the Vue core along with it. These bundles can can be imported via <script> (umd bundle) or <script type="module"> (es bundle) tags into projects where Vue is already available in the global namespace.
To utilize, include the script tag on your page after including Vue, and then call window.registerKongAuthNativeElements() with the options outlined below.
You will also need to import the styles in the document.head
<link rel="stylesheet" href="/{path}/dist/style.css"See a working example here: https://codepen.io/adamdehaven/pen/ExRxYja
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="https://packages.konghq.tech/@kong/kong-auth-elements@1/dist/style.css" />
<script src="https://packages.konghq.tech/@kong/kong-auth-elements@1/dist/kong-auth-elements.vue.umd.js"></script>
</head>
<body>
<div class="container">
<div id="kong-auth-register-wrapper">
<kong-auth-register wrapper-id="kong-auth-register-wrapper" .register-success="showAlert('Register success!')" />
</div>
</div>
<script>
(function() {
var showAlert = function(text = '') {
if (!text) {
return
}
alert(text)
}
window.registerKongAuthNativeElements({
apiBaseUrl: 'https://global.api.konghq.com/kauth',
userEntity: 'user',
})
})()
</script>
</body>
</html>Import the package (and TypeScript types, if desired) inside of your App's entry file (e.g. for Vue, main.ts). Set the plugin options, and tell Vue to use the plugin.
// main.ts
import App from './App.vue'
import { KongAuthElementsPlugin } from '@kong/kong-auth-elements/dist/kong-auth-elements.es'
import type { KongAuthElementsOptions } from '@kong/kong-auth-elements/dist/types'
import '@kong/kong-auth-elements/dist/style.css'
const app = createApp(App)
const pluginOptions: KongAuthElementsOptions = {
// Unless using an absolute URL, this base path MUST start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users)
apiBaseUrl: 'https://global.api.konghq.com/kauth',
userEntity: 'user',
shadowDom: false, // We are using the Vue plugin, so the shadow DOM isn't needed
}
// Register the plugin
app.use(KongAuthElementsPlugin, pluginOptions)
app.mount('#app')Now that the plugin is globally registered, simply include a component just like you would any other Vue component, utilizing any props as needed
<KongAuthLogin
show-forgot-password-link
@login-success="onLoginSuccess"
@click-forgot-password-link="onUserClickForgotPassword"
@click-register-link="onUserClickRegister"></KongAuthLogin>Import the package (and TypeScript types, if desired) inside of your App's entry file (e.g. for Vue, main.ts), set up the options, and call the provided registerKongAuthNativeElements function.
// main.ts
import registerKongAuthNativeElements from '@kong/kong-auth-elements'
import type { KongAuthElementsOptions } from '@kong/kong-auth-elements'
import '@kong/kong-auth-elements/dist/style.css'
const options: KongAuthElementsOptions = {
// Unless using an absolute URL, this base path MUST start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users)
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'user',
shadowDom: true,
injectCss: ['.kong-auth-login-form .k-input#email { background-color: #ff0000 }'],
lang: 'en', // Exclude to default to English
}
// Call the registration function to automatically register all custom elements for usage
registerKongAuthNativeElements(options)The function will register all custom elements for usage as native web components.
Wherever you want to utilze a custom element, you must wrap it with an element (e.g. a div) with a unique id attribute, and then simply include the element in your HTML just like you would any other element, utilizing any props as needed
<div id="kong-auth-login-wrapper">
<kong-auth-login
basic-auth-login-enabled
show-forgot-password-link
@login-success="onLoginSuccess"
@click-forgot-password-link="onUserClickForgotPassword"
@click-register-link="onUserClickRegister"></kong-auth-login>
</div>For the current implementation, it is REQUIRED to wrap the element with a tag with a unique id attribute so the custom element can be "teleported" out of the shadow DOM to enable password manager support.
The id attribute should then be passed to each Custom Element in the wrapperId prop so the element can be properly teleported out of the shadow DOM. For more information refer to the Vue Teleport docs. There are default wrapperId prop values provided; however to utilize them you still must wrap the custom element in an element with the corresponding id.
Regardless if you're using in Vue 3, Vue 2, or the native web components, an identical set of options exist for configuring the kong-auth-elements.
| Option | Type | Default | Description |
|---|---|---|---|
apiBaseUrl |
string |
/kauth |
The basePath of the internal axios instance. Unless using an absolute URL, this base path must start with a leading slash (if setting the default) in order to properly resolve within container applications, especially when called from nested routes(e.g. /organizations/users) |
userEntity |
string |
user |
The user entity for authentication; one of user or developer. |
developerConfig |
DeveloperConfig |
{ portalId: string } |
The developer config object. |
customErrorHandler |
Function |
(event: CustomEndpointErrorEvent) => '' |
Supply a custom error handler to use when utilizing an element that allows providing a custom request endpoint. See the example below |
injectCss |
string[] |
[] |
Pass an array of inlined CSS strings that will be injected into the DOM. See the example below |
lang |
string |
en |
Set the language to use for the component message strings. See /src/locales/ |
You can import the TypeScript interfaces from the package if desired.
// List of user entities
export type UserEntities = 'user' | 'developer'
// List of custom elements that accept a custom error handler
export type CustomEndpointElement = 'kong-auth-login' | 'kong-auth-forgot-password' | 'kong-auth-register' | 'kong-auth-reset-password' | 'kong-auth-change-password'
// List of requests that support custom endpoints
export type CustomEndpointRequest = 'authenticate-request' | 'verify-email-request' | 'reset-password-request' | 'change-password-request' | 'register-request' | 'set-new-password-request'
export interface CustomEndpointErrorEvent = {
error: AxiosError
request: CustomEndpointRequest
element: CustomEndpointElement
}
// Developer config options
export interface DeveloperConfig {
portalId: string
}
// Supported languages
export type SupportedLanguages = 'en'
export interface KongAuthElementsOptions {
apiBaseUrl?: string
userEntity?: UserEntities
developerConfig?: DeveloperConfig
customErrorHandler?: (event: CustomEndpointErrorEvent) => string
shadowDom?: boolean
injectCss?: string[]
lang?: SupportedLanguages
}You can customize the logic in your error handler to only respond to the requests or elements you wish to target.
If an error message string is not returned from the customErrorHandler based on the error/request/element logic then the default error handler and messaging will be used.
const pluginOptions: KongAuthElementsOptions = {
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'developer',
customErrorHandler: ({ error, request, element }): string => {
// Access the original error
console.log('error', error)
// ... or the element name that the event was triggered by
console.log('element', element)
// Or perform different logic based on the request that errored
if (request === 'reset-password-request') {
return 'Custom reset error message.'
} else if (request === 'register-request') {
return 'Custom registration error message.'
}
},
}// Pass in inlined CSS strings as needed
const pluginOptions: KongAuthElementsOptions = {
apiBaseUrl: 'https://us.api.konghq.com/kauth',
userEntity: 'user',
injectCss: [
'.kong-auth-login-form .k-input#email { background-color: #ff0000 }',
`
.kong-auth-register-form .k-input {
width: 50%;
}
`,
],
}Events are emitted for different component/element actions.
If using the Vue Plugin, you can listen to these events just like you would any other emitted event. (e.g. @login-success="successHandler") The payload of events follows the Record<string, any> type in most cases.
const successHandler = (eventData: Record<string, any>) => {
console.log(eventData.email) // => 'marty.mcfly@thepinheads.com'
}If your app uses the native web components, the emitted events follow the CustomEvent() Web API spec.
An example of consuming the native web component events and CustomEvent.details (emitted data) in your Vue app can be seen here
<kong-auth-forgot-password
instruction-text="Enter your verified email address and we will send you a password reset link."
@forgot-password-success="onForgotPasswordSuccess"
></kong-auth-forgot-password>
<script lang="ts">
setup () {
// Respond to a successful reset password request
const onForgotPasswordSuccess = (successEvent: CustomEvent): void => {
const eventData: Record<string, any> = Array.isArray(successEvent.detail) ? successEvent.detail[0] : successEvent.detail
console.log(`User with email '${eventData.email}' successfully requested a password reset email.`)
}
return {
onForgotPasswordSuccess
}
}
</script>If your app does not utilize Vue, you can respond to the custom events just like any other event listener
// Add an appropriate event listener
document.querySelector('kong-auth-login').addEventListener('login-success', function (successEvent) {
const eventData = Array.isArray(successEvent.detail) ? successEvent.detail[0] : successEvent.detail
console.log('The user has successfully authenticated!')
})You may utilize any CSS variables included in the Kongponents component library.
In order to override the built-in CSS variables, you will need to scope your custom values to the .kong-auth-element selector as shown here
.kong-auth-element {
--kui-color-text-primary: green;
}If utilizing the native web components inside of a Vue app with the register function (which forces use of the native web components), you will need to inform your consuming app (e.g. Vue) to recognize the custom elements defined outside of the framework (e.g. using the Web Components APIs).
If a component matches this condition, it won't need local or global registration and Vue won't throw a warning about an Unknown custom element.
Regardless of whether your consuming application is a Vue app, you will also need to add an entry to transpileDependencies.
If your consuming application is a Vue app, add the following code in vue.config.js
// vue.config.js
module.exports = {
chainWebpack: (config) => {
config.module
.rule('vue')
.use('vue-loader')
.tap((options) => {
return {
...options,
compilerOptions: {
isCustomElement: (tag) => tag.startsWith('kong-auth'), // Tags with this prefix will be recognized as custom elements
},
}
})
},
transpileDependencies: ['@kong/kong-auth-elements'],
}If your consuming app does not utilize vue.config.js file, you can transpile dependencies in your project's webpack config. As an example, if using babel-loader, you can include something like this in your webpack.config.js file
// webpack.config.js
module.exports = {
module: {
loaders: [
{
test: /\.js$/,
include: /(node_modules)\/(@kong/kong-auth-elements)/,
loader: 'babel-loader'
}
]
}
}The custom elements have data attributes in place with a standard format of data-testid="kong-auth-{identifier}". If these test selectors are not sufficient, you should be able to create your tests by targeting a parent element and then searching downward through its child elements as needed.
If you have a specific use-case, submit a PR for a new attribute to be added and please add an example use-case as to why the existing attributes are not sufficient.
If your app utilizes Cypress for testing, you will need to add an entry to your cypress.json configuration file to allow it to traverse the shadow DOM.
{
"includeShadowDom": true
}Alternatively, you can provide an options object to the .get() method with a includeShadowDom property set to true; however, you would have to replicate in every .get() reference, so it's easier to add to your cypress.json config file, if possible. Cypress also has a .shadow() command, but again, the config setting is the easier way to go.
- Provides a login UI along with corresponding
kauthauthentication (foruseranddeveloperentities) - Provides Identity Provider (IdP) login, if enabled.
- Provides email verification, given a valid
tokenin the query string. - Sets the
kauthcookies, along with theuserStatuscookie (possibly unused). - Consumes the
options.developerConfig.portalIdfordeveloperentity authentication.
The login element must reside at the {window.location.origin}/login path in your application.
| Prop | Type | Default | Description |
|---|---|---|---|
wrapperId |
String | kong-auth-login-wrapper |
Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
instructionText |
String | '' |
Set the instruction text to display above the inputs. |
showForgotPasswordLink |
Boolean | false |
Show a forgot password link under the password field. |
forgotPasswordLinkText |
String | Forgot your password? |
Set the text for the forgot password link. |
showRegisterLink |
Boolean | false |
Show a register link under the login button. |
registerLinkHelpText |
String | Don't have an account? |
Set the register link help text. |
registerLinkText |
String | Sign Up |
Set the text for the register link. |
registerSuccessText |
String | Successfully registered! |
Set the text for the register success message. |
basicAuthLoginEnabled |
Boolean | false |
Enable basic auth login. To set to false, simply do not add the prop |
showBasicAuthLoginLink |
Boolean | true |
Show a link to log in with basic auth credentials on the IdP login form. |
idpLoginEnabled |
Boolean | false |
Enable IdP login detection. |
idpLoginCallbackUrl |
URL | '' |
Set the URL to return to in order to complete the OIDC flow. In most cases, this should be set to ${window.location.origin}/login |
idpLoginReturnTo |
URL | '' |
Set the URL to return to upon successful IdP login. In most cases, this should be set to window.location.origin |
idpFullScreenLoader |
Boolean | true |
Show the full screen loading skeleton when IdP login is processing |
loginSsoButtonText |
String | Continue with SSO |
Set the text for the SSO login button. |
loginButtonText |
String | Log in |
Set the text for the basic authentication login button. |
Note: When utilizing the props as a native web component, you may need to use dot syntax, as shown here
<!-- Use this (notice the `.` before the attribute name) --> <kong-auth-login .basic-auth-login-enabled="false"> <!-- Instead of this --> <kong-auth-login :basic-auth-login-enabled="false">
| Event | Payload | Description |
|---|---|---|
login-success |
User successfully logged in. | |
verify-email-success |
{ email: String } |
User successfully verified their email address. |
click-forgot-password-link |
User clicked the included forgot password link. | |
click-register-link |
User clicked the included register link. | |
idp-is-loading |
{ isLoading: Boolean } |
IdP authentication is processing. |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
| Param | Required | Description |
|---|---|---|
token |
true if email verification |
Pass a valid token entry in the URL query string to verify the user's email address. |
passwordReset |
true if password reset |
To show the Reset Password Confirmation, the consuming app URL must include passwordReset=true in the query string. You can choose to include the email parameter as well. |
registered |
true if register success (from register or invite) |
To show the Register Confirmation, the consuming app URL must include registered=true in the query string. You can choose to include the email parameter as well. |
email |
false |
Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string to prepopulate the login form's email input. |
basicAuth |
false |
To force displaying basic authentication (e.g. for organization owners) the URL should include basicAuth=true in the query string. |
When a user lands on your app on the route /login/{login-path} the <kong-auth-login> element will automatically initialize IdP login if the idpLoginEnabled prop is set to true, and the idpLoginReturnTo prop contains a valid URL to redirect the user to after successful authentication.
When a developer lands on your app on the route /login/sso the <kong-auth-login> element will automatically initialize IdP login if the idpLoginEnabled prop is set to true, and the idpLoginReturnTo prop contains a valid URL to redirect the user to after successful authentication.
Upon logging out, if the user is sent to /login/{login-path}?logout=true (notice the logout query param) this will prevent IdP auto-initialization, and will hide the email and password fields and instead will show a Login button along with a separate link to login with credentials. This allows your app to log out the user, send them back to their organization's login path without actually logging them back in (preventing a loop).
If the user clicks the Login button, they will be sent to /login/{login-path} which will start auto-initialization.
If the user clicks the link to login with credentials, they will be sent to /login, and will be able to authenticate with an email and password (if they are an Organization Owner, or their organization allows credentialed login).
- Provides a forgot password UI along with corresponding
kauthfunctionality to allow the user to request a reset password email.
| Prop | Type | Default | Description |
|---|---|---|---|
wrapperId |
String | kong-auth-forgot-password-wrapper |
Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
showLoginLink |
Boolean | false |
Show a login link under the password fields. |
loginLinkText |
String | Return to log in |
Set the text for the login link. |
instructionText |
String | '' |
Set the instruction text to display above the inputs. |
successText |
String | Check your email for a link to reset your password. If it doesn’t appear within a few minutes, check your spam folder. |
Set the text to display upon successful reset password request. |
resetPasswordRequestEndpoint |
String | '' |
Set the URL (relative or absolute) endpoint for the password reset request. |
| Event | Payload | Description |
|---|---|---|
wrapperId |
String | kong-auth-reset-password-wrapper |
forgot-password-success |
{ email: String } |
User successfully requested a reset password email. |
click-login-link |
User clicked the included login link. |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
- Provides a reset password UI along with corresponding
kauthfunctionality to allow the user to reset their password when coming from the reset password email, provided a validtokenis present in the query string.
| Prop | Type | Default | Description |
|---|---|---|---|
instructionText |
String | '' |
Set the instruction text to display above the input. |
| Event | Payload | Description |
|---|---|---|
reset-password-success |
{ email: String } |
User successfully reset their password. |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
| Param | Required | Description |
|---|---|---|
token |
true |
Pass a valid token entry in the URL query string to send to the reset password request. |
email |
false |
Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string to prepopulate the login form's email input on redirect. |
- Provides a change password UI along with corresponding
kauthfunctionality to allow the user to change their password when coming from the MyAccount UI. Note: This component is only functional whenuserEntity === 'user'.
| Prop | Type | Default | Description |
|---|---|---|---|
instructionText |
String | '' |
Set the instruction text to display above the input. |
changePasswordButtonText |
String | Change Password |
Set the text for the change password button. |
| Event | Payload | Description |
|---|---|---|
change-password-success |
User successfully changed their password. | |
password-requirements |
{uppercase: boolean, lowercase: boolean, number: boolean, special: boolean} |
Password requirements met after user inputs new password |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
- Provides a registration UI along with corresponding
kauthfunctionality to allow the user to register and sending the confirmation email. - Checks the client config to determine if registration access codes are required.
| Prop | Type | Default | Description |
|---|---|---|---|
wrapperId |
String | kong-auth-register-wrapper |
Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
accessCodeRequired |
Boolean | false |
An access code is required for registration. |
instructionText |
String | '' |
Set the instruction text to display above the form inputs. |
registerButtonText |
String | Sign up for Free |
Set the text for the register button. |
registerRequestEndpoint |
String | '' |
Set the URL (relative or absolute) endpoint for the registration request. |
recaptcha |
Boolean | false |
Should reCAPTCHA be enabled for the register form. This feature is currently only available if the userEntity is set to user. |
| Param | Required | Description |
|---|---|---|
selectRegion |
false |
Pass "selectRegion=true" in the URL to show the Konnect region selection during registration for userEntity === 'user'. |
| Event | Payload | Description |
|---|---|---|
register-success |
{ email: String, { organization: { id: String, name: String } } } |
User successfully registered. |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
- Provides a UI to allow accepting an invitation. The user should arrive via an invite link with the required query string parameters (outlined below) in the URL. The form will be pre-populated with data and the user will just provide a new password.
| Prop | Type | Default | Description |
|---|---|---|---|
wrapperId |
String | kong-auth-accept-invitation-wrapper |
Set the element selector of where the element should be rendered outside of the shadow DOM. This is normally the id of the parent HTML element. |
subheaderText |
String | You've been invited to join |
Set the subheader text that appears before the organization name above the form. |
| Event | Payload | Description |
|---|---|---|
accept-invitation-success |
{ email: String } |
User successfully accepted the invitation. |
To respond to any of the emitted events in your app, simply provide a callback for any of the events listed above. See the Events reference for more details. All events return a Custom Event.
| Param | Required | Description |
|---|---|---|
token |
true |
Pass an invite token in the query string. |
email |
true |
Pass the user's URL encoded email address (e.g. email=user%40foo.com via encodeURIComponent()) in the query string. |
fullName |
true |
Pass the user's URL encoded full name in the query string. |
org |
true |
Pass the user's URL encoded organization in the query string. |
-
Custom elements must follow the naming convention
{PascalCaseName}.ce.vue -
The only root-level tag within the
<template>of a custom elementsrc/elements/**/{CustomElement}.ce.vuefile must be the<TeleportWrapper>component (located at/src/components/BaseCustomElement.vue) and it must wrap a<BaseCustomElement>component, which then wraps all other content within the template (this enables style injection for child components). -
The rest of the element's functionality should live within a child component (see existing examples) located in the
src/components/directory and should not have anypropsof its own; thepropsfrom the parent{PascalCaseName}.ce.vueare injected withprovide/inject(required). -
Custom elements must be added to the following path
/src/elements/{kebab-case-element-name}/{PascalCaseElementName}.ce.vue -
Custom elements must have an export function added in the
/src/elements/index.tsfile that exports the registration function for the element. Note the proper names/paths in the file. -
The registration function (created in Step 5) must be imported and called in
/src/index.ts(as well as in/sandbox/elements/index.tsfor testing). -
A corresponding
{PascalCaseName}.spec.tsfile must be created in the same directory as the custom element to provide Cypress Component Test Runner code coverage. -
Custom element templates (the contents of the
{PascalCaseElementName}.ce.vuefile) must utilize the template shown below:Click to view the starter Custom Element template
<template> <TeleportWrapper :parent-props="$props"> <!-- required --> <BaseCustomElement> <!-- required --> <!-- Components from /src/components may be used in this default slot --> <ExampleComponent @example-event="(emitData: any) => $emit('example-event', emitData)" /> </BaseCustomElement> </TeleportWrapper> </template> <script lang="ts"> import { defineComponent, computed, provide } from 'vue' import BaseCustomElement from '@/components/BaseCustomElement.vue' import ExampleComponent, { exampleComponentEmits } from '@/components/ExampleComponent.vue' import TeleportWrapper from '@/components/TeleportWrapper.vue' export default defineComponent({ name: 'KongAuthExampleElement', // Props are defined here for use on the custom element tag, and all elements MUST have at least 1 prop props: { /* Required */ wrapperId: { type: String, required: false, default: 'kong-auth-example-element', } }, // Import emits from child component with validation, where necessary. See existing components for examples. emits: exampleComponentEmits, components: { TeleportWrapper, BaseCustomElement, }, setup(props, { emit }) { // Provide custom element props to child components - this allows all props to remain reactive provide( 'example-prop', computed((): string => (props.exampleProp ? props.exampleProp : '')), ) }, }) </script> <style lang="scss" scoped> // No styles should be added to this component. </style>
Styles are auto-injected into the shadow DOM for any internal components and child components.
In order for the styles to be injected, you need to place the exact comment (shown below) in ALL <style> blocks that are located inside a component within the /src/ directory.
/*! KONG_AUTH_INJECT_STYLES */The exclamation point at the beginning of the comment flags the comment as important to PurgeCSS and prevents it from being removed during the build. Here's an example
Note: No styles should be placed in the
<style>blocks within thesrc/elements/**/{CustomElement}.vuefiles.
You must put element/component styles into the /src/assets/styles/_elements.scss file.
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 commitThis will trigger the Commitizen interactive prompt for building your commit message.
Lefthook is used to manage Git Hooks within the repo. A commit-msg hook is automatically setup that enforces commit message stands with commitlint, see lefthook.yaml.
A pre-push hook is configured to run Stylelint and ESLint before pushing your changes to the remote repository.
We recommend using VSCode along with the Volar extension.
By default, the UI runs against a remote DEV backend.
To utilize the remote backend, first duplicate the .env.local.example file and rename it to .env.local
# Execute from the project root
cp .env.local.example .env.localAfter adding this new env file, your local frontend will utilize the DEV environment APIs.
The same process can/should be repeated for the .env.local.example to utilize the preview:components and preview:elements commands.
Ensure you pull down the lastest from the main branch and then install dependencies, making sure not to update the lockfile.
yarn install --frozen-lockfileImport elements as Vue components and utilize Vue Dev Tools during development (may require additional imports in /sandbox/components/ComponentsApp.vue).
Note: This will not allow testing embedded styles and other Custom Element features.
yarn dev:componentsBuild the /sandbox/components app and preview locally (requires copying the .env.local.example to .env.local and configuring the DEV or PROD KAuth URL).
yarn preview:componentsImport elements as native HTML Web Components (may require additional imports in /sandbox/elements/index.ts).
Note: This will not allow you to utilize Vue Dev Tools in the browser (custom elements are not currently supported).
yarn dev:elementsBuild the /sandbox/elements app and preview locally (requires copying the .env.local.example to .env.local and configuring the DEV or PROD KAuth URL).
yarn preview:elementsThe web components sandbox is different from the components and elements sandboxes in that it first builds the actual package exports and then registers the elements as native Web Components. See the /sandbox/web-components directory.
Build the /sandbox/web-components app and preview locally (requires copying the .env.local.example to .env.local and configuring the DEV or PROD KAuth URL).
yarn preview:web-componentsyarn buildInside @kong/kong-auth-elements run
yarn linkNext, inside of the local consuming project run this command from the project root.
yarn link "@kong/kong-auth-elements"When you're finish testing locally, don't forget to run the unlink command and reinstall dependencies in your host application.
yarn unlink "@kong/kong-auth-elements"There is currently an issue in Vue 3 custom elements (which we are using here) whereby with our setup, all src/elements/**/{CustomElement}.ce.vue files within the /src/elements/ directory MUST have at least one prop defined. I'm still looking into why.
This in no way impacts production or using kong-auth-elements within your application; all elements have at least one prop defined.
This package depends on axios; specifically a minimum version of 0.27.2. If your project is pinned to a version of axios less than 0.27.2 you will need to upgrade to prevent type interface conflicts.