configuration.md

Configuring TypeScript in Deno

TypeScript comes with a lot of different options that can be configured, but Deno strives to make it easy to use TypeScript with Deno. Lots of different options frustrates that goal. To make things easier, Deno configures TypeScript to "just work" and shouldn't require additional configuration.

That being said, Deno does support using a TypeScript configuration file. To use a TypeScript configuration file with Deno, you may provide a path on the command line, or use the default. For example:

> deno run --config ./deno.json main.ts

⚠️ Do consider though that if you are creating libraries that require a configuration file, all of the consumers of your modules will require that configuration file too if you distribute your modules as TypeScript. In addition, there could be settings you do in the configuration file that make other TypeScript modules incompatible. Honestly it is best to use the Deno defaults and to think long and hard about using a configuration file.

⚠️ Deno v1.14 started supporting a more general configuration file that is no longer confined to specifying TypeScript compiler settings. Using tsconfig.json as a file name will still work, but we recommend to use deno.json or deno.jsonc, as an automatic lookup of this file is planned for an upcoming release.

How Deno uses a configuration file

Deno does not process a TypeScript configuration file like tsc does, as there are lots of parts of a TypeScript configuration file that are meaningless in a Deno context or would cause Deno to not function properly if they were applied.

Deno only looks at the compilerOptions section of a configuration file, and even then it only considers certain compiler options, with the rest being ignored.

Here is a table of compiler options that can be changed, their default in Deno and any other notes about that option:

Option	Default	Notes
allowJs	true	This almost never needs to be changed
allowUnreachableCode	false
allowUnusedLabels	false
checkJs	false	If true causes TypeScript to type check JavaScript
jsx	"react"
jsxFactory	"React.createElement"
jsxFragmentFactory	"React.Fragment"
keyofStringsOnly	false
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.
noErrorTruncation	false
noFallthroughCasesInSwitch	false
noImplicitAny	true
noImplicitReturns	false
noImplicitThis	true
noImplicitUseStrict	true
noStrictGenericChecks	false
noUnusedLocals	false
noUnusedParameters	false
noUncheckedIndexedAccess	false
reactNamespace	React
strict	true
strictBindCallApply	true
strictFunctionTypes	true
strictPropertyInitialization	true
strictNullChecks	true
suppressExcessPropertyErrors	false
suppressImplicitAnyIndexErrors	false
useUnknownInCatchVariables	false

For a full list of compiler options and how they affect TypeScript, please refer to the TypeScript Handbook.

What an implied tsconfig.json looks like

It is impossible to get tsc to behave like Deno. It is also difficult to get the TypeScript language service to behave like Deno. This is why we have built a language service directly into Deno. That being said, it can be useful to understand what is implied.

If you were to write a tsconfig.json for Deno, it would look something like this:

{
  "compilerOptions": {
    "allowJs": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "inlineSourceMap": true,
    "isolatedModules": true,
    "jsx": "react",
    "lib": ["deno.window"],
    "module": "esnext",
    "moduleDetection": "force",
    "strict": true,
    "target": "esnext",
    "useDefineForClassFields": true
  }
}

You can't copy paste this into a configuration file and get it to work, specifically because of the built-in type libraries that are custom to Deno which are provided to the TypeScript compiler. This can somewhat be mocked by running deno types on the command line and piping the output to a file and including that in the files as part of the program, removing the "lib" option, and setting the "noLib" option to true.

If you use the --unstable flag, Deno will change the "lib" option to [ "deno.window", "deno.unstable" ]. If you are trying to load a worker, that is type checked with "deno.worker" instead of "deno.window". See Type Checking Web Workers for more information on this.

Using the "lib" property

Deno has several libraries built into it that are not present in other platforms, like tsc. This is what enables Deno to properly check code written for Deno. In some situations though, this automatic behavior can cause challenges, for example like writing code that is intended to also run in a browser. In these situations the "lib" property of a compilerOptions can be used to modify the behavior of Deno when type checking code.

The built-in libraries that are of interest to users:

• "deno.ns" - This includes all the custom Deno global namespace APIs plus the Deno additions to import.meta. This should generally not conflict with other libraries or global types.
• "deno.unstable" - This includes the addition unstable Deno global namespace APIs.
• "deno.window" - This is the "default" library used when checking Deno main runtime scripts. It includes the "deno.ns" as well as other type libraries for the extensions that are built into Deno. This library will conflict with libraries like "dom" and "dom.iterable" that are standard TypeScript libraries.
• "deno.worker" - This is the library used when checking a Deno web worker script. For more information about web workers, check out Type Checking Web Workers.
• "dom.asynciterable" - TypeScript currently does not include the DOM async iterables that Deno implements (plus several browsers), so we have implemented it ourselves until it becomes available in TypeScript.

These are common libraries that Deno doesn't use, but are useful when writing code that is intended to also work in another runtime:

• "dom" - The main browser global library that ships with TypeScript. The type definitions conflict in many ways with "deno.window" and so if "dom" is used, then consider using just "deno.ns" to expose the Deno specific APIs.
• "dom.iterable" - The iterable extensions to the browser global library.
• "scripthost" - The library for the Microsoft Windows Script Host.
• "webworker" - The main library for web workers in the browser. Like "dom" this will conflict with "deno.window" or "deno.worker", so consider using just "deno.ns" to expose the Deno specific APIs.
• "webworker.importscripts" - The library that exposes the importScripts() API in the web worker.
• "webworker.iterable" - The library that adds iterables to objects within a web worker. Modern browsers support this.

Targeting Deno and the Browser

A common use case is writing code that works in Deno and the browser: using a conditional check to determine the environment in which the code is executing before using any APIs which are exclusive to one or the other. If that is the case, a common configuration of a compilerOptions would look like this:

{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
  }
}

This should allow most code to be type checked properly by Deno.

If you expect to run the code in Deno with the --unstable flag, then you will want to add that library to the mix as well:

{
  "compilerOptions": {
    "target": "esnext",
    "lib": [
      "dom",
      "dom.iterable",
      "dom.asynciterable",
      "deno.ns",
      "deno.unstable"
    ]
  }
}

Typically when you use the "lib" option in TypeScript, you need to include an "es" library as well. In the case of "deno.ns" and "deno.unstable", they automatically include "esnext" when you bring them in.

The biggest "danger" when doing something like this, is that the type checking is significantly looser, and there is no way to validate that you are doing sufficient and effective feature detection in your code, which may lead to what could be trivial errors becoming runtime errors.

Using the "types" property

The "types" property in "compilerOptions" can be used to specify arbitrary type definitions to include when type checking a program. For more information on this see Using ambient or global types.