Skip to content

Commit

Permalink
chore: small fixes to docs for user-provided tsconfig (#4518)
Browse files Browse the repository at this point in the history 
---

By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0
  • Loading branch information
@mrgrain
mrgrain authored May 20, 2024
1 parent b8a8264 commit f1bb4e6
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 20 deletions.
28 changes: 16 additions & 12 deletions gh-pages/content/user-guides/lib-author/configuration/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,16 +135,16 @@ package maintainer, the generic interpretation for those on packages is:
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 | Supported versions |
| ------------------- | ---------------------------------------------- | :-----------------------------: | ------------------------------------ | ------------------ |
| `excludeTypescript` | `#!ts string[]` | | _none_ | _all_ |
| `metadata` | `#!ts object` | | _none_ | _all_ |
| `projectReferences` | `#!ts boolean` | | `#!ts true` | _all_ |
| `targets` | `#!ts object` | :octicons-check-circle-fill-24: | | _all_ |
| `tsc` | `#!ts object` | | `#!ts { outDir: '.', rootDir: '.' }` | _all_ |
| `tsconfig` | `#!ts string` | | _none_ | `>= 5.2` |
| `validateTsconfig` | `#!ts 'strict'\|'generated'\|'minimal'\|'off'` | | _none_ | `>= 5.2` |
| `versionFormat` | `#!ts 'short'\|'full'` | | `#!ts 'full'` | _all_ |
| Field | Type | Required | Default | Supported versions |
| ------------------- | ------------------------------------------------- | :-----------------------------: | ------------------------------------ | ------------------ |
| `excludeTypescript` | `#!ts string[]` | | _none_ | _all_ |
| `metadata` | `#!ts object` | | _none_ | _all_ |
| `projectReferences` | `#!ts boolean` | | `#!ts true` | _all_ |
| `targets` | `#!ts object` | :octicons-check-circle-fill-24: | | _all_ |
| `tsc` | `#!ts object` | | `#!ts { outDir: '.', rootDir: '.' }` | _all_ |
| `tsconfig` | `#!ts string` | | _none_ | `>= 5.2` |
| `validateTsconfig` | `#!ts 'strict' | 'generated' | 'minimal' | 'off'` | | _none_ | `>= 5.2` |
| `versionFormat` | `#!ts 'short' | 'full'` | | `#!ts 'full'` | _all_ |

### Language targets

Expand Down Expand Up @@ -216,7 +216,9 @@ Refer to the [TypeScript compiler options reference][ts-options] for more inform
[`tsconfig.json`]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
[ts-options]: https://www.typescriptlang.org/docs/handbook/compiler-options.html

#### `tsconfig` _(available from jsii >= 5.2)_
#### `tsconfig`

_Available from jsii >= 5.2_

!!! warn
:test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
Expand All @@ -234,7 +236,9 @@ The provided tsconfig is subject to validation rules, see below for more details
}
```

#### :test_tube: `validateTsconfig` _(available from jsii >= 5.2)_
#### `validateTsconfig`

_Available from jsii >= 5.2_

!!! warn
:test_tube: This features is experimental. Behavior may change as bugs are addressed, and requirements are clarified
Expand Down
16 changes: 8 additions & 8 deletions gh-pages/partials/tsconfig-rulesets.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
| Rule set | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strict` :star: | (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` :warn: | 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` :warn: | Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk. |
| Rule set | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strict` :star: | (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` :warning: | 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` :warning: | Disables all config validation, including options that are known to be incompatible with jsii. Intended for experimentation only. Use at your own risk. |

:star: Recommended setting
:warn: Resulting jsii assembly/package may be incompatible with wider ecosystem
:star: Recommended setting\
:warning: 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.

0 comments on commit f1bb4e6

Please sign in to comment.