Skip to content

Commit f4dff69

Browse files
nayeemrmnthisisjofrank
nayeemrmn
and
thisisjofrank
authored
add tsconfig compatibility section (#2677)
Co-authored-by: Jo Franchetti <[email protected]>
1 parent 3b831ec commit f4dff69

File tree

2 files changed

+101
-21
lines changed

2 files changed

+101
-21
lines changed

‎runtime/fundamentals/workspaces.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,48 @@ root and its members:
482482
Deno provides several ways to run commands across all or specific workspace
483483
members:
484484

485+
### Type checking
486+
487+
Workspace members can have different sets of compiler options. They are also
488+
inherited between root and member, much like
489+
[TSConfig `extends`](https://www.typescriptlang.org/tsconfig/#extends). For
490+
example:
491+
492+
```json title="deno.json"
493+
{
494+
"workspace": ["./web"],
495+
"compilerOptions": {
496+
"checkJs": true
497+
}
498+
}
499+
```
500+
501+
```json title="web/deno.json"
502+
{
503+
"compilerOptions": {
504+
"lib": ["esnext", "dom"]
505+
}
506+
}
507+
```
508+
509+
Files in the `web` subdirectory will be configured with the following options:
510+
511+
```json
512+
{
513+
"compilerOptions": {
514+
"checkJs": true,
515+
"lib": ["esnext", "dom"]
516+
}
517+
}
518+
```
519+
520+
Each member will be partitioned and checked separately from one another. Just
521+
run `deno check` from the workspace root:
522+
523+
```sh
524+
deno check
525+
```
526+
485527
### Running tests
486528

487529
To run tests across all workspace members, simply execute `deno test` from the

‎runtime/reference/ts_config_migration.md‎

Lines changed: 59 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -80,27 +80,63 @@ TypeScript wasn't able to detect before.
8080

8181
## Configuring TypeScript in Deno
8282

83-
TypeScript offers many configuration options, which can be daunting if you're
84-
just starting out with TS. Deno aims to simplify using TypeScript, instead of
85-
drowning you in countless settings. Deno configures TypeScript to **just work**
86-
out of the box. No extra configuration headaches required!
83+
Deno aims to simplify TypeScript configuration based on the following design
84+
choices:
8785

88-
However, if you do want to change the TypeScript compiler options, Deno allows
89-
you to do so in your `deno.json` file. Provide a path on the command line, or
90-
use the default. For example:
86+
- Strict and modern defaults for type-checking rules.
87+
- Allowing the omission of settings relating to the target runtime or
88+
compatibility, leveraging direct integration with the execution environment.
89+
- Project references using `deno.json` directory scopes.
9190

92-
```console
93-
deno run --config ./deno.json main.ts
94-
```
91+
The last point presents a simpler format than `tsconfig.json`'s
92+
[`references`](https://www.typescriptlang.org/tsconfig/#references) and
93+
[`extends`](https://www.typescriptlang.org/tsconfig/#extends) fields, replacing
94+
them with `deno.json` workspaces and root-member inheritance. See the section on
95+
[type checking in workspaces](/runtime/fundamentals/workspaces/#type-checking).
9596

96-
:::note
97+
## `tsconfig.json` compatibility
9798

98-
If you are creating libraries that require a configuration file, remember that
99-
all of the consumers of your TS modules will require that configuration file
100-
too. In addition, there could be settings in the configuration file that make
101-
other TypeScript modules incompatible.
99+
While using [`tsconfig.json`](https://www.typescriptlang.org/tsconfig/) files is
100+
not recommended for Deno-first projects, existing Node.js + TypeScript
101+
workspaces using them will work out-of-the-box under Deno's type checker and
102+
LSP.
102103

103-
:::
104+
Each workspace directory containing a `deno.json` or `package.json` is probed
105+
for a `tsconfig.json`. If it exists, it is added as a 'root' project reference
106+
and contained references are included recursively.
107+
108+
As with `tsc`, the scope of a TSConfig is determined by its
109+
[root fields](https://www.typescriptlang.org/tsconfig/#root-fields). In case of
110+
overlap:
111+
112+
- A reference takes precedence over its referrer.
113+
- For root references, `foo/bar/tsconfig.json` takes precedence over
114+
`foo/tsconfig.json`.
115+
- If a parent `deno.json` contains `compilerOptions`, that will take precedence
116+
over any TSConfig.
117+
118+
The following fields are supported:
119+
120+
```json title="tsconfig.json"
121+
{
122+
"extends": "...",
123+
"files": ["..."],
124+
"include": ["..."],
125+
"exclude": ["..."],
126+
"references": [
127+
{ "path": "..." }
128+
],
129+
"compilerOptions": {
130+
"...": "..."
131+
}
132+
}
133+
```
134+
135+
Except for `compilerOptions`, these fields cannot be specified in `deno.json`.
136+
137+
You may be forced to use a `tsconfig.json` file when, for example, the required
138+
granularity for [`include`](https://www.typescriptlang.org/tsconfig/#include)
139+
cannot be represented with `deno.json` workspaces and directory scopes.
104140

105141
## TS Compiler Options
106142

@@ -109,15 +145,17 @@ and any other notes about that option:
109145

110146
| Option | Default | Notes |
111147
| -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
112-
| `allowJs` | `true` | This almost never needs to be changed |
113148
| `allowUnreachableCode` | `false` | |
114149
| `allowUnusedLabels` | `false` | |
115-
| `checkJs` | `false` | If `true` causes TypeScript to type check JavaScript |
150+
| `baseUrl` | `"./"` | This is used for resolving bare specifier entries in `paths` and `rootDirs`, but never for bare specifiers in module imports. |
151+
| `checkJs` | `false` | |
116152
| `jsx` | `"react"` | |
117153
| `jsxFactory` | `"React.createElement"` | |
118154
| `jsxFragmentFactory` | `"React.Fragment"` | |
119155
| `keyofStringsOnly` | `false` | |
120156
| `lib` | `[ "deno.window" ]` | The default for this varies based on other settings in Deno. If it is supplied, it overrides the default. See below for more information. |
157+
| `module` | `"nodenext"` | Supported values: `["nodenext", "esnext", "preserve"]`. |
158+
| `moduleResolution` | `"nodenext"` | Supported values: `["nodenext", "bundler"]`. |
121159
| `noErrorTruncation` | `false` | |
122160
| `noFallthroughCasesInSwitch` | `false` | |
123161
| `noImplicitAny` | `true` | |
@@ -129,7 +167,9 @@ and any other notes about that option:
129167
| `noUnusedLocals` | `false` | |
130168
| `noUnusedParameters` | `false` | |
131169
| `noUncheckedIndexedAccess` | `false` | |
132-
| `reactNamespace` | `React` | |
170+
| `paths` | `{}` | |
171+
| `rootDirs` | `null` | |
172+
| `strict` | `true` | |
133173
| `strict` | `true` | |
134174
| `strictBindCallApply` | `true` | |
135175
| `strictFunctionTypes` | `true` | |
@@ -154,8 +194,6 @@ The built-in libraries that are of interest to users:
154194
- `"deno.ns"` - This includes all the custom `Deno` global namespace APIs plus
155195
the Deno additions to `import.meta`. This should generally not conflict with
156196
other libraries or global types.
157-
- `"deno.unstable"` - This includes the addition unstable `Deno` global
158-
namespace APIs.
159197
- `"deno.window"` - This is the "default" library used when checking Deno main
160198
runtime scripts. It includes the `"deno.ns"` as well as other type libraries
161199
for the extensions that are built into Deno. This library will conflict with

0 commit comments

Comments
 (0)