Overview

jsii allows code in any language to naturally interact with JavaScript classes. It is the technology that enables the AWS Cloud Development Kit to deliver polyglot libraries from a single codebase!

A class library written in TypeScript can be used in projects authored in TypeScript or Javascript (as usual), but also in Python, Java, C# (and other languages from the .NET family), ...

NOTE: Due to performance of the hosted Javascript engine and marshaling costs, jsii modules are best suited for development and build tools, as opposed to performance-sensitive or resource-constrained applications.

See Runtime Architecture for more information.

An example is worth a thousand words

Consider the following TypeScript class:

export class HelloJsii {
  public sayHello(name: string) {
    return `Hello, ${name}!`;
  }
}

By compiling our source module using jsii, we can now package it as modules in one of the supported target languages. Each target module has the exact same API as the source. This allows users of that target language to use HelloJsii like any other class:

• In Python:

  hello = HelloJsii()
  hello.say_hello("World"); # => Hello, World!

• In Java

  final HelloJsii hello = new HelloJsii();
  hello.sayHello("World"); // => Hello, World!

• In C#

  var hello = new HelloJsii();
  hello.SayHello("World"); // => Hello, World!

• ... and more to come!

Toolchain

jsii consists of multiple single-purposed programs which can be used to compose various workflows.

We are considering creating an "umbrella entrypoint" to make it easier to consume.

Name	Stability	Description
jsii	Stable	Compiles TypeScript to jsii module
jsii-pacmak	Stable	Creates ready-to-publish language-specific packages from jsii modules
jsii-reflect	Stable	Strong-typed reflection library for jsii type systems
jsii-diff	Stable	API backwards compatibility checker
jsii-rosetta	Experimental	Transpile code snippets (in docs) from TypeScript to jsii languages
jsii-config	Experimental	Interactive tool for generating jsii configuration
jsii-release	Community	Publishes jsii modules to all supported package managers
jsii-srcmak	Community	Generates relocatable source code in jsii languages from typescript
jsii-docgen	Community	Generates markdown API documentation for jsii modules

"Community": a community-maintained project, not officially supported by the jsii team.

Getting Started

Let's create our first jsii TypeScript module (actual outputs may slightly differ):

$ mkdir hello-jsii
$ cd hello-jsii
$ npm init -y
Wrote to /tmp/hello-jsii/package.json:

{
  "name": "hello-jsii",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}
$ npm i --save-dev jsii jsii-pacmak
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN [email protected] No description
npm WARN [email protected] No repository field.

+ [email protected]
+ [email protected]
added 65 packages from 54 contributors and audited 191 packages in 7.922s
found 0 vulnerabilities

Edit the package.json file:

/// package.json
{
  // ...
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "scripts": {
    "build": "jsii",
    "build:watch": "jsii -w",
    "package": "jsii-pacmak"
  },
  "jsii": {
    "outdir": "dist",
    "targets": {
      "python": {
        "distName": "acme.hello-jsii",
        "module": "acme.hello_jsii"
      },
      "java": {
        "package": "com.acme.hello",
        "maven": {
          "groupId": "com.acme.hello",
          "artifactId": "hello-jsii"
        }
      },
      "dotnet": {
        "namespace": "Acme.HelloNamespace",
        "packageId": "Acme.HelloPackage"
      }
    }
  },
  "author": {
    "name": "John Doe"
  },
  "repository": {
    "url": "https://github.com/acme/hello-jsii.git"
  }
  // ...
}

Read more about what those configuration entries do in the configuration documentation.

Okay, we are ready to write some code. Create a lib/index.ts file:

/// lib/index.ts
export class HelloJsii {
  public sayHello(name: string) {
    return `Hello, ${name}!`;
  }
}

Build your module:

$ npm run build

If build succeeds, you will see the resulting lib/index.js and lib/index.d.ts files were produced, as well as the .jsii file (contents may vary):

/// .jsii
{
  "author": {
    "name": "John Doe",
    "roles": [
      "author"
    ]
  },
  "description": "hello-jsii",
  "homepage": "https://github.com/acme/hello-jsii.git",
  "jsiiVersion": "0.14.3 (build 1b1062d)",
  "license": "ISC",
  "name": "hello-jsii",
  "repository": {
    "type": "git",
    "url": "https://github.com/acme/hello-jsii.git"
  },
  "schema": "jsii/0.10.0",
  "targets": {
    "dotnet": {
      "namespace": "Acme.HelloNamespace",
      "packageId": "Acme.HelloPackage"
    },
    "java": {
      "maven": {
        "artifactId": "hello-jsii",
        "groupId": "com.acme.hello"
      },
      "package": "com.acme.hello"
    },
    "js": {
      "npm": "hello-jsii"
    },
    "python": {
      "distName": "acme.hello-jsii",
      "module": "acme.hello_jsii"
    }
  },
  "types": {
    "hello-jsii.HelloJsii": {
      "assembly": "hello-jsii",
      "fqn": "hello-jsii.HelloJsii",
      "initializer": {},
      "kind": "class",
      "locationInModule": {
        "filename": "lib/index.ts",
        "line": 1
      },
      "methods": [
        {
          "locationInModule": {
            "filename": "lib/index.ts",
            "line": 2
          },
          "name": "sayHello",
          "parameters": [
            {
              "name": "name",
              "type": {
                "primitive": "string"
              }
            }
          ],
          "returns": {
            "type": {
              "primitive": "string"
            }
          }
        }
      ],
      "name": "HelloJsii"
    }
  },
  "version": "1.0.0",
  "fingerprint": "XYWYOiOupH4MmIjFj84wTSRfWqSw8hW37vHkVMO7iuY="
}

This file includes all the information needed in order to package your module into every jsii-supported language. It contains the module metadata from package.json and a full declaration of your module's public API.

Okay, now the magic happens:

$ npm run package

> [email protected] package /Users/rmuller/Development/Demos/hello-jsii
> jsii-pacmak -v

[jsii-pacmak] [INFO] Building hello-jsii (python,java,dotnet,js) into dist
[jsii-pacmak] [INFO] Packaged. java (4.3s) | dotnet (2.0s) | python (0.9s) | npm pack (0.5s) | js (0.0s)

Now, if you check out the contents of dist, you'll find:

dist
├── dotnet
│   ├── Acme.HelloPackage.1.0.0.nupkg
│   └── Acme.HelloPackage.1.0.0.symbols.nupkg
├── java
│   └── com
│       └── acme
│           └── hello
│               └── hello-jsii
│                   ├── 1.0.0
│                   │   ├── hello-jsii-1.0.0-javadoc.jar
│                   │   ├── hello-jsii-1.0.0-javadoc.jar.md5
│                   │   ├── hello-jsii-1.0.0-javadoc.jar.sha1
│                   │   ├── hello-jsii-1.0.0-sources.jar
│                   │   ├── hello-jsii-1.0.0-sources.jar.md5
│                   │   ├── hello-jsii-1.0.0-sources.jar.sha1
│                   │   ├── hello-jsii-1.0.0.jar
│                   │   ├── hello-jsii-1.0.0.jar.md5
│                   │   ├── hello-jsii-1.0.0.jar.sha1
│                   │   ├── hello-jsii-1.0.0.pom
│                   │   ├── hello-jsii-1.0.0.pom.md5
│                   │   └── hello-jsii-1.0.0.pom.sha1
│                   ├── maven-metadata.xml
│                   ├── maven-metadata.xml.md5
│                   └── maven-metadata.xml.sha1
├── js
│   └── [email protected]
└── python
    ├── acme.hello-jsii-1.0.0.tar.gz
    └── acme.hello_jsii-1.0.0-py3-none-any.whl

These files are ready-to-publish artifacts for each target language. You can see the npm tarball under js, the python package under python, the Maven repo under java, etc...

That's it. You are ready to rock!

Features

Source Languages

• TypeScript with some restrictions

Target Languages

• Javascript - generates an NPM package implicitly (no configuration required).
• Python - generates a ready-to-publish PyPI package.
• Java - generates a ready-to-publish Maven package.
• .NET - generates a ready-to-publish NuGet package.

See the configuration documentation for more information on configuring the various targets.

📖 Blog Posts

Here's a collection of blog posts (in chronological order) related to jsii:

• 2020-01-11: How to Create CDK Constructs, by Matthew Bonig
• 2020-05-27: Generate Python, Java, and .NET software libraries from a TypeScript source, by Hari Pachuveetil

ℹ️ If you wrote blog posts about jsii and would like to have them referenced here, do not hesitate to file a pull request to add the links here!

⚙️ Contributing

See CONTRIBUTING.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

AWS CDK Automation 🚧 👀	Aaron Costley 🐛 💻 🥅 🤔 👀	Abdallah Hodieb 🐛	Adam Ruka 🐛 💻 🚧 👀	Alex Pulver 🐛	Andy Slezak 💻	Anshul Guleria 🤔
Ari Palo 🤔	Bartłomiej Jurek 🐛	Ben Walters 🤔	Benjamin Maizels 💻 👀	Bill Cauchois 🤔	Brecht Verhoeve 🤔	Breland Miley 💻
CaerusKaru 💻 🚧	Campion Fellin 💻 ☕️	Carter Van Deuren 🐛	Christopher Currie 💻 🤔	CyrusNajmabadi 🐛 🤔	Daniel Dinu 🐛 💻	Daniel Schroeder 🐛 💻 📖 🤔 🚧
Dave Slotnick 🐛	Donald Stufft 🐛 💻 🤔 🐍 👀	Dongie Agnir 💻 ☕️ 👀	Eduardo Sena S. Rosa 🐛	Elad Ben-Israel 🐛 💻 🤔 ☕️ 🚧 👀 📢	Eli Polonsky 🐛 💻 🤔 🚧 👀	Eric Z. Beard 📆
Erik Karlsson 🐛	Eugene Kozlov 💻	Fabio Gentile 🐛	Florian Eitel 🤔	Graham Lea 🤔 👀	Hamza Assyad 🐛 💻 🥅 🤔 👀	Hari Pachuveetil 📝
Hsing-Hui Hsu 💻 📖 🚶‍♀️ 🤔 👀	James Mead 💻	James Siri 💻 🚧	Jason Del Ponte 🚶‍♀️ 🤔 👀	Jason Fulghum 🤔 📆 👀	Jerry Kindall 📖 🤔	Jimmy Gaussen 🤔
Jon Steinich 🐛 🤔	Joseph Lawson 👀	Joseph Martin 🐛	Junix 🐛	Justin Taylor 🐛	Kyle Thomson ☕️ 👀	Leandro Padua 🐛
Maja S Bratseth 🐛	Marcos Diez 🐛	Matthew Bonig 🐛 📝	Matthew Pirocchi 💻 🥅 🤔 👀	Mike Lane 🐛	Mitch Garnaat 🐛 💻 🤔 🐍 👀	Mitchell Valine 🐛 💻 🚶‍♀️ 🤔 🚧 👀
Neta Nir 💻 🤔 🚧 👀	Nick Lynch 🐛 💻 🚧 👀	Niranjan Jayakar 🐛 💻 🤔 🚧 👀	Noah Litov 💻 🚧 👀	PIDZ - Bart 🤔	Petra Barus 💻	Philip Cali 🤔
Quentin Loos 🤔	Raphael 🐛	Richard H Boyd 🐛	Rico Huijbers 🐛 💻 🤔 🚧 🐍 👀	Romain Marcadier 🐛 💻 🎨 🥅 🚶‍♀️ 🤔 ☕️ 🚧 🐍 👀	SADIK KUZU 👀	SK 🤔
Sam Fink 💻 👀	Sam Goodwin 👀	Sebastian Korfmann 🐛 💻 🤔	Shane Witbeck 🤔	Shiv Lakshminarayan 💻 🚧 👀	Somaya 💻 🤔 🚧 👀	The Gitter Badger 💻 🚧
Thomas Poignant 🐛	Thomas Steinbach 🐛	Thorsten Hoeger 💻	Tim Wagner 🐛 🤔	Tobias Lidskog 💻	Ty Coghlan 🐛	Tyler van Hensbergen 🤔
Vlad Hrybok 🐛	Vladimir Shchur 🐛	Yan Zhulanow 💻	ajnarang 🤔	deccy-mcc 🐛	dependabot-preview[bot] 🐛 🚧	dependabot[bot] 🚧
dheffx 🐛	gregswdl 🐛	mergify[bot] 🚧	seiyashima42 🐛 💻 📖	sullis 💻	vaneek 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

⚖️ License

jsii is distributed under the Apache License, Version 2.0.

See LICENSE and NOTICE for more information.