Registry / aws / jsii-rosetta

jsii-rosetta

library5.9.39jsnpmunverified

The `jsii-rosetta` library, currently at version 5.9.39, is an essential tool within the `jsii` ecosystem, developed by AWS. Its core purpose is to translate code snippets written in one `jsii`-supported language (primarily TypeScript) into other target languages such as Python, Java, C#, and Go. This functionality is crucial for projects like the AWS Cloud Development Kit (CDK), enabling documentation to display examples across various programming languages from a single source. `jsii-rosetta` maintains a rapid and continuous release cadence, frequently updating its internal `jsii` and TypeScript dependencies to ensure compatibility and leverage the latest `jsii` features. Its key differentiator is its specialized focus on `jsii`-compliant code translation, providing robust tools for syntax analysis, type resolution, and idiomatic translation across multiple language runtimes.

aws serialization devops

npm install jsii-rosetta

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSII-ROSETTA

jsii-rosetta

awsjavascriptv5.9.39

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Rosetta

✓ import { Rosetta } from 'jsii-rosetta';

✗ const Rosetta = require('jsii-rosetta').Rosetta;

The primary class for initiating and managing code translations. Always prefer ESM imports for modern Node.js and TypeScript environments.

TargetLanguage

✓ import { TargetLanguage } from 'jsii-rosetta';

✗ import { LANGUAGES } from 'jsii-rosetta';

An enum defining the available target languages for translation, such as PYTHON, JAVA, CSHARP, and GO.

renderTypeScriptSnippet

✓ import { renderTypeScriptSnippet } from 'jsii-rosetta';

A utility function that can directly render a TypeScript snippet into a target language, often used for simpler, direct translations without instantiating the full `Rosetta` class.

This example demonstrates how to initialize the `Rosetta` translator and translate a TypeScript AWS CDK code snippet into Python and Java, handling potential translation failures.

import { Rosetta, TargetLanguage } from 'jsii-rosetta'; async function translateCode() { const rosetta = new Rosetta(); const tsSnippet = ` import * as cdk from 'aws-cdk-lib'; import * as ec2 from 'aws-cdk-lib/aws-ec2'; const app = new cdk.App(); const stack = new cdk.Stack(app, 'MyStack'); new ec2.Vpc(stack, 'MyVpc', { maxAzs: 2, natGateways: 1, }); app.synth(); `; // Translate to Python const pythonTranslation = await rosetta.translateTypeScript(tsSnippet, { language: TargetLanguage.PYTHON, trimLeadingEmptyLines: true, indentation: 4, }); if (pythonTranslation.translation) { console.log('Python Code:\n', pythonTranslation.translation.source); } else if (pythonTranslation.didFail) { console.error('Python translation failed:', pythonTranslation.failure); } // Translate to Java const javaTranslation = await rosetta.translateTypeScript(tsSnippet, { language: TargetLanguage.JAVA, trimLeadingEmptyLines: true, indentation: 4, }); if (javaTranslation.translation) { console.log('\nJava Code:\n', javaTranslation.translation.source); } else if (javaTranslation.didFail) { console.error('Java translation failed:', javaTranslation.failure); } } translateCode().catch(console.error);

jsii-rosetta --version

Debug

Known issues

breaking`jsii-rosetta` is tightly coupled with its internal `jsii` and TypeScript dependencies. Upgrading `jsii` in your project without also updating `jsii-rosetta` can lead to build failures or incorrect translations due to API mismatches.

fix

Always ensure your `jsii-rosetta` version is compatible with your project's `jsii` and `typescript` versions. Refer to the `jsii-rosetta` release notes and `jsii` compatibility matrix.

affects: >=3.0.0

gotchaThe `engines` field in `package.json` specifies a minimum Node.js version. Using an older Node.js version will result in errors and prevent `jsii-rosetta` from functioning correctly.

fix

Ensure your Node.js environment meets or exceeds the specified minimum version (currently `>= 20.16.0`). Use a Node.js version manager like `nvm` to easily switch versions.

affects: >=5.0.0

gotchaWhile `jsii-rosetta` aims for accurate translation, highly complex or non-idiomatic TypeScript code (e.g., extensive use of `any`, advanced generics without clear type boundaries, or intricate conditional types) may result in less accurate or failing translations in target languages.

fix

Design `jsii` constructs with clarity and strong typing. Test translations for complex snippets. Simplify TypeScript patterns where direct translation might be ambiguous or non-idiomatic in target languages.

affects: >=1.0.0

gotchaWhen running `jsii-rosetta` programmatically, ensure all `jsii` dependencies required by the snippets being translated are correctly installed and available in the environment where `jsii-rosetta` executes. Missing dependencies will cause type resolution failures during translation.

fix

Install all necessary `jsii` packages (e.g., `aws-cdk-lib`) as `devDependencies` or `dependencies` in your project. If running in a separate context, ensure the `node_modules` are properly resolved or paths configured.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'jsii-rosetta' or its corresponding type declarations.

The `jsii-rosetta` package is not installed, or there's an issue with module resolution in your build system (e.g., TypeScript configuration).

fix

Run `npm install jsii-rosetta` or `yarn add jsii-rosetta`. Verify your `tsconfig.json` includes `node_modules` in its `typeRoots` or `moduleResolution` settings.

TypeError: rosetta.translateTypeScript is not a function

This usually indicates that `Rosetta` was not correctly imported or instantiated, or an outdated version of `jsii-rosetta` is being used where the API might differ.

fix

Ensure you are using `import { Rosetta } from 'jsii-rosetta';` and instantiate it with `new Rosetta()`. Check `jsii-rosetta` documentation for API changes if using an older version.

The Rosetta kernel failed to initialize. Make sure you have a compatible jsii-runtime installed.

The internal `jsii` runtime that `jsii-rosetta` depends on could not be found or is incompatible with the installed `jsii-rosetta` version, often due to Node.js version or `jsii` package mismatches.

fix

Ensure your Node.js version meets the `jsii-rosetta` requirements (e.g., `>= 20.16.0`). Reinstall `jsii-rosetta` to ensure all its peer dependencies, including the `jsii-runtime`, are correctly linked.

TypeScript diagnostics: Cannot find name 'cdk' (or similar for other `jsii` types)

The `jsii-rosetta` instance cannot resolve types from `jsii`-generated libraries (like `aws-cdk-lib`) that are used in the snippet being translated.

fix

Ensure that the `jsii` packages referenced in your code snippets are installed in your project's `node_modules` (e.g., `npm install aws-cdk-lib`). If running programmatically, you might need to specify a `projectRoot` in `Rosetta`'s options for proper module resolution.

Upgrade

Version history

5.9.39latest on npm

Audit

Dependencies

jsiirequired`jsii-rosetta` is an integral part of the `jsii` ecosystem, relying heavily on `jsii` for understanding type systems, metadata, and runtime conventions during code translation.

typescriptrequiredTypeScript is the primary source language for `jsii` constructs and `jsii-rosetta` utilizes TypeScript's compiler API for parsing, type checking, and detailed code analysis before translation.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/aws/jsii-rosetta ↗

packagehttps://www.npmjs.com/package/jsii-rosetta ↗

homepagehttps://aws.github.io/jsii ↗