# aws/jsii: publishing one TypeScript library as Python, Java and .NET packages

> jsii turns a TypeScript class library into assemblies that other languages can consume, and it is the machinery behind the AWS CDK's polyglot releases. Here is what the toolchain actually contains, how to install it, and where it stops being the right answer.

**aws/jsii** — 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!

- Repository: https://github.com/aws/jsii
- Website: https://aws.github.io/jsii
- Stars: 2,869 · Forks: 265
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/aws-jsii

## The problem jsii solves is distribution, not compilation

Writing a library in TypeScript is easy. Handing that library to a Java team, a Python team and a C# team is not. The usual answers are to reimplement the library per language, to publish a thin HTTP service, or to publish raw JavaScript and ask every consumer to call into it through a host-language bridge. The README states the project's position plainly: jsii allows code in any language to naturally interact with JavaScript classes, and it is the technology that enables the AWS Cloud Development Kit to deliver polyglot libraries from a single codebase.

The audience is library authors, not application developers. If you are building constructs, an SDK surface, or any class-based API that other teams will consume from more than one language, jsii is aimed at you. If you are writing an application that happens to use TypeScript, nothing here applies. The unit of work is a published package, and the payoff only arrives when that package has consumers outside the JavaScript ecosystem.

## What the toolchain actually contains, and why it is split across repositories

The README is explicit that the jsii toolchain is spread out on multiple repositories. The compiler is maintained in aws/jsii-compiler. The jsii-rosetta sample code transliteration tool is maintained in aws/jsii-rosetta. Everything else lives in aws/jsii: the runtime libraries for the supported target languages, @jsii/spec (the package that defines the .jsii assembly specification), jsii-pacmak (the bindings generator), jsii-reflect (a higher-level way to process .jsii assemblies) and jsii-config (an interactive tool to help configure a jsii package).

That split matters when you file an issue or read release notes, because a version bump in one repository does not imply a change in the others. The repository package.json confirms the shape of the monorepo: it is private, versioned 0.0.0, with Yarn workspaces covering packages/*, packages/@fixtures/*, packages/@jsii/*, packages/@scope/* and tools/*, and it pins packageManager to yarn@4.13.0. The build script runs yarn constraints --fix and then lerna run build with --concurrency=1, so packages build one at a time in dependency order rather than in parallel.

The central artifact is the .jsii assembly, a JSON description of the library's types produced by the compiler. jsii-pacmak consumes that assembly and generates the language bindings. The runtime libraries are what the generated bindings call at execution time, which is why a generated Python or Java package still needs a Node.js process underneath it.

## Installing the compiler and producing a first assembly

The README points readers to the documentation website at aws.github.io/jsii and to npm for the jsii package, whose badge links to npmjs.com/package/jsii. The compiler itself is maintained in aws/jsii-compiler, so the install target is the jsii package on npm. The README does not print an install command, and the repository's own scripts are build tooling rather than consumer instructions, so the exact command is something to take from the documentation website rather than from this page. The same applies to the compiler invocation and to jsii-pacmak: the README documents what these tools are and which repository maintains them, not the flags you pass.

What the README does establish is the shape of the workflow. You configure a jsii package, which is what jsii-config exists to help with as an interactive tool. The compiler reads your TypeScript and emits a .jsii assembly into an output directory. jsii-pacmak then reads that assembly and generates the bindings. The repository layout supports this reading: packages/@jsii/* holds the spec and tooling packages, and tools/* holds supporting tooling such as the compliance reporter referenced by the root test script.

If the compiler rejects a construct, that rejection is the type model telling you the API cannot be expressed in every target language. The fix belongs in your TypeScript, not in the generated output.

## Generating the Python, Java and .NET packages with jsii-pacmak

The assembly is not a distributable package. jsii-pacmak is the bindings generator that turns it into one, and the README lists it among the pieces maintained in this repository. Because the README does not print a canonical command line for it, the flags that match your configured targets come from the documentation website at aws.github.io/jsii.

The generated packages depend on the jsii runtime libraries for the supported target languages, which are also maintained in this repository. That dependency is the part teams underestimate. A Python consumer installs your generated package, and that package starts a Node.js process to execute the original TypeScript. The polyglot surface is real, but it is a bridge, not a rewrite. Startup cost, process management and the presence of a Node.js runtime on the consumer's machine are all consequences of that design, and none of them are documented away.

One operational detail from the repository is worth carrying over to your own project: the root build runs packages sequentially with --concurrency=1, and the test script does the same before running the compliance report. Serial execution is a deliberate choice in a workspace where packages depend on each other's build output, and a consumer pipeline that generates bindings for several targets faces the same ordering constraint.

## The type model is the constraint, and it rejects more than TypeScript does

jsii is not a general TypeScript-to-anything transpiler. It compiles a subset of TypeScript whose types can be represented in every supported target language, and the compiler enforces that subset at build time. Constructs that have no faithful equivalent across Python, Java and .NET are refused rather than approximated, which is the correct engineering choice and also the most common source of friction for authors migrating an existing codebase.

A second limitation follows from the architecture. Because generated bindings call into a Node.js runtime, jsii is the wrong tool for anything that must run without a JavaScript runtime present, for performance-sensitive inner loops where a cross-language call sits on the hot path, and for libraries whose public surface is mostly free functions and plain data rather than classes. The README frames the value in terms of classes specifically, and that framing is accurate: the model is class-oriented.

Finally, the split toolchain is an operational cost. A bug in the compiler is filed against aws/jsii-compiler, a bug in sample transliteration against aws/jsii-rosetta, and a bug in bindings generation or the runtime against aws/jsii. Determining which repository owns a failure is the first step of every investigation.

## How jsii differs from writing the bindings yourself

The obvious alternative is to keep the TypeScript library as the source of truth and hand-write a Python wrapper, a Java wrapper and a .NET wrapper around it. That approach gives you complete control over each language's idioms: you can expose Pythonic iteration, Java generics and C# properties exactly as each community expects them. You also own four codebases, four release processes and four sets of tests, and every API change has to be applied four times. jsii trades that control for a single source of truth and a generated surface that is consistent across languages rather than idiomatic in each.

A second alternative is to expose the functionality as a network service and let each language use an HTTP client. That removes the Node.js runtime dependency from consumers entirely and works from any language, including ones jsii does not target. The cost is that you now operate a service, and consumers lose the ability to use the library offline or embed it in a process. For a library like a CDK construct collection, which is meant to be composed in-process by the consumer's own code, a service is not a substitute.

jsii-rosetta addresses a narrower problem in the same space: keeping the sample code in your documentation accurate across languages by transliterating examples rather than maintaining one snippet per language by hand.

## Licence, maintenance and what upgrading involves

The repository package.json declares "license": "Apache-2.0", and the LICENSE and NOTICE files sit at the top level of the repository. Apache-2.0 permits commercial use and modification and includes an express patent grant; the NOTICE file is the part that carries attribution obligations when you redistribute, so read it rather than assuming the licence line is the whole story. This is not legal advice, and generated bindings inherit the licensing posture of the code you compiled plus whatever the runtime libraries impose.

On maintenance: the repository is not archived, and the last push was on 2026-09-23. The most recent release listed is v1.140.0 on 2026-08-24, preceded by v1.139.0 on 2026-07-17 and v1.138.0 on 2026-07-02. The version numbering is worth noting for upgrade planning: the project is in the 1.x line, and the release cadence shown by those three releases is roughly monthly, so pinning a minor version and reviewing the changelog at each bump is a reasonable posture. CHANGELOG.md is present at the top level, and the root package.json exposes an upgrade:jsii script backed by scripts/upgrade-jsii.sh, which is the project's own mechanism for moving a consumer forward. Because the compiler, the runtime and the bindings generator live in separate repositories, verify that the versions you install are compatible with each other before upgrading any single one.

## Conclusion

Adopt jsii if you maintain a TypeScript class library and genuinely need Python, Java or .NET consumers to call it as an idiomatic package, and you accept that the compiler lives in a separate repository from the runtime and bindings generator you install from npm. Do not adopt it for a plain Node.js library, a CLI, or anything that depends on TypeScript features the jsii type model does not express, since the compiler will reject those constructs rather than translate them. Verify first which repository owns the piece you need: aws/jsii-compiler holds the compiler, aws/jsii-rosetta holds the sample transliteration tool, and aws/jsii holds the runtime libraries, @jsii/spec, jsii-pacmak, jsii-reflect and jsii-config. The last push to aws/jsii was on 2026-09-23, and the newest release listed is v1.140.0 from 2026-08-24.

## FAQ

### What is aws/jsii?

It is a toolchain that lets code in other languages interact with JavaScript classes, and it is what the AWS Cloud Development Kit uses to publish polyglot libraries from one TypeScript codebase. A TypeScript class library can then be consumed from Python, Java, C# and other .NET family languages as well as JavaScript and TypeScript.

### What is the aws/jsii compiler and where is it maintained?

The compiler is the piece that reads your TypeScript and emits the .jsii assembly. It is not in this repository: the README states that aws/jsii-compiler is where the jsii compiler is maintained.

### What does jsii-pacmak do?

jsii-pacmak is the bindings generator for jsii packages, and it is maintained in the aws/jsii repository. It consumes the .jsii assembly and produces the language-specific packages, which depend on the jsii runtime libraries for the supported target languages.

### Do I need Node.js installed to use a package generated by jsii?

The generated bindings call the jsii runtime libraries, which execute the original JavaScript. The README describes jsii as letting other languages interact with JavaScript classes, so a JavaScript runtime is part of the execution path rather than something the generated package removes.

### Is aws/jsii the same thing as the AWS CDK?

No. The README describes jsii as the technology that enables the AWS CDK to deliver polyglot libraries from a single codebase, so jsii is the underlying toolchain rather than the CDK itself.

## Sources

- [aws/jsii on GitHub](https://github.com/aws/jsii)
- [License: Apache-2.0](https://github.com/aws/jsii/blob/main/LICENSE)
- [Project website](https://aws.github.io/jsii)
- [README](https://github.com/aws/jsii/blob/main/README.md)
- [Releases](https://github.com/aws/jsii/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aws-jsii