Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ba95059

Browse files
cspotcodecspotcode
authored
Docs overhaul (#1682)
* Fix "esm" jsdoc * categorize typedocs; exclude jsonschema tags from typedoc * Resolve #1607: explain common ESM errors in troubleshooting page * improve dark theme contrast * Fix amendment to typedoc categories * big docs overhaul * changes to cater to our readme rendering script * lint-fix * final fixes
1 parent f5b6e2d commit ba95059

22 files changed

+706
-194
lines changed

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
!/tests
99
!/website
1010
/website/.docusaurus
11+
/website/build
1112
/website/docs
1213
/website/readme-sources
1314
/website/static

‎src/index.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,8 @@ export const VERSION = require('../package.json').version;
183183

184184
/**
185185
* Options for creating a new TypeScript compiler instance.
186+
187+
* @category Basic
186188
*/
187189
export interface CreateOptions {
188190
/**
@@ -367,7 +369,9 @@ export interface CreateOptions {
367369
*/
368370
tsTrace?: (str: string) => void;
369371
/**
370-
* TODO DOCS YAY
372+
* Enable native ESM support.
373+
*
374+
* For details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules
371375
*/
372376
esm?: boolean;
373377
/**
@@ -392,6 +396,8 @@ export interface OptionBasePaths {
392396

393397
/**
394398
* Options for registering a TypeScript compiler instance globally.
399+
400+
* @category Basic
395401
*/
396402
export interface RegisterOptions extends CreateOptions {
397403
/**
@@ -548,10 +554,14 @@ export function getExtensions(config: _ts.ParsedCommandLine) {
548554

549555
/**
550556
* Create a new TypeScript compiler instance and register it onto node.js
557+
558+
* @category Basic
551559
*/
552560
export function register(opts?: RegisterOptions): Service;
553561
/**
554562
* Register TypeScript compiler instance onto node.js
563+
564+
* @category Basic
555565
*/
556566
export function register(service: Service): Service;
557567
export function register(
@@ -591,6 +601,8 @@ export function register(
591601

592602
/**
593603
* Create TypeScript compiler instance.
604+
*
605+
* @category Basic
594606
*/
595607
export function create(rawOptions: CreateOptions = {}): Service {
596608
const foundConfigResult = findAndReadConfig(rawOptions);
@@ -1585,6 +1597,8 @@ function getTokenAtPosition(
15851597
*
15861598
* Node changed the hooks API, so there are two possible APIs. This function
15871599
* detects your node version and returns the appropriate API.
1600+
*
1601+
* @category ESM Loader
15881602
*/
15891603
export const createEsmHooks: typeof createEsmHooksFn = (
15901604
tsNodeService: Service

‎src/repl.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ export interface ReplService {
115115
readonly console: Console;
116116
}
117117

118+
/** @category REPL */
118119
export interface CreateReplOptions {
119120
service?: Service;
120121
state?: EvalState;
@@ -144,6 +145,8 @@ export interface CreateReplOptions {
144145
* const service = tsNode.create({...repl.evalAwarePartialHost});
145146
* repl.setService(service);
146147
* repl.start();
148+
*
149+
* @category REPL
147150
*/
148151
export function createRepl(options: CreateReplOptions = {}) {
149152
const { ignoreDiagnosticsThatAreAnnoyingInInteractiveRepl = true } = options;

‎src/transpilers/types.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,21 @@ import type { ProjectLocalResolveHelper } from '../util';
55
/**
66
* Third-party transpilers are implemented as a CommonJS module with a
77
* named export "create"
8+
*
9+
* @category Transpiler
810
*/
911
export interface TranspilerModule {
1012
create: TranspilerFactory;
1113
}
1214
/**
1315
* Called by ts-node to create a custom transpiler.
16+
*
17+
* @category Transpiler
1418
*/
1519
export type TranspilerFactory = (
1620
options: CreateTranspilerOptions
1721
) => Transpiler;
22+
/** @category Transpiler */
1823
export interface CreateTranspilerOptions {
1924
// TODO this is confusing because its only a partial Service. Rename?
2025
// Careful: must avoid stripInternal breakage by guarding with Extract<>
@@ -30,15 +35,18 @@ export interface CreateTranspilerOptions {
3035
*/
3136
transpilerConfigLocalResolveHelper: ProjectLocalResolveHelper;
3237
}
38+
/** @category Transpiler */
3339
export interface Transpiler {
3440
// TODOs
3541
// Create spec for returning diagnostics? Currently transpilers are allowed to
3642
// throw an error but that's it.
3743
transpile(input: string, options: TranspileOptions): TranspileOutput;
3844
}
45+
/** @category Transpiler */
3946
export interface TranspileOptions {
4047
fileName: string;
4148
}
49+
/** @category Transpiler */
4250
export interface TranspileOutput {
4351
outputText: string;
4452
diagnostics?: ts.Diagnostic[];

‎tsconfig.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@
2424
"typedocOptions": {
2525
"entryPoints": ["./src/index.ts"],
2626
"readme": "none",
27-
"out": "website/static/api"
27+
"out": "website/static/api",
28+
"excludeTags": ["allof"],
29+
"categorizeByGroup": false,
30+
"categoryOrder": ["Basic", "REPL", "Transpiler", "ESM Loader", "Other"],
31+
"defaultCategory": "Other"
2832
}
2933
}

‎website/docs/api.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: API
3+
---
4+
5+
ts-node's complete API is documented here: [API Docs](https://typestrong.org/ts-node/api/)
6+
7+
Here are a few highlights of what you can accomplish:
8+
9+
- [`create()`](https://typestrong.org/ts-node/api/index.html#create) creates ts-node's compiler service without
10+
registering any hooks.
11+
- [`createRepl()`](https://typestrong.org/ts-node/api/index.html#createRepl) creates an instance of our REPL service, so
12+
you can create your own TypeScript-powered REPLs.
13+
- [`createEsmHooks()`](https://typestrong.org/ts-node/api/index.html#createEsmHooks) creates our ESM loader hooks,
14+
suitable for composing with other loaders or augmenting with additional features.

‎website/docs/imports.md‎ renamed to ‎website/docs/commonjs-vs-native-ecmascript-modules.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: "CommonJS vs native ECMAScript modules"
3+
slug: imports
34
---
45

56
TypeScript is almost always written using modern `import` syntax, but it is also transformed before being executed by the underlying runtime. You can choose to either transform to CommonJS or to preserve the native `import` syntax, using node's native ESM support. Configuration is different for each.

‎website/docs/how-it-works.md‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,9 @@
11
---
2-
title: How It Works
2+
title: How it works
33
---
44

55
ts-node works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions.
66

77
Vanilla `node` loads `.js` by reading code from disk and executing it. Our hook runs in the middle, transforming code from TypeScript to JavaScript and passing the result to `node` for execution. This transformation will respect your `tsconfig.json` as if you had compiled via `tsc`.
88

9-
`.js` and `.jsx` are only transformed when [`allowJs`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) is enabled.
10-
11-
`.tsx` and `.jsx` are only transformed when [`jsx`](https://www.typescriptlang.org/docs/handbook/jsx.html) is enabled.
12-
13-
> **Warning:** if a file is ignored or its file extension is not registered, node will either fail to resolve the file or will attempt to execute it as JavaScript without any transformation. This may cause syntax errors or other failures, because node does not understand TypeScript type syntax nor bleeding-edge ECMAScript features.
14-
15-
> **Warning:** When ts-node is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler.
16-
17-
## Skipping `node_modules`
18-
19-
By default, ts-node avoids compiling files in `/node_modules/` for three reasons:
20-
21-
1. Modules should always be published in a format node.js can consume
22-
2. Transpiling the entire dependency tree will make your project slower
23-
3. Differing behaviours between TypeScript and node.js (e.g. ES2015 modules) can result in a project that works until you decide to support a feature natively from node.js
24-
25-
If you need to import uncompiled TypeScript in `node_modules`, use [`--skipIgnore`](./options#transpilation) or [`TS_NODE_SKIP_IGNORE`](./options#transpilation) to bypass this restriction.
26-
27-
## Skipping pre-compiled TypeScript
28-
29-
If a compiled JavaScript file with the same name as a TypeScript file already exists, the TypeScript file will be ignored. ts-node will import the pre-compiled JavaScript.
30-
31-
To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](./options#transpilation).
9+
We also register a few other hooks to apply sourcemaps to stack traces and remap from `.js` imports to `.ts`.

0 commit comments

Comments
 (0)