Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.2.x
  • Home icon
  • Kong Gateway
  • Plugin Development
  • Pluginserver
  • Plugins in Other Languages Javascript
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Install
  • Development
  • Phase handlers
  • PDK functions
  • Plugin dependencies
    • Testing
  • More Information
You are browsing documentation for an outdated version. See the latest documentation here.

Plugins in Other Languages Javascript

Kong Gateway support for the JavaScript language is provided by the JavaScript PDK. The library provides a plugin server that provides a runtime for JavaScript bindings for Kong Gateway.

TypeScript is also supported in the following ways:

  • The PDK includes type definitions for PDK functions that allow type checking when developing plugins in TypeScript.
  • Plugins written in TypeScript can be loaded directly to Kong Gateway and transpiled.

Install

JavaScript PDK can be installed using npm. To install the plugin server binary globally:

npm install kong-pdk -g

Development

A valid JavaScript plugin implementation should export the following object:

module.exports = {
  Plugin: KongPlugin,
  Schema: [
    { message: { type: "string" } },
  ],
  Version: '0.1.0',
  Priority: 0,
}
  • The Plugin attribute defines the class that implements this plugin.
  • The Schema defines the configuration schema of the plugin.
  • Version and Priority variables set to the version number and priority of execution.

Note: This repository contains examples of plugins built with JavaScript.

Phase handlers

You can implement custom logic to be executed at various points in the request processing lifecycle. To execute custom JavaScript code in the access phase, define a function named access:

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    // ...
  }
}

You can implement custom logic during the following phases using the same function signature:

  • certificate
  • rewrite
  • access
  • response
  • preread
  • log

The presence of the response handler automatically enables the buffered proxy mode.

PDK functions

Kong interacts with the PDK through network-based inter-rocess communication. Each function returns a promise instance. You can use async/await keywords in the phase handlers for better readability.

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    let host = await kong.request.getHeader("host")
    // do something to host
  }
}

Alternatively, use the then method to resolve a promise:

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    kong.request.getHeader("host")
      .then((host) => {
        // do something to host
      })
  }
}

Plugin dependencies

When using the plugin server, plugins are allowed to have extra dependencies, as long as the directory that holds plugin source code also includes a node_modules directory.

Assuming plugins are stored under /usr/local/kong/js-plugins, the extra dependencies are then defined in /usr/local/kong/js-plugins/package.json. Developers also need to run npm install under /usr/local/kong/js-plugins to install those dependencies locally into /usr/local/kong/js-plugins/node_modules.

The Node.js version and architecture that runs the plugin server and the one that runs npm install under plugins directory must match.

Testing

The JavaScript PDK provides a mock framework to test plugin code using jest.

Install jest as a development dependency, then add the test script in package.json:

npm install jest --save-dev

The package.json contains information like this:

{
  "scripts": {
    "test": "jest"
  },
  "devDependencies": {
    "jest": "^26.6.3",
    "kong-pdk": "^0.3.2"
  }
}

Run the test through npm with:

npm test

This repository contains examples of writing tests with jest.

More Information

  • PDK Reference
  • Plugins with Containers
  • Develop plugins with Python
  • Develop plugins with Go
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023