diff options
Diffstat (limited to 'std/manual.md')
| -rw-r--r-- | std/manual.md | 66 |
1 files changed, 56 insertions, 10 deletions
diff --git a/std/manual.md b/std/manual.md index 3ddf6493b..2fa93718f 100644 --- a/std/manual.md +++ b/std/manual.md @@ -567,20 +567,65 @@ The out of the box TypeScript compiler though relies on both extension-less modules and the Node.js module resolution logic to apply types to JavaScript modules. -In order to bridge this gap, Deno supports compiler hints that inform Deno the -location of `.d.ts` files and the JavaScript code they relate to. A compiler -hint looks like this: +In order to bridge this gap, Deno supports three ways of referencing type +definition files without having to resort to "magic" resolution. + +#### Compiler hint + +If you are importing a JavaScript module, and you know where the type definition +for that module is located, you can specify the type definition at import. This +takes the form of a compiler hint. Compiler hints inform Deno the location of +`.d.ts` files and the JavaScript code that is imported that they relate to. The +hint is `@deno-types` and when specified the value will be used in the compiler +instead of the JavaScript module. For example if you had `foo.js`, but you know +that along side of it was `foo.d.ts` which was the types for the file, the code +would look like this: ```ts // @deno-types="./foo.d.ts" import * as foo from "./foo.js"; ``` -Where the hint affects the next `import` statement (or `export ... from` -statement) where the value of the `@deno-types` will be substituted at compile -time instead of the specified module. Like in the above example, the Deno -compiler will load `./foo.d.ts` instead of `./foo.js`. Deno will still load -`./foo.js` when it runs the program. +The value follows the same resolution logic as importing a module, meaning the +file needs to have an extension and is relative to the current module. Remote +specifiers are also allowed. + +The hint affects the next `import` statement (or `export ... from` statement) +where the value of the `@deno-types` will be substituted at compile time instead +of the specified module. Like in the above example, the Deno compiler will load +`./foo.d.ts` instead of `./foo.js`. Deno will still load `./foo.js` when it runs +the program. + +#### Triple-slash reference directive in JavaScript files + +If you are hosting modules which you want to be consumed by Deno, and you want +to inform Deno the location of the type definitions, you can utilise a +triple-slash directive in the actual code. For example, if you have a JavaScript +module, where you want to provide Deno with the location of the type definitions +for that JavaScript file, which happens to be along side that file. You +JavaScript module named `foo.js` might look like this: + +```js +/// <reference types="./foo.d.ts" /> +export const foo = "foo"; +``` + +Deno will see this, and the compiler will use `foo.d.ts` when type checking the +file, though `foo.js` will be loaded at runtime. The resolution of the value of +the directive follows the same resolution logic as importing a module, meaning +the file needs to have an extension and is relative to the current file. Remote +specifiers are also allowed. + +#### X-TypeScript-Types custom header + +If you are hosting modules which you want to be consumed by Deno, and you want +to inform Deno the location of the type definitions, you can use a custom HTTP +header of `X-TypeScript-Types` to inform Deno of the location of that file. + +The header works in the same way as the triple-slash reference mentioned above, +it just means that the content of the JavaScript file itself does not need to be +modified, and the location of the type definitions can be determined by the +server itself. **Not all type definitions are supported.** @@ -592,11 +637,12 @@ include `node`, expecting to resolve to some path like `./node_modules/@types/node/index.d.ts`. Since this depends on non-relative "magical" resolution, Deno cannot resolve this. -**Why not use the triple-slash type reference?** +**Why not use the triple-slash type reference in TypeScript files?** The TypeScript compiler supports triple-slash directives, including a type reference directive. If Deno used this, it would interfere with the behavior of -the TypeScript compiler. +the TypeScript compiler. Deno only looks for the directive in JavaScript (and +JSX) files. ### Testing if current file is the main program |