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 theobject
format:The{ // ... "author": { "name": "The Octocat", // Required "email": "octocat@github.com", // Optional "url": "https://github.com/octocat", // Optional "organization": false // Optional (defaults to false) }, // ... }
organization
field is an extension from the package.json schema that can be used to signal theauthor
field refers to anorganization
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 withUnlicense
) 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 thedeprecated
field inpackage.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 | Required | Default |
---|---|---|---|
excludeTypescript |
string[] |
none | |
metadata |
object |
none | |
projectReferences |
boolean |
true |
|
targets |
object |
||
tsc |
object |
{ outDir: '.', rootDir: '.' } |
|
versionFormat |
'short' | 'full' |
'full' |
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.
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.
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:
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 theTypeScript
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 withoutDir
, to control the directory structure that gets generated.forceConsistentCasingInFileNames
- iftrue
, will make theTypeScript
compiler care about the casing of files specified inimport
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
, andsourceMap
allow confifuring the source map generation. This option can be useful to finely control your local development experience (for example, by enablingdeclarationMap
), 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 thatjsii
uses). The value specified here will be forwarded as-is to the TypeScript compiler.baseUrl
andpaths
can be used to configure TypeScript path mappings, and are copied verbatim totsconfig.json
.
Refer to the TypeScript compiler options reference for more information about those options.
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 ofjsii
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.