jsii-sampiler

0.20.6 verified Fri May 01 auth: no javascript

jsii-sampiler is a utility for transcribing TypeScript code snippets into other jsii-supported languages (Java, C#, Python, Go, etc.). It is part of the AWS jsii ecosystem and works in tandem with jsii-pacmak for documentation generation. The latest stable version (v1.x) is actively maintained with frequent bug fix releases. It uses grammatical and type-aware translation for compiling or non-compiling samples and supports void masking to hide boilerplate. Its key differentiator is deep integration with the jsii type system, enabling accurate multi-language translations beyond simple text transformation.

Common errors

error SyntaxError: Unexpected token 'void' ↓

cause Using void masking outside of allowed contexts (e.g., expression positions).

fix

Move void directives to statement or comma expression positions where void is syntactically valid.

error Cannot find module 'jsii-sampiler' or its corresponding type declarations. ↓

cause Missing installation or incorrect import path.

fix

npm install jsii-sampiler and use import { sampile } from 'jsii-sampiler' (ESM).

error TypeError: sampile is not a function ↓

cause Improper import (e.g., default import instead of named).

fix

Use import { sampile } from 'jsii-sampiler', not import sampile from 'jsii-sampiler'.

Warnings

breaking Version 1.x dropped support for Node 10; require Node >= 10.3.0. ↓

fix Upgrade Node to >=10.3.0 (but ideally use current LTS).

gotcha void masking directives are removed in output but affect translation; incorrect placement may produce invalid code. ↓

fix Ensure void expressions are used only where valid JavaScript/TypeScript syntax allows.

gotcha Non-compiling samples lose type information; struct fields, nested types, and dictionary vs struct disambiguation may be incorrect. ↓

fix Provide compilable samples with full type annotations for best results.

deprecated The 'Sample' class from earlier versions is deprecated; use 'sampile' function directly. ↓

fix Replace Sample.sampile() with import { sampile } from 'jsii-sampiler'.

Install

npm install jsii-sampiler

yarn add jsii-sampiler

pnpm add jsii-sampiler

Imports

sampile

wrong

const { sampile } = require('jsii-sampiler')

correct

import { sampile } from 'jsii-sampiler'

ESM-only since v1.x; CommonJS require not supported.

Sampiler

wrong

import Sampiler from 'jsii-sampiler'

correct

import { Sampiler } from 'jsii-sampiler'

Sampiler is a named export, not default.

TypeScriptSnippet
```
import { TypeScriptSnippet } from 'jsii-sampiler'
```
TypeScript type import; use 'import type' if only used as a type.

Quickstart

Basic usage: translate a TypeScript snippet to Python using the sampile function.

import { sampile } from 'jsii-sampiler';

// TypeScript code snippet to translate
const tsCode = `
  const greeting: string = 'Hello';
  console.log(greeting);
`;

// Translate to Python
const pythonCode = sampile(tsCode, 'python');
console.log(pythonCode);
// Output: greeting = 'Hello'
// print(greeting)