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

.prettierignore

@@ -8,6 +8,7 @@
 !/tests
 !/website
 /website/.docusaurus
+/website/build
 /website/docs
 /website/readme-sources
 /website/static

src/index.ts

@@ -183,6 +183,8 @@ export const VERSION = require('../package.json').version;
 
 /**
  * Options for creating a new TypeScript compiler instance.
+
+ * @category Basic
  */
 export interface CreateOptions {
   /**
@@ -367,7 +369,9 @@ export interface CreateOptions {
    */
   tsTrace?: (str: string) => void;
   /**
-   * TODO DOCS YAY
+   * Enable native ESM support.
+   *
+   * For details, see https://typestrong.org/ts-node/docs/imports#native-ecmascript-modules
    */
   esm?: boolean;
   /**
@@ -392,6 +396,8 @@ export interface OptionBasePaths {
 
 /**
  * Options for registering a TypeScript compiler instance globally.
+
+ * @category Basic
  */
 export interface RegisterOptions extends CreateOptions {
   /**
@@ -548,10 +554,14 @@ export function getExtensions(config: _ts.ParsedCommandLine) {
 
 /**
  * Create a new TypeScript compiler instance and register it onto node.js
+
+ * @category Basic
  */
 export function register(opts?: RegisterOptions): Service;
 /**
  * Register TypeScript compiler instance onto node.js
+
+ * @category Basic
  */
 export function register(service: Service): Service;
 export function register(
@@ -591,6 +601,8 @@ export function register(
 
 /**
  * Create TypeScript compiler instance.
+ *
+ * @category Basic
  */
 export function create(rawOptions: CreateOptions = {}): Service {
   const foundConfigResult = findAndReadConfig(rawOptions);
@@ -1585,6 +1597,8 @@ function getTokenAtPosition(
  *
  * Node changed the hooks API, so there are two possible APIs.  This function
  * detects your node version and returns the appropriate API.
+ *
+ * @category ESM Loader
  */
 export const createEsmHooks: typeof createEsmHooksFn = (
   tsNodeService: Service

src/repl.ts

@@ -115,6 +115,7 @@ export interface ReplService {
   readonly console: Console;
 }
 
+/** @category REPL */
 export interface CreateReplOptions {
   service?: Service;
   state?: EvalState;
@@ -144,6 +145,8 @@ export interface CreateReplOptions {
  *     const service = tsNode.create({...repl.evalAwarePartialHost});
  *     repl.setService(service);
  *     repl.start();
+ *
+ * @category REPL
  */
 export function createRepl(options: CreateReplOptions = {}) {
   const { ignoreDiagnosticsThatAreAnnoyingInInteractiveRepl = true } = options;

src/transpilers/types.ts

@@ -5,16 +5,21 @@ import type { ProjectLocalResolveHelper } from '../util';
 /**
  * Third-party transpilers are implemented as a CommonJS module with a
  * named export "create"
+ *
+ * @category Transpiler
  */
 export interface TranspilerModule {
   create: TranspilerFactory;
 }
 /**
  * Called by ts-node to create a custom transpiler.
+ *
+ * @category Transpiler
  */
 export type TranspilerFactory = (
   options: CreateTranspilerOptions
 ) => Transpiler;
+/** @category Transpiler */
 export interface CreateTranspilerOptions {
   // TODO this is confusing because its only a partial Service.  Rename?
   // Careful: must avoid stripInternal breakage by guarding with Extract<>
@@ -30,15 +35,18 @@ export interface CreateTranspilerOptions {
    */
   transpilerConfigLocalResolveHelper: ProjectLocalResolveHelper;
 }
+/** @category Transpiler */
 export interface Transpiler {
   // TODOs
   // Create spec for returning diagnostics?  Currently transpilers are allowed to
   // throw an error but that's it.
   transpile(input: string, options: TranspileOptions): TranspileOutput;
 }
+/** @category Transpiler */
 export interface TranspileOptions {
   fileName: string;
 }
+/** @category Transpiler */
 export interface TranspileOutput {
   outputText: string;
   diagnostics?: ts.Diagnostic[];

tsconfig.json

@@ -24,6 +24,10 @@
   "typedocOptions": {
     "entryPoints": ["./src/index.ts"],
     "readme": "none",
-    "out": "website/static/api"
+    "out": "website/static/api",
+    "excludeTags": ["allof"],
+    "categorizeByGroup": false,
+    "categoryOrder": ["Basic", "REPL", "Transpiler", "ESM Loader", "Other"],
+    "defaultCategory": "Other"
   }
 }

website/docs/api.md

@@ -0,0 +1,14 @@
+---
+title: API
+---
+
+ts-node's complete API is documented here: [API Docs](https://typestrong.org/ts-node/api/)
+
+Here are a few highlights of what you can accomplish:
+
+- [`create()`](https://typestrong.org/ts-node/api/index.html#create) creates ts-node's compiler service without
+registering any hooks.
+- [`createRepl()`](https://typestrong.org/ts-node/api/index.html#createRepl) creates an instance of our REPL service, so
+you can create your own TypeScript-powered REPLs.
+- [`createEsmHooks()`](https://typestrong.org/ts-node/api/index.html#createEsmHooks) creates our ESM loader hooks,
+suitable for composing with other loaders or augmenting with additional features.

website/docs/imports.md → website/docs/commonjs-vs-native-ecmascript-modules.md

@@ -1,5 +1,6 @@
 ---
 title: "CommonJS vs native ECMAScript modules"
+slug: imports
 ---
 
 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

@@ -1,31 +1,9 @@
 ---
-title: How It Works
+title: How it works
 ---
 
 ts-node works by registering hooks for `.ts`, `.tsx`, `.js`, and/or `.jsx` extensions.
 
 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`.
 
-`.js` and `.jsx` are only transformed when [`allowJs`](https://www.typescriptlang.org/docs/handbook/compiler-options.html#compiler-options) is enabled.
-
-`.tsx` and `.jsx` are only transformed when [`jsx`](https://www.typescriptlang.org/docs/handbook/jsx.html) is enabled.
-
-> **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.
-
-> **Warning:** When ts-node is used with `allowJs`, all non-ignored JavaScript files are transformed using the TypeScript compiler.
-
-## Skipping `node_modules`
-
-By default, ts-node avoids compiling files in `/node_modules/` for three reasons:
-
-1. Modules should always be published in a format node.js can consume
-2. Transpiling the entire dependency tree will make your project slower
-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
-
-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.
-
-## Skipping pre-compiled TypeScript
-
-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.
-
-To force ts-node to import the TypeScript source, not the precompiled JavaScript, use [`--preferTsExts`](./options#transpilation).
+We also register a few other hooks to apply sourcemaps to stack traces and remap from `.js` imports to `.ts`.