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,
jsiimodules 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!
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 hello-jsii@1.0.0 No description
npm WARN hello-jsii@1.0.0 No repository field.
+ jsii-pacmak@0.14.3
+ jsii@0.14.3
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
> hello-jsii@1.0.0 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
│ └── hello-jsii@1.0.0.jsii.tgz
└── 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.
Contributing
See CONTRIBUTING.
License
jsii is distributed under the Apache License, Version 2.0.
3 maintainers
Metadata
3 maintainers
Release files for jsii 1.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| jsii-1.3.2.tar.gz | 262.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jsii-1.3.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 525.0 kB
Release files / jsii-1.3.2.tar.gz
| Download URL | jsii-1.3.2.tar.gz |
|---|---|
| Size | 262.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e2a8c5aea6d21858746b18189916d8ffb114703fbcb1372f97c357b6dfb8bdb
|
|
BLAKE2b-256 checksum How to use checksums |
cbcc42331cc5dc0405e558cadda5a2885eeed18212a47f1d3c8e42551670c59c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.6.5
|
Release files / jsii-1.3.2-py3-none-any.whl
| Download URL | jsii-1.3.2-py3-none-any.whl |
|---|---|
| Size | 263.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a72f043f8823966e9eacaeb429a657e3a04080ffd0f1994adf705ec3db0b880
|
|
BLAKE2b-256 checksum How to use checksums |
aebd656acbdf92e26887e114492fd56b83e525f0431021f510493dd3a9b768d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.45.0 CPython/3.6.5
|
