Overview

The configuration for jsii is recorded in the package.json file, which is the standard package manifest for NPM packages. This document describes the constraints and extensions jsii adds to the package.json schema.

jsii-config

Use jsii-config to aid in configuring a new jsii module.

Additional Requirements & Extensions

In order to be able to generate valid packages for all the supported target package managers, certain fields that are optional in the standard package.json schema are required by jsii.

For example, Maven Central requires packages to carry sufficient metadata, such as developer information and license, in order to be valid for publishing.

Field	Required	Extensions
`author`		`author.organization`
`license`
`main`
`repository`
`stability`		The field itself is an extension
`types`

Attribution & Licensing

The author field must be set. Although the string form ("The Octocat <octocat@github.com> (https://github.com/octocat)") works, it is recommended to set the value using the object format:

{
  // ...
  "author": {
    "name": "The Octocat",                // Required
    "email": "octocat@github.com",        // Optional
    "url": "https://github.com/octocat",  // Optional
    "organization": false                 // Optional (defaults to false)
  },
  // ...
}

The organization field is an extension from the package.json schema that can be used to signal the author field refers to an organization and not and individual person.

The license field must be set to a valid SPDX license id. If you do not intend to release your package for third-party consumption, UNLICENSED (not to be confused with Unlicense) is a valid option.

Important License Information

You are free to decide which license you want to distribute your code under. The bindings generated by jsii-pacmak will use the exact same license as the source TypeScript library they were based on. You are responsible for correctly applying your chosen license to your work (most licenses have documentations outlining how to correctly apply the license), and for complying with the terms of the licenses of packages your work depends on (this is particularly important when dependencies are bundled, as discussed later in this section).

In addition to the license field present in the package.json file, we strongly recommend adding a LICENSE file in the package's root directory which contains the standardized text for the license (those can be found on the SPDX website).

Danger

Unless you know exactly what you are doing, you should copy the license text verbatim in the LICENSE file. Many organizations have license scanners that will only recognize the standard license text, and editing that may cause undesired friction before users in those organizations can use your library, and may void your license choice.

A NOTICE file is often desirable. In particular, if you are developing the library as part of your employment, you should ask your employer's legal team (or equivalent) for specific instructions.

Danger

If your library includes bundled dependencies (via the bundledDependencies/bundleDependencies key in the package.json file), you are required to comply with those dependencies' licenses provisions pertaining to re-distribution. This often means providing attribution to these in your NOTICE file, among other requirements.

The LICENSE and NOTICE files, when present, will be copied into generated binding's source code. If no LICENSE file exists in the source package, the standard SPDX license text will be produced into a LICENSE file in generated bindings whenever possible.

Source Control Information

The repository field must be set to the URL of the source-control system (such as a git repository) for the package. The recommended way to provide the value is using the object representation:

{
  "repository": {
    "url": "https://github.com/aws/jsii.git", // Required
    "type": "git",                            // Recommended
    "directory": "/path"                      // Optional
  }
}

Library Entry Point

Both the main field must be set to the .js file that acts as the entry point of your library (what node's require('library-name') will load). Additionally, TypeScript's types field must be set to the .d.ts file corresponding to the main file. The assembly emitted by jsii will only represent types that are exported from the types file.

Package-level API Stability

The .jsii assembly document allows representing API stability levels on individual API elements. The default value set for API elements for which a stability declaration is not found can be configured using the stability field of the package.json file. It can be set to one of the following values: experimental, stable, deprecated and external. While the exact semantic value of those fields is defined by the package maintainer, the generic interpretation for those on packages is:

experimental - the package is not yet ready for production usage, as it is still in the early stages of its development.
stable - the package is ready for production and its APIs should be expected to adhere to semantic versioning.
deprecated - the package should no longer be used and may no longer be maintained. It is a good practice to set the deprecated field in package.json with an explanation of how consumers of the package should update their dependencies.
external - the package includes APIs that are derived from external artifacts, and the owners of those artifacts control their stability.

The `jsii` section

In order to configure the behavior of jsii, the package.json file must include a jsii section that can contain the following entries:

Field	Type	Default	Supported versions
`excludeTypescript`	`string[]`	none	all
`metadata`	`object`	none	all
`projectReferences`	`boolean`	`true`	all
`targets`	`object`		all
`tsc`	`object`	`{ outDir: '.', rootDir: '.' }`	all
`tsconfig`	`string`	none	`>= 5.2`
`validateTsconfig`	`'strict' \| 'generated' \| 'minimal' \| 'off'`	none	`>= 5.2`
`versionFormat`	`'short' \| 'full'`	`'full'`	all

Language targets

`targets`

The targets section is where jsii packages define which target languages they support. This provides the package generators with the additional information they require in order to name generated artifacts. Configuration is provided as a mapping from target name to a configuration object.

The specific configuration accepted for each supported language is presented in dedicated pages:

Typescript configuration

By default, jsii generates a tsconfig.json for you, using best practice settings that are optimized for widespread support and backwards compatibility. Use the excludeTypescript and tsc settings to configure some supported typescript compiler options.

You may want to customize the typescript configuration even further. In this case, use the tsconfig setting to instruct the jsii compiler to use user-owned typescript configuration file. Such a user-provider tsconfig must follow certain rules to be a valid config for use with jsii. These rules are enforced via the validateTsconfig setting. You may choose the level of validation to match your use case.

Info

Using a user-provider tsconfig and configuration via excludeTypescript and tsc are mutually exclusive. Specifically when using a user-provided tsconfig, any other configuration settings will be ignored.

`excludeTypescript`

By default, jsii will include all *.ts files (except .d.ts files) in the TypeScript compiler input. This can be problematic for example when the package's build or test procedure generates .ts files that cannot be compiled with jsii's compiler settings.

The excludeTypescript configuration accepts a list of glob patterns. Files matching any of those patterns will be excluded from the TypeScript compiler input.

`tsc`

In order to the generated javascript can be properly loaded by the jsii runtimes, jsii generates a [tsconfig.json] file with fixed settings at the beginning of the compilation pass. Certain configuration options can however be set by the maintainers in order to better suit their development workflow or processes. Those configuration are set in the jsii.tsc section of the package.json file, but use the same name as [tsconfig.json]:

outDir - path to the directory when artifacts generated by the TypeScript compiler will be placed.
This influences the location of .d.ts and .js files, but will not affect the location of the .jsii file, which will always be placed at the package's root.
rootDir - specifies the root directory that contains all of the .ts source files. This is used in conjunction with outDir, to control the directory structure that gets generated.
forceConsistentCasingInFileNames - if true, will make the TypeScript compiler care about the casing of files specified in import statements. This is helpful if you're developing on a filesystem that is case-insensitive (Mac/Win), but building/deploying on a filesystem that is case-sensitive (Linux).
declarationMap, inlineSourceMap, inlineSources, and sourceMap allow configuring the source map generation. This option can be useful to finely control your local development experience (for example, by enabling declarationMap), or to optimize the emitted code size (by disabling source maps entirely).
if any of these options is specified, the source map configuration will exactly match what is being provided here
If none are specified, the default settings will be used: { inlineSourceMap: true, inlineSources: true }
types allows limiting which visible type libraries get loaded in the global scope by the typescript compiler. By default, all visible @types/* packages will be loaded, which can be undesirable (in particular in monorepos, where some type libraries are not compatible with the TypeScript compiler version that jsii uses). The value specified here will be forwarded as-is to the TypeScript compiler.
baseUrl and paths can be used to configure TypeScript path mappings, and are copied verbatim to tsconfig.json.

Refer to the TypeScript compiler options reference for more information about those options.

`tsconfig`

Available from jsii >= 5.2

Warn

This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified through early adopters. Use at your own risk, and please any report bugs.

Provide this setting, to use a user-provided typescript configuration with jsii. Set to the name of the tsconfig file that should be used. Usually this will be "tsconfig.json", but can be set to any filename. The provided tsconfig is subject to validation rules, see below for more details.

{
  "jsii": {
    "tsconfig": "tsconfig.json"
  }
}

`validateTsconfig`

Available from jsii >= 5.2

Warn

This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified through early adopters. Use at your own risk, and please any report bugs.

A user-provider typescript config must follow certain rules to be a valid config for use with jsii. By default the tsconfig is validated against the strict rule set. If needed, you can change the level of enforcement with the validateTsconfig setting.

Rule set	Description
`strict`	(Default) Validates the provided config against a strict rule set designed for widespread support and backwards-compatibility.
`generated`	Enforces a tsconfig as if it were generated by jsii. Use this to stay compatible with the generated config, but have full ownership over the file.
`minimal`	Only reject options that are known to be incompatible with jsii. This rule set is likely to be incomplete and new rules will be added without notice as incompatibilities are discovered.
`off`	Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk.

Recommended setting\ Resulting jsii assembly/package may be incompatible with wider ecosystem

There is currently no easy way to inspect these rule sets, however detailed error messages are returned if a provided tsconfig fails validation.

{
  "jsii": {
    "tsconfig": "tsconfig.json",
    "validateTsconfig": "generated" // ensure user tsconfig is similar to jsii-generated tsconfig
  }
}

Metadata

`metadata`

The metadata section can be used to record additional metadata as key-value pairs that will be recorded as-is into the .jsii assembly file. That metadata can later be inspected using jsii-reflect utilities, for example.

`versionFormat`

Determines the format of the jsii toolchain version string that will be included in the .jsii assembly file's jsiiVersion attribute.

full (the default) - a version number including a commit hash will be used
For example: 0.14.3 (build 1b1062d)
short - only the version number of jsii will be used
For example: 0.14.3

This option is primarily useful for developing regression tests when developing jsii itself, as using the short format reduces volatility in the assemblies generated by development versions of jsii. Users of jsii are advised to leave the default setting, as having full version information can be essential when trying to troubleshoot assembly generation problems.

Diagnostics

JSII produces a number of diagnostic information. These have been categorized into "error", "warning", "suggestion" and "message", by default. Diagnostics categorized as "error" will fail the jsii compiler and the rest will be printed to console.

These can be re-configured to a different category under the diagnostics key as so -

"jsii": {
  // ...
  "diagnostics": {
    "documentation/non-existent-parameter": "error",
    "code-style/submodule-name-casing": "suggestion",
    "JSII9998": "error",
    "JSII9001": "warning"
  }
}

As noted in the example above, the diagnostic code can be the human readable string, or the numeric code prefixed with JSII.

The full list of diagnostic codes can be found in jsii-diagnostic.ts.

Dependency considerations

Like any node library, jsii packages can declare runtime dependencies using the dependencies section of package.json.

Dependencies that are `jsii` modules

Node modules are conventionally versioned using semantic versioning, but that is not true of all package managers that jsii is able to target. Additionally, only one version of the jsii runtime and kernel can be used within a given application. In order to avoid version resolution surprises at run-time, jsii requires duplicating jsii modules declarations from dependencies into the peerDependencies section.

Dependencies that are not `jsii` modules

The jsii runtimes in non-javascript languages do not use npm install, and as a consequence cannot rely on npm install bringing in a package's dependencies. As a consequence, dependencies that are not themselves jsii modules, must also be referenced in the bundledDependencies section, so that they are bundled within the NPM package.

Overview

jsii-config

Additional Requirements & Extensions

Attribution & Licensing

Important License Information

Source Control Information

Library Entry Point

Package-level API Stability

The jsii section

Language targets

targets

Typescript configuration

excludeTypescript

tsc

tsconfig

validateTsconfig