TypeScript (#1632)

* TypeScript

* verbatimModuleSyntax

* TypeScript docs

* JavaScript inline expressions

---------

Co-authored-by: Philippe Rivière <fil@rezo.net>

Author: mbostock

docs/imports.md

@@ -101,7 +101,7 @@ Imports from `node_modules` are cached in `.observablehq/cache/_node` within you
 
 ## Local imports
 
-You can import JavaScript modules from local files. This is useful for organizing your code into modules that can be imported across multiple pages. You can also unit test your code and share code with other web applications.
+You can import [JavaScript](./javascript) and [TypeScript](./javascript#type-script) modules from local files. This is useful for organizing your code into modules that can be imported across multiple pages. You can also unit test your code and share code with other web applications.
 
 For example, if this is `foo.js`:
 

docs/javascript.md

@@ -86,7 +86,7 @@ html`<span style=${{color: `hsl(${(now / 10) % 360} 100% 50%)`}}>Rainbow text!</
 
 ## Inline expressions
 
-Inline expressions <code>$\{…}</code> interpolate values into Markdown. They are typically used to display numbers such as metrics, or to arrange visual elements such as charts into rich HTML layouts.
+JavaScript inline expressions <code>$\{…}</code> interpolate values into Markdown. They are typically used to display numbers such as metrics, or to arrange visual elements such as charts into rich HTML layouts.
 
 For example, this paragraph simulates rolling a 20-sided dice:
 
@@ -127,6 +127,22 @@ const number = Generators.input(numberInput);
 
 Expressions cannot declare top-level reactive variables. To declare a variable, use a code block instead. You can declare a variable in a code block (without displaying it) and then display it somewhere else using an inline expression.
 
+## TypeScript <a href="https://github.com/observablehq/framework/pull/1632" class="observablehq-version-badge" data-version="prerelease" title="Added in #1632"></a>
+
+TypeScript fenced code blocks (<code>```ts</code>) allow TypeScript to be used in place of JavaScript. You can also import TypeScript modules (`.ts`). Use the `.js` file extension when importing TypeScript modules; TypeScript is transpiled to JavaScript during build.
+
+<div class="warning">
+
+Framework does not perform type checking during preview or build. If you want the additional safety of type checks, considering using [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html).
+
+</div>
+
+<div class="note">
+
+TypeScript fenced code blocks do not currently support [implicit display](#implicit-display), and TypeScript is not currently allowed in [inline expressions](#inline-expressions).
+
+</div>
+
 ## Explicit display
 
 The built-in [`display` function](#display-value) displays the specified value.

docs/jsx.md

@@ -1,6 +1,8 @@
 # JSX <a href="https://github.com/observablehq/framework/releases/tag/v1.9.0" class="observablehq-version-badge" data-version="^1.9.0" title="Added in 1.9.0"></a>
 
-[React](https://react.dev/) is a popular and powerful library for building interactive interfaces. React is typically written in [JSX](https://react.dev/learn/writing-markup-with-jsx), an extension of JavaScript that allows HTML-like markup. To use JSX and React, declare a JSX fenced code block (<code>```jsx</code>). For example, to define a `Greeting` component that accepts a `subject` prop:
+[React](https://react.dev/) is a popular and powerful library for building interactive interfaces. React is typically written in [JSX](https://react.dev/learn/writing-markup-with-jsx), an extension of JavaScript that allows HTML-like markup. To use JSX and React, declare a JSX fenced code block (<code>\```jsx</code>). You can alternatively use a TSX fenced code block (<code>\```tsx</code>) if using JSX with [TypeScript](./javascript#type-script).
+
+For example, to define a `Greeting` component that accepts a `subject` prop:
 
 ````md
 ```jsx

src/javascript/module.ts

@@ -4,6 +4,7 @@ import {accessSync, constants, readFileSync, statSync} from "node:fs";
 import {readFile} from "node:fs/promises";
 import {extname, join} from "node:path/posix";
 import type {Program} from "acorn";
+import type {TransformOptions} from "esbuild";
 import {transform, transformSync} from "esbuild";
 import {resolveNodeImport} from "../node.js";
 import {resolveNpmImport} from "../npm.js";
@@ -221,34 +222,72 @@ export function findModule(root: string, path: string): RouteResult | undefined
   const ext = extname(path);
   if (!ext) throw new Error(`empty extension: ${path}`);
   const exts = [ext];
-  if (ext === ".js") exts.push(".jsx");
+  if (ext === ".js") exts.push(".ts", ".jsx", ".tsx");
   return route(root, path.slice(0, -ext.length), exts);
 }
 
 export async function readJavaScript(sourcePath: string): Promise<string> {
   const source = await readFile(sourcePath, "utf-8");
-  if (sourcePath.endsWith(".jsx")) {
-    const {code} = await transform(source, {
-      loader: "jsx",
-      jsx: "automatic",
-      jsxImportSource: "npm:react",
-      sourcefile: sourcePath
-    });
-    return code;
+  switch (extname(sourcePath)) {
+    case ".ts":
+      return transformJavaScript(source, "ts", sourcePath);
+    case ".jsx":
+      return transformJavaScript(source, "jsx", sourcePath);
+    case ".tsx":
+      return transformJavaScript(source, "tsx", sourcePath);
   }
   return source;
 }
 
 export function readJavaScriptSync(sourcePath: string): string {
   const source = readFileSync(sourcePath, "utf-8");
-  if (sourcePath.endsWith(".jsx")) {
-    const {code} = transformSync(source, {
-      loader: "jsx",
-      jsx: "automatic",
-      jsxImportSource: "npm:react",
-      sourcefile: sourcePath
-    });
-    return code;
+  switch (extname(sourcePath)) {
+    case ".ts":
+      return transformJavaScriptSync(source, "ts", sourcePath);
+    case ".jsx":
+      return transformJavaScriptSync(source, "jsx", sourcePath);
+    case ".tsx":
+      return transformJavaScriptSync(source, "tsx", sourcePath);
   }
   return source;
 }
+
+export async function transformJavaScript(
+  source: string,
+  loader: "ts" | "jsx" | "tsx",
+  sourcePath?: string
+): Promise<string> {
+  return (await transform(source, getTransformOptions(loader, sourcePath))).code;
+}
+
+export function transformJavaScriptSync(source: string, loader: "ts" | "jsx" | "tsx", sourcePath?: string): string {
+  return transformSync(source, getTransformOptions(loader, sourcePath)).code;
+}
+
+function getTransformOptions(loader: "ts" | "jsx" | "tsx", sourcePath?: string): TransformOptions {
+  switch (loader) {
+    case "ts":
+      return {
+        loader,
+        sourcefile: sourcePath,
+        tsconfigRaw: '{"compilerOptions": {"verbatimModuleSyntax": true}}'
+      };
+    case "jsx":
+      return {
+        loader,
+        jsx: "automatic",
+        jsxImportSource: "npm:react",
+        sourcefile: sourcePath
+      };
+    case "tsx":
+      return {
+        loader,
+        jsx: "automatic",
+        jsxImportSource: "npm:react",
+        sourcefile: sourcePath,
+        tsconfigRaw: '{"compilerOptions": {"verbatimModuleSyntax": true}}'
+      };
+    default:
+      throw new Error(`unknown loader: ${loader}`);
+  }
+}

src/loader.ts

@@ -256,8 +256,11 @@ export class LoaderResolver {
     const exactPath = join(this.root, path);
     if (existsSync(exactPath)) return exactPath;
     if (exactPath.endsWith(".js")) {
-      const jsxPath = exactPath + "x";
-      if (existsSync(jsxPath)) return jsxPath;
+      const basePath = exactPath.slice(0, -".js".length);
+      for (const ext of [".ts", ".jsx", ".tsx"]) {
+        const extPath = basePath + ext;
+        if (existsSync(extPath)) return extPath;
+      }
       return; // loaders aren’t supported for .js
     }
     const foundPath = this.find(path)?.path;

src/markdown.ts

@@ -1,7 +1,6 @@
 /* eslint-disable import/no-named-as-default-member */
 import {createHash} from "node:crypto";
 import slugify from "@sindresorhus/slugify";
-import {transformSync} from "esbuild";
 import he from "he";
 import MarkdownIt from "markdown-it";
 import type {Token} from "markdown-it";
@@ -15,6 +14,7 @@ import type {FrontMatter} from "./frontMatter.js";
 import {readFrontMatter} from "./frontMatter.js";
 import {html, rewriteHtmlPaths} from "./html.js";
 import {parseInfo} from "./info.js";
+import {transformJavaScriptSync} from "./javascript/module.js";
 import type {JavaScriptNode} from "./javascript/parse.js";
 import {parseJavaScript} from "./javascript/parse.js";
 import {isAssetPath, relativePath} from "./path.js";
@@ -63,9 +63,9 @@ function isFalse(attribute: string | undefined): boolean {
   return attribute?.toLowerCase() === "false";
 }
 
-function transformJsx(content: string): string {
+function transpileJavaScript(content: string, tag: "ts" | "jsx" | "tsx"): string {
   try {
-    return transformSync(content, {loader: "jsx", jsx: "automatic", jsxImportSource: "npm:react"}).code;
+    return transformJavaScriptSync(content, tag);
   } catch (error: any) {
     throw new SyntaxError(error.message);
   }
@@ -74,8 +74,8 @@ function transformJsx(content: string): string {
 function getLiveSource(content: string, tag: string, attributes: Record<string, string>): string | undefined {
   return tag === "js"
     ? content
-    : tag === "jsx"
-    ? transformJsx(content)
+    : tag === "ts" || tag === "jsx" || tag === "tsx"
+    ? transpileJavaScript(content, tag)
     : tag === "tex"
     ? transpileTag(content, "tex.block", true)
     : tag === "html"
@@ -123,7 +123,7 @@ function makeFenceRenderer(baseRenderer: RenderRule): RenderRule {
         const id = uniqueCodeId(context, source);
         // TODO const sourceLine = context.startLine + context.currentLine;
         const node = parseJavaScript(source, {path, params});
-        context.code.push({id, node, mode: tag === "jsx" ? "jsx" : "block"});
+        context.code.push({id, node, mode: tag === "jsx" || tag === "tsx" ? "jsx" : "block"});
         html += `<div class="observablehq observablehq--block">${
           node.expression ? "<observablehq-loading></observablehq-loading>" : ""
         }<!--:${id}:--></div>\n`;
@@ -188,6 +188,7 @@ function makePlaceholderRenderer(): RenderRule {
     const id = uniqueCodeId(context, token.content);
     try {
       // TODO sourceLine: context.startLine + context.currentLine
+      // TODO allow TypeScript?
       const node = parseJavaScript(token.content, {path, params, inline: true});
       context.code.push({id, node, mode: "inline"});
       return `<observablehq-loading></observablehq-loading><!--:${id}:-->`;

test/input/build/typescript/index.md

@@ -0,0 +1,21 @@
+```ts echo
+function add(a: number, b: number): number {
+  return a + b;
+}
+```
+
+```js echo
+add(1, 3)
+```
+
+```ts echo
+add(1 as number, 3)
+```
+
+```ts echo
+import {sum} from "./sum.js";
+```
+
+```ts echo
+sum(1, 2)
+```

test/input/build/typescript/sum.ts

@@ -0,0 +1,3 @@
+export function sum(a: number, b: number): number {
+  return a + b;
+}

test/output/build/typescript/_import/sum.fd55756b.js

@@ -0,0 +1,3 @@
+export function sum(a, b) {
+  return a + b;
+}