{"id":13602679,"url":"https://github.com/aws/jsii-rosetta","last_synced_at":"2026-03-16T02:45:11.522Z","repository":{"id":88974559,"uuid":"598711841","full_name":"aws/jsii-rosetta","owner":"aws","description":"The jsii sample code transliterator","archived":false,"fork":false,"pushed_at":"2025-04-02T15:08:49.000Z","size":6912,"stargazers_count":23,"open_issues_count":6,"forks_count":13,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-02T20:53:54.694Z","etag":null,"topics":["aws","cdk","constructs","jsii","jsii-rosetta","transpiler","typescript"],"latest_commit_sha":null,"homepage":"https://aws.github.io/jsii","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-07T16:58:46.000Z","updated_at":"2025-04-02T00:31:14.000Z","dependencies_parsed_at":"2024-01-20T02:04:53.069Z","dependency_job_id":"112c59d9-8eb3-4acb-931f-e4d14be9e12b","html_url":"https://github.com/aws/jsii-rosetta","commit_stats":{"total_commits":791,"total_committers":15,"mean_commits":"52.733333333333334","dds":0.08217446270543616,"last_synced_commit":"25c9f3ca25786434bf98c490863abf7179835b37"},"previous_names":[],"tags_count":1799,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fjsii-rosetta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fjsii-rosetta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fjsii-rosetta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fjsii-rosetta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/jsii-rosetta/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246892847,"owners_count":20850850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cdk","constructs","jsii","jsii-rosetta","transpiler","typescript"],"created_at":"2024-08-01T18:01:33.556Z","updated_at":"2026-01-05T07:24:01.421Z","avatar_url":"https://github.com/aws.png","language":"TypeScript","readme":"# ![jsii](https://raw.githubusercontent.com/aws/jsii/main/logo/png/128.png)\n\n[![Join the chat at https://cdk.Dev](https://img.shields.io/static/v1?label=Slack\u0026message=cdk.dev\u0026color=brightgreen\u0026logo=slack)](https://cdk.dev)\n[![Build Status](https://github.com/aws/jsii-rosetta/workflows/build/badge.svg)](https://github.com/aws/jsii-rosetta/actions?query=workflow%3Abuild+branch%3Amain)\n[![npm](https://img.shields.io/npm/v/jsii-rosetta?logo=npm)](https://www.npmjs.com/package/jsii-rosetta)\n\n## Overview\n\n`jsii-rosetta` translates code samples contained in jsii libraries from TypeScript to supported *jsii* target languages.\nThis is what enables the [AWS Cloud Development Kit][cdk] to deliver polyglot documentation from a single codebase!\n\n`jsii-rosetta` leverages knowledge about jsii language translation conventions in order to produce translations. It only\nsupports a limited set of TypeScript language features (which can be reliably represented in other languages).\n\n[cdk]: https://github.com/aws/aws-cdk\n\n## :question: Documentation\n\nHead over to our [documentation website](https://aws.github.io/jsii)!\n\nThe jsii toolchain spreads out on multiple repositories:\n\n- [aws/jsii-compiler](https://github.com/aws/jsii-compiler) is where the `jsii` compiler is maintained (except releases\n  in the `1.x` line)\n- [aws/jsii-rosetta](https://github.com/aws/jsii-rosetta) is where the `jsii-rosetta` sample code transliteration tool\n  is maintained (except releases in the `1.x` line)\n- [aws/jsii](https://github.com/aws/jsii) is where the rest of the toolchain is maintained, including:\n  - `@jsii/spec`, the package that defines the *`.jsii` assembly* specification\n  - `jsii-config`, an interactive tool to help configure your jsii package\n  - `jsii-pacmak`, the bindings generator for jsii packages\n  - `jsii-reflect`, a higher-level way to process *`.jsii` assemblies*\n  - The jsii runtime libraries for the supported jsii target languages\n  - `1.x` release lines of `jsii` and `jsii-rosetta`\n\n## :gear: Maintenance \u0026 Support\n\nThe applicable *Maintenance \u0026 Support policy* can be reviewed in [SUPPORT.md](./SUPPORT.md).\n\nThe current status of `jsii-rosetta` releases is:\n\n| Release | Status      | EOS        | Comment                                                                                                 |\n| ------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- |\n| `5.9.x` | Current     | TBD        | ![npm](https://img.shields.io/npm/v/jsii-rosetta/v5.9-latest?label=jsii-rosetta%40v5.9-latest\u0026logo=npm) |\n| `5.8.x` | Maintenance | 2026-02-15 | ![npm](https://img.shields.io/npm/v/jsii-rosetta/v5.8-latest?label=jsii-rosetta%40v5.8-latest\u0026logo=npm) |\n| `5.7.x` | Maintenance | 2025-09-15 | ![npm](https://img.shields.io/npm/v/jsii-rosetta/v5.7-latest?label=jsii-rosetta%40v5.7-latest\u0026logo=npm) |\n\n## :gear: Contributing\n\nSee [CONTRIBUTING](./CONTRIBUTING.md).\n\n## :school_satchel: Getting Started\n\n## Rosetta for example authors\n\nThis section describes what to pay attention to when writing examples that will be converted\nby Rosetta.\n\n### Making examples compile\n\nThe translator can translate both code that completely compiles and typechecks, as well as code that doesn't.\n\nIn case of non-compiling samples the translations will be based off of grammatical parsing only. This has the downside\nthat we do not have the type information available to the exact thing in all instances. Specifically\nstruct types will not be able to be inferred from object literals. Have a look at the following piece of code:\n\n```ts\nsomeObject.someMethod('foo', {\n  bar: 3,\n});\n```\n\nIn non-TypeScript languages, it is important to know the type of the second\nargument to the method here. However, without access to the definition of\n`someMethod()`, it's impossible for Rosetta to know the type, and hence\nit cannot translate the example. It is therefore important to include necessary\nimports, variable declarations, etc, to give Rosetta enough information to figure\nout what's going on in this code, and the example should read like this:\n\n```ts\nimport * as myLib from 'some-library';\n\ndeclare const someObject: myLib.SomeClass;\n\nsomeObject.someMethod('foo', {\n  bar: 3,\n});\n```\n\n### Enforcing correct examples\n\nBy default, Rosetta will accept non-compiling examples. If you set\n`jsiiRosetta.strict` to `true` in your `package.json`,\nthe Rosetta command will fail if any example contains an error:\n\n```js\n/// package.json\n{\n  \"jsiiRosetta\": {\n    \"strict\": true\n  }\n}\n```\n\n### Fixtures\n\nTo avoid having to repeat common setup every time, code samples can use\n\"fixtures\": a source template where the example is inserted. A fixture must\ncontain the text `/// here` and typically looks like this:\n\n```ts\nconst * as module from '@some/dependency';\n\nclass MyClass {\n  constructor() {\n    const obj = new MyObject();\n\n    /// here\n  }\n}\n```\n\nThe example will be inserted at the location marked as `/// here` and will have\naccess to `module`, `obj` and `this`.  Any `import` statements found in the\nexample will automatically be hoisted at the top of the fixture, where they are\nguaranteed to be syntactically valid.\n\nThe default file loaded as a fixture is called `rosetta/default.ts-fixture` in\nthe package directory (if it exists).\n\nExamples can request an alternative fixture by specifying a `fixture` parameter\nas part of the code block fence:\n\n````text\n```ts fixture=some-fixture\n````\n\nOr opt out of using the default fixture by specifying `nofixture`:\n\n````text\n```ts nofixture\n````\n\nTo specify fixtures in an `@example` block, use an accompanying `@exampleMetadata` tag:\n\n````text\n/**\n * My cool class\n *\n * @exampleMetadata fixture=with-setup\n * @example\n *\n * new MyCoolClass();\n */\n````\n\n### Dependencies\n\nWhen compiling examples, Rosetta will make sure your package itself and all of\nits `dependencies` and `peerDependencies` are available in the dependency\nclosure that your examples will be compiled in.\n\nIf there are packages you want to use in an example that should *not* be part\nof your package's dependencies, declare them in `jsiiRosetta.exampleDependencies`\nin your `package.json`:\n\n```js\n/// package.json\n{\n  \"jsiiRosetta\": {\n    \"exampleDependencies\": {\n      \"@some-other/package\": \"^1.2.3\",\n      \"@yet-another/package\": \"*\",\n    }\n  }\n}\n```\n\nYou can also set up a directory with correct dependencies yourself, and pass\n`--directory` when running `jsii-rosetta extract`. We recommend using the\nautomatic closure building mechanism and specifying `exampleDependencies` though.\n\n## Rosetta for package publishers\n\nThis section describes how Rosetta integrates into your build process.\n\n### Extract\n\nRosetta has a number of subcommands. The most important one is `jsii-rosetta extract`.\n\nThe `jsii-rosetta extract` command will take one or more jsii assemblies,\nextract the snippets from them, will try to compile them with respect to a given\nhome directory, and finally store all translations in something called a\n\"tablet\".\n\nA couple of things to note here:\n\n- Snippets are always read from the jsii assembly. That means if you make\n  changes to examples in source files, you must first re-run `jsii` to\n  regenerate the assembly, before re-running `jsii-rosetta extract`.\n- The compilation directory will be used to resolve `import`s. Currently, you\n  are responsible for building a directory with the correct `node_modules`\n  directories in there so that a TypeScript compilation step will find all\n  libraries referenced in the examples. This is especially revelant if your\n  examples include libraries that depend on the *current* library: it is not\n  uncommon to write examples in library `A` showing how to use it in combination\n  with library `B`, where `B` depends on `A`. However, since by definition `B`\n  *cannot* be in the set of dependencies of `A`, you must build a directory with\n  both `B` and `A` in it somewhere in your filesystem and run Rosetta in that\n  directory.\n- \"Extract\" will compile samples in parallel. The more assemblies you give it\n  at the same time, the more efficient of a job it will be able to do.\n\nThe extract command will write a file named `.jsii.tabl.json` next to every\nassembly, containing translations for all samples found in the assembly. You\nshould include this file in your NPM package when you publish, so that\ndownstream consumers of the package have access to the translations.\n\nAn example invocation of `jsii-rosetta extract` looks like this:\n\n```sh\njsii-rosetta extract --directory some/dir $(find . -name .jsii)\n```\n\n#### Running in parallel\n\nSince TypeScript compilation takes a lot of time, much time can be gained by\nusing the CPUs in your system effectively.  `jsii-rosetta extract` will run the\ncompilations in parallel.\n\n`jsii-rosetta` will use a number of workers equal to half the number of CPU\ncores, up to a maximum of 16 workers. This default maximum can be overridden by\nsetting the `JSII_ROSETTA_MAX_WORKER_COUNT` environment variable.\n\nIf you get out of memory errors running too many workers, run a command like\nthis to raise the memory allowed for your workers:\n\n```sh\n/sbin/sysctl -w vm.max_map_count=2251954\n```\n\n#### Caching\n\nRosetta extract will translate all examples found in `.jsii` and write the\ntranslations to `.jsii.tabl.json`. From compilation to compilation, many of these\nexamples won't have changed. Since TypeScript compilation is a fairly expensive\nprocess, we would like to avoid doing unnecessary work as much as possible.\n\nTo that end, rosetta can reuse translations from a cache, and write\nnew translations into the same cache:\n\n```sh\njsii-rosetta extract \\\n  --directory some/dir \\\n  --cache cache.json \\\n  [--trim-cache] \\\n  $(find . -name .jsii)\n```\n\nThe `--trim-cache` flag will remove any old translations from the cache that\ndon't exist anymore in any of the given assemblies. This prevents the cache from\ngrowing endlessly over time (an equivalent `jsii-rosetta trim-cache` command is\navailable if your workflow involves running `extract` in multiple distinct\ninvocations and want to retain the cache between them).\n\n##### Dirty Translations\n\nWhen reusing translations from cache, Rosetta checks if cached translations are still valid.\nA translation becomes \"dirty\" (and is dropped from cache) when:\n\n- **Changed sources**: The TypeScript source code has been modified since the translation was cached.\n- **Changed translator version**: The translator for one or more target languages has been updated to a new version.\n  This is a rare occurrence that may happen when upgrading from an older version of Rosetta.\n- **Changed types**: The types referenced by the snippet have changed and consequently any translation might have to be updated.\n  This is detected using type fingerprinting.\n- **Non-compiling**: The cached translation didn't compile, but `--compile` mode is enabled.\n\nDirty translations are dropped and re-translated.\n\n### Infuse\n\nThe `jsii-rosetta infuse` command increases the coverage of examples for classes\nin the assembly.\n\nIt finds classes in the assembly that don't have an example associated with them\nyet (as specified via the `@example` tag in the doc comments), but that are used\nin another example found elsewhere—in either a `README` or an example of another\nclass—it will copy the example to all classes involved.  This will make sure\nyour handwritten examples go as far as possible.\n\nNote that in order to do this, `infuse` will *modify* the assemblies it is\ngiven.\n\n`rosetta infuse` depends on the analysis perfomed by `rosetta extract`, and must\ntherefore be run after `extract`. It can also be run as part of `extract`, by\npassing the `--infuse` flag:\n\n```sh\njsii-rosetta extract \\\n  --directory some/dir \\\n  --infuse \\\n  $(find . -name .jsii)\n```\n\n## Debugging\n\n### Type Fingerprints\n\nTo debug type fingerprinting issues, set the `DEBUG_TYPE_FINGERPRINTS` environment variable to a file path.\nThis writes all computed type fingerprints to the specified file in alphabetically sorted format:\n\n```sh\nDEBUG_TYPE_FINGERPRINTS=type-fingerprints.txt jsii-rosetta extract $(find . -name .jsii)\n```\n\nThe output file contains one line per type in the format `\u003cfqn\u003e: \u003chash\u003e`, making it easy to compare\nfingerprints across different runs using standard diff tools.\n\n### Translation Timing\n\nTo display timing information for snippet translations, set the `TIMING=1` environment variable:\n\n```sh\nTIMING=1 jsii-rosetta extract $(find . -name .jsii)\n```\n\nThis outputs a table showing compilation time for each snippet, helping identify performance bottlenecks.\nNote that timing is not supported when using batch compilation mode.\n\n### Translations and pacmak\n\n`jsii-pacmak` will read translation from tablets to substitute translated examples\ninto the generated source bindings. `pacmak` will automatically read individual\n`.jsii.tabl.json` files if present, and can additionally also read from a global\ntablet file.\n\nWhen a translation for a code sample cannot be found, `pacmak` can be configured\nto do one of the following:\n\n- Leave the sample untranslated (default)\n- Translate the sample in-place (this will slow down generation a lot, and you\n  will not have the fine control over the compilation environment that you would\n  have if you were to use the `extract` command)\n- Fail\n\nExample:\n\n```sh\njsii-pacmak \\\n  [--rosetta-tablet=global.json] \\\n  [--rosetta-unknown-snippets=verbatim|translate|fail]\n```\n\n### Data flow\n\nThe diagram below shows how data flows through the jsii tools when used together:\n\n```text\n┌───────────┐\n│           │\n│  Source   ├───┐\n│           │   │    ╔══════════╗    ┌────────────┐     ╔═══════════════╗    ┌──────────┐\n└───────────┘   │    ║          ║    │            │     ║    rosetta    ║    │          │\n                ├───▶║   jsii   ║───▶│  assembly  │────▶║    extract    ║───▶│  tablet  │\n┌───────────┐   │    ║          ║    │            │     ║               ║    │          │\n│           │   │    ╚══════════╝    └────────────┘     ╚═══════════════╝    └──────────┘\n│  README   │───┘                           │                                      │\n│           │                               │                                      │\n└───────────┘                               │           ╔═══════════════╗          │\n                                            │           ║    rosetta    ║          │\n                                            └──────────▶║    infuse     ║◀─────────┘\n                                                        ║               ║\n                                                        ╚═══════════════╝\n                                                                │\n                                            ┌───────────────────┴───────────────────┐\n                                            │                                       │\n                                            ▼                                       ▼\n                                     ┌────────────┐                           ┌──────────┐\n                                     │            │                           │          │\n                                     │ assembly'  │                           │ tablet'  │\n                                     │            │                           │          │\n                                     └────────────┘                           └──────────┘\n                                            │                                       │\n                                            │                                       │\n                                            │                                       ▼              ┌─────────────┐\n                                            │                               ╔═══════════════╗     ┌┴────────────┐│\n                                            │                               ║               ║     │             ││\n                                            └──────────────────────────────▶║    pacmak     ║────▶│  packages   ││\n                                                                            ║               ║     │             ├┘\n                                                                            ╚═══════════════╝     └─────────────┘\n                                                                               (potentially\n                                                                             live-translates)\n```\n\n## Advanced topics\n\n### Hiding code from samples\n\nIn order to make examples compile, boilerplate code may need to be added that detracts from the example at hand (such as\nvariable declarations and imports).\n\nThis package supports hiding parts of the original source after translation.\n\nTo mark special locations in the source tree, we can use one of three mechanisms:\n\n- Use a `void` expression statement to mark statement locations in the AST.\n- Use the `comma` operator combined with a `void` expression to mark expression locations in the AST.\n- Use special directive comments (`/// !hide`, `/// !show`) to mark locations that span AST nodes. This is less reliable\n  (because the source location of translated syntax sometimes will have to be estimated) but the only option if you want\n  to mark non-contiguous nodes (such as hide part of a class declaration but show statements inside the constructor).\n\nThe `void` expression keyword and or the `comma` operator feature are little-used JavaScript features that are reliably\nparsed by TypeScript and do not affect the semantics of the application in which they appear (so the program executes\nthe same with or without them).\n\nA handy mnemonic for this feature is that you can use it to \"send your code into the void\".\n\n#### Hiding statements\n\nStatement hiding looks like this:\n\n```ts\nbefore(); // will be shown\n\nvoid 0; // start hiding (the argument to 'void' doesn't matter)\nmiddle(); // will not be shown\nvoid 'show'; // stop hiding\n\nafter(); // will be shown again\n```\n\n#### Hiding expressions\n\nFor hiding expressions, we use `comma` expressions to attach a `void` statement to an expression value without changing\nthe meaning of the code.\n\nExample:\n\n```ts\nfoo(1, 2, (void 1, 3));\n```\n\nWill render as\n\n```ts\nfoo(1, 2)\n```\n\nAlso supports a visible ellipsis:\n\n```ts\nconst x = (void '...', 3);\n```\n\nRenders to:\n\n```ts\nx = ...\n```\n\n#### Hiding across AST nodes\n\nUse special comment directives:\n\n```ts\nbefore();\n/// !hide\nnotShown();\n/// !show\nafter();\n```\n\n\n## :balance_scale: License\n\n**jsii** is distributed under the [Apache License, Version 2.0][apache-2.0].\n\nSee [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for more information.\n\n[apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0\n","funding_links":[],"categories":["aws"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fjsii-rosetta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Fjsii-rosetta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fjsii-rosetta/lists"}