Add TypeScript twoslash support to docs code blocks (#729)

* Add TypeScript twoslash support to docs code blocks

Wires up expressive-code-twoslash with a generated Aspire SDK .d.ts
so TS samples get hover types. Adds the `twoslash` meta to TS code
blocks across docs and the homepage AppHostBuilder component. Also
fixes nav bar / mobile TOC stacking at ≥72rem where expressive-code's
`:root .main-pane { z-index: 1 }` was trapping the TOC below content.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Remove @Noerrors from docs twoslash blocks

Inherit class baseType from src/data/pkgs/*.json so subclasses like
ViteAppResource/NodeAppResource/PythonAppResource pick up methods defined
on their parent class (publishAsDockerFile, publishAsHostedAgent). Fix
misaligned samples (withVolume args, withHostPort, publishAsExisting,
userNameParameter/passwordParameter, executionContext.isRunMode, redis
host/port accessors). Drop twoslash marker from the hypothetical
user-integration example where types don't resolve by design.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Let twoslash tooltips escape the AppHostBuilder container

Remove overflow:hidden from the outer .container so the popup
(positioned by floating-ui into the expressive-code wrapper) can extend
past the bottom edge. Top-corner rounding moves to .header to preserve
the visual against the container's rounded border.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Address PR review comments

- Add fallback value to --sl-z-index-toc var in site.css so the
  right-sidebar z-index still resolves when the CSS variable is absent
- Guard the twoslash popup-fix IIFE with window.__aspireTwoslashFixInitialized
  so document-level listeners only register once across Astro view transitions
- Downgrade typescript to ^5.9.3 to stay within the peer range declared by
  expressive-code-twoslash (^5.5.0)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Address additional PR review comments

- postgres-host.mdx: pass port directly to withHostPort(5050); the TS SDK
  signature takes a number, not an object
- ec.config.mjs: use canonical lib name 'es2022' instead of the filename
  'lib.es2022.d.ts' so TypeScript loads the standard library correctly
  during twoslash compilation
- ec.config.mjs: point the missing-types warning at the 'pnpm twoslash-types'
  script rather than the raw tsx invocation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Update src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx

Co-authored-by: David Pine <david.pine@microsoft.com>

* Update src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx

Co-authored-by: David Pine <david.pine@microsoft.com>

* Update src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx

Co-authored-by: David Pine <david.pine@microsoft.com>

* Address review round 2 on twoslash docs PR

- generate-twoslash-types.ts: type the JSON.parse results so the
  @typescript-eslint/no-unsafe-* rules pass (previously failed CI)
- Add tests/unit/twoslash-types-generator.vitest.test.ts covering the
  key shape of aspire.d.ts (createBuilder, IDistributedApplicationBuilder,
  class inheritance from pkgs/, camelCasing, options-object overloads)
  and wire test:unit:twoslash-types into the test:unit pipeline
- ec.config.mjs: drop the explicit `lib` array — twoslash's VFS only
  loads the lib files literally named in `lib`, so triple-slash
  references inside lib.es2022.d.ts (es5 → Date, dom → URL, etc.) were
  silently dropped. Letting `target: ESNext` pick lib.esnext.full.d.ts
  restores the full standard library. Also remove the now-redundant
  console.d.ts shim
- multi-language-integration-authoring.mdx: drop `twoslash` flag from
  the apphost.ts sample — the article shows authoring custom exported
  APIs that aren't part of the generated .d.ts, so the sample correctly
  uses hypothetical types
- executable-resources.mdx: publishAsDockerFile() takes no args
- migrate-from-docker-compose.mdx: switch withVolume() calls to the
  options-object overload as suggested

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Regenerate TS module JSON with AtsTransformer fixes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Make twoslash-types generator test cross-platform

execFileSync('pnpm', ...) fails on Windows with ENOENT because spawn doesn't resolve .cmd shims. Invoke tsx directly via node instead, which also sidesteps the DEP0190 warning from shell:true.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Stabilize frontend e2e CI by using astro preview + 60s timeout

Tests were flaking in CI (4-5 flaky + 1 failed each run) because playwright's webServer was running astro dev, and this PR's twoslash processing makes first-request page loads expensive. Under 2 parallel workers, concurrent requests for twoslash pages pegged the dev server, causing unrelated page.goto calls (e.g. on / and /get-started/install-cli/) to exceed the 30s test timeout.

Switch CI to astro preview (dist/ already exists from the Build frontend step) so pages are served as static files. Kept astro dev for local dev so interactive work doesn't require a rebuild. Also bumped per-test timeout to 60s as a safety net against any residual slow pages.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Set E2E_TESTS=1 at CI build time so cookie consent loads under preview

After switching CI's playwright webServer to astro preview, the 6 cookie-consent e2e tests began failing because hideFromBots in config/cookie.config.ts is evaluated at build time (read by astro.config.mjs at static build). Previously astro dev was started by playwright with E2E_TESTS=1 set, so the flag flipped correctly; under preview, the env has to be set during the preceding build step.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: David Pine <david.pine@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 4 people

.github/workflows/frontend-build.yml

@@ -75,6 +75,12 @@ jobs:
         env:
           MODE: production
           ASTRO_TELEMETRY_DISABLED: 1
+          # The built artifact is consumed by `astro preview` during the
+          # e2e step below. `config/cookie.config.ts` reads `E2E_TESTS`
+          # at build time to disable the cookie-consent bot check; without
+          # this, the preview serves a production-configured modal that
+          # playwright is mistaken for a bot and never opens.
+          E2E_TESTS: 1
         run: pnpm build:production
 
       # Upload before the dist sanity-check so the artifact is always

.gitignore

@@ -20,6 +20,7 @@ test-results/
 .astro/
 .cache/
 .netlify/
+.twoslash-types/
 tmp/
 
 # Logs

src/frontend/ec.config.mjs

@@ -1,10 +1,66 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
 import { pluginCollapsibleSections } from '@expressive-code/plugin-collapsible-sections';
 import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
+import ecTwoSlash from 'expressive-code-twoslash';
 import { pluginDisableCopy } from './src/expressive-code-plugins/disable-copy.mjs';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ASPIRE_TYPES_PATH = resolve(__dirname, '.twoslash-types/aspire.d.ts');
+const aspireTypes = existsSync(ASPIRE_TYPES_PATH)
+  ? readFileSync(ASPIRE_TYPES_PATH, 'utf8')
+  : '';
+
+if (!aspireTypes) {
+  // Non-fatal — twoslash blocks that import the SDK will just show `any`.
+  // Run `pnpm twoslash-types` to refresh.
+  console.warn('[ec] .twoslash-types/aspire.d.ts missing — run `pnpm twoslash-types`');
+}
+
 /** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */
 export default {
-  plugins: [pluginCollapsibleSections(), pluginLineNumbers(), pluginDisableCopy()],
+  plugins: [
+    pluginCollapsibleSections(),
+    pluginLineNumbers(),
+    pluginDisableCopy(),
+    ecTwoSlash({
+      // Only run on TS blocks that opt in via the `twoslash` meta flag.
+      instanceConfigs: {
+        // Docs samples use both `ts` and `typescript` fence languages; accept both.
+        twoslash: { explicitTrigger: true, languages: ['ts', 'tsx', 'typescript'] },
+      },
+      includeJsDoc: true,
+      twoslashOptions: {
+        compilerOptions: {
+          // ts.ModuleResolutionKind.Bundler so `./.modules/aspire.js` falls
+          // through to the virtual `.modules/aspire.ts` file declared below.
+          moduleResolution: 100,
+          // ts.ModuleKind.ESNext (paired with bundler resolution).
+          module: 99,
+          // ts.ScriptTarget.ESNext.
+          target: 99,
+          strict: true,
+          noEmit: true,
+          // Omit `lib` so twoslash falls back to `lib.esnext.full.d.ts`
+          // (target: ESNext) — that bundle pulls in `Date`, `URL`, DOM,
+          // and other common globals via triple-slash references. Pinning
+          // an explicit `lib` array breaks those references in the VFS.
+        },
+        handbookOptions: {
+          // Keep type squigglies rendered inline but don't fail the build when
+          // a sample has unannotated compiler errors — the generated SDK is a
+          // best-effort shape and docs samples shouldn't need `// @errors` tags.
+          noErrorValidation: true,
+        },
+        // Virtual files merged into the Twoslash VFS. The Aspire SDK types
+        // are declared at `.modules/aspire.ts` so docs samples that import
+        // `'./.modules/aspire.js'` resolve against the real API surface.
+        extraFiles: aspireTypes ? { '.modules/aspire.ts': aspireTypes } : {},
+      },
+    }),
+  ],
   defaultProps: {
     showLineNumbers: false,
   },

src/frontend/package.json

@@ -16,21 +16,23 @@
   "scripts": {
     "git-env": "node ./scripts/write-git-env.mjs",
     "check-data": "node ./scripts/check-data-files.mjs",
-    "dev": "pnpm git-env && pnpm check-data && astro dev",
-    "dev:host": "pnpm git-env && pnpm check-data && astro dev --host",
-    "start": "pnpm git-env && pnpm check-data && astro dev",
-    "start:host": "pnpm git-env && pnpm check-data && astro dev --host",
-    "build": "pnpm git-env && astro build",
-    "build:skip-search": "pnpm git-env && astro build --mode skip-search",
-    "build:production": "pnpm git-env && astro build --mode production",
+    "twoslash-types": "tsx ./scripts/generate-twoslash-types.ts",
+    "dev": "pnpm git-env && pnpm check-data && pnpm twoslash-types && astro dev",
+    "dev:host": "pnpm git-env && pnpm check-data && pnpm twoslash-types && astro dev --host",
+    "start": "pnpm git-env && pnpm check-data && pnpm twoslash-types && astro dev",
+    "start:host": "pnpm git-env && pnpm check-data && pnpm twoslash-types && astro dev --host",
+    "build": "pnpm git-env && pnpm twoslash-types && astro build",
+    "build:skip-search": "pnpm git-env && pnpm twoslash-types && astro build --mode skip-search",
+    "build:production": "pnpm git-env && pnpm twoslash-types && astro build --mode production",
     "preview": "astro preview",
     "preview:host": "astro preview --host",
     "astro": "pnpm git-env && astro",
     "test": "pnpm test:unit && pnpm test:e2e",
     "test:all": "pnpm lint && pnpm test",
-    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs && pnpm test:unit:api-markdown && pnpm test:unit:ts-api",
+    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs && pnpm test:unit:api-markdown && pnpm test:unit:ts-api && pnpm test:unit:twoslash-types",
     "test:unit:api-markdown": "vitest run --config vitest.config.ts tests/unit/api-markdown.vitest.test.ts",
     "test:unit:ts-api": "vitest run --config vitest.config.ts tests/unit/ts-api-routes.vitest.test.ts tests/unit/ts-api-search.vitest.test.ts",
+    "test:unit:twoslash-types": "vitest run --config vitest.config.ts tests/unit/twoslash-types-generator.vitest.test.ts",
     "test:unit:contracts": "vitest run --config vitest.config.ts tests/unit/analytics-script-contracts.vitest.test.ts",
     "test:unit:components": "vitest run --config vitest.config.ts tests/unit/custom-components.vitest.test.ts tests/unit/site-tour.vitest.test.ts",
     "test:unit:docs": "vitest run --config vitest.config.ts tests/unit/filetree-format.vitest.test.ts",
@@ -88,13 +90,15 @@
     "astro-vtbot": "^2.1.12",
     "eslint": "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
+    "expressive-code-twoslash": "^0.6.1",
     "globals": "^17.5.0",
     "http-proxy-agent": "^9.0.0",
     "https-proxy-agent": "^9.0.0",
     "node-fetch": "^3.3.2",
     "prettier": "^3.8.2",
     "prettier-plugin-astro": "^0.14.1",
     "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
     "typescript-eslint": "^8.58.2",
     "vitest": "^4.1.4"
   },

src/frontend/playwright.config.mjs

@@ -10,6 +10,10 @@ export default defineConfig({
   forbidOnly: isCI,
   retries: isCI ? 2 : 0,
   workers: isCI ? 2 : undefined,
+  // Default (30s) is tight once twoslash code blocks add server-side work
+  // during dev mode. 60s gives `page.goto` enough headroom without masking
+  // real regressions.
+  timeout: 60_000,
   reporter: isCI
     ? [
         ['github'],
@@ -50,7 +54,15 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: `pnpm git-env && pnpm check-data && astro dev --host 127.0.0.1 --port ${e2ePort}`,
+    // In CI the preceding `pnpm build:production` step has already produced
+    // `dist/`, so serve the built site via `astro preview`. Under `astro dev`
+    // the first request to each page triggers twoslash processing, which
+    // stacks up under parallel test workers and blows past the default
+    // 30s test timeout. Locally we keep `astro dev` so interactive work
+    // doesn't require a full rebuild.
+    command: isCI
+      ? `astro preview --host 127.0.0.1 --port ${e2ePort}`
+      : `pnpm git-env && pnpm check-data && astro dev --host 127.0.0.1 --port ${e2ePort}`,
     env: {
       ...process.env,
       ASTRO_TELEMETRY_DISABLED: '1',