Fix twoslash in AppHostBuilder; source-control twoslash .d.ts bundle (#741)

The homepage AppHostBuilder component rendered a ts(2307) 'Cannot find module ./.modules/aspire.js' error in the TypeScript view on production, while MDX fenced samples on /get-started/first-app/ worked fine. Root cause: Starlight's <Code> component resolves expressive-code config through astro-expressive-code's virtual module, which loses the runtime extraFiles VFS state in production builds; MDX fences flow through rehype-expressive-code with the live ec.config.mjs instance intact.

Changes:

- Remove meta=twoslash from AppHostBuilder.astro (not desired there anyway).

- Relocate the generated aspire.d.ts bundle from transient .twoslash-types/ to source-controlled src/frontend/src/data/twoslash/aspire.d.ts so diffs are reviewable and dev/build startup is faster (no pre-build generation step).

- Chain generate-twoslash-types.ts to run at the tail of update-ts-api.ts so the bundle stays in sync with src/data/ts-modules/*.json.

- Drop pnpm twoslash-types from dev/start/build scripts in package.json; keep the manual pnpm twoslash-types script for ad-hoc refreshes.

- Update ec.config.mjs, the vitest generator test, .gitignore, and the update-integrations SKILL.md to match the new location and workflow.

Validated: unit tests pass (6/6); Playwright crawl against localhost:4321 across 22 docs pages with twoslash blocks reports 0 twoslash errors and rendered hovers intact.

Author: IEvangelist

.github/skills/update-integrations/SKILL.md

@@ -15,6 +15,7 @@ The aspire.dev site maintains three key data locations:
 - **`src/frontend/src/data/integration-docs.json`** — Mappings from package names to site-relative documentation URLs.
 - **`src/frontend/src/data/pkgs/`** — Per-package API reference JSON files (e.g. `Aspire.Hosting.Redis.13.1.2.json`) generated by the `PackageJsonGenerator` tool. These feed the auto-generated API reference pages at `/reference/api/`.
 - **`src/frontend/src/data/ts-modules/`** — Per-package TypeScript API reference JSON files (e.g. `Aspire.Hosting.Redis.13.2.0.json`) generated by the `AtsJsonGenerator` tool. These feed the auto-generated TypeScript API reference pages at `/reference/api/typescript/`.
+- **`src/frontend/src/data/twoslash/aspire.d.ts`** — A single consolidated TypeScript declaration bundle generated from the `ts-modules` JSON by `scripts/generate-twoslash-types.ts`. Consumed by `expressive-code-twoslash` to provide hover tooltips for TypeScript code samples in the docs. **Source-controlled** — commit the diff whenever `ts-modules` changes.
 
 This skill keeps the documentation mappings in sync with the package catalog and regenerates both the C# and TypeScript API reference data.
 
@@ -200,6 +201,12 @@ The companion `generate-ts-api-json.ps1` script reads the generated C# package J
 
 When a TypeScript module is regenerated for a new package version, stale `ts-modules` JSON files for older versions of that same package are deleted automatically.
 
+After the JSON is refreshed, `update-ts-api` automatically chains `generate-twoslash-types.ts` to rebuild `src/frontend/src/data/twoslash/aspire.d.ts`. This bundle is source-controlled and its diff must be committed alongside the `ts-modules` JSON changes — without it, docs hover tooltips fall back to `any`. If you only need to refresh the bundle (e.g. after a generator script change) without running the full SDK dump, use:
+
+```bash
+cd src/frontend && pnpm twoslash-types
+```
+
 ### 6. Verify all links
 
 For every entry in the updated `integration-docs.json`:
@@ -247,3 +254,4 @@ After running this skill, the agent should report:
 - Any packages that could not be mapped (flagged for manual review)
 - Number of API reference JSON files generated (success / failed / skipped)
 - Any packages that failed API generation, with reasons
+- Confirmation that `src/frontend/src/data/twoslash/aspire.d.ts` was refreshed (and that the diff will be committed)

.gitignore

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

src/frontend/ec.config.mjs

@@ -8,15 +8,15 @@ 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 ASPIRE_TYPES_PATH = resolve(__dirname, 'src/data/twoslash/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`');
+  console.warn('[ec] src/data/twoslash/aspire.d.ts missing — run `pnpm twoslash-types`');
 }
 
 /** @type {import('@astrojs/starlight/expressive-code').StarlightExpressiveCodeOptions} */

src/frontend/package.json

@@ -17,13 +17,13 @@
     "git-env": "node ./scripts/write-git-env.mjs",
     "check-data": "node ./scripts/check-data-files.mjs",
     "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",
+    "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",
     "preview": "astro preview",
     "preview:host": "astro preview --host",
     "astro": "pnpm git-env && astro",

src/frontend/scripts/generate-twoslash-types.ts

@@ -4,7 +4,8 @@
  * in the docs get accurate hover tooltips.
  *
  * Reads: src/data/ts-modules/*.json (produced by update-ts-api.ts)
- * Writes: .twoslash-types/aspire.d.ts
+ * Writes: src/data/twoslash/aspire.d.ts (source-controlled — commit updates
+ * after regenerating).
  */
 
 import { readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
@@ -14,7 +15,7 @@ import { fileURLToPath } from 'url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const MODULES_DIR = resolve(__dirname, '..', 'src', 'data', 'ts-modules');
 const PKGS_DIR = resolve(__dirname, '..', 'src', 'data', 'pkgs');
-const OUTPUT_DIR = resolve(__dirname, '..', '.twoslash-types');
+const OUTPUT_DIR = resolve(__dirname, '..', 'src', 'data', 'twoslash');
 const OUTPUT_FILE = resolve(OUTPUT_DIR, 'aspire.d.ts');
 
 interface Parameter {

src/frontend/scripts/update-ts-api.ts

@@ -79,6 +79,23 @@ function main(): void {
     console.error('❌ Generation failed:', getErrorMessage(error));
     process.exit(1);
   }
+
+  // Refresh the twoslash .d.ts bundle so docs hover tooltips stay in sync
+  // with the regenerated ts-modules JSON. The bundle is source-controlled
+  // at src/data/twoslash/aspire.d.ts — commit the diff alongside the JSON.
+  const generatorScript = resolve(__dirname, 'generate-twoslash-types.ts');
+  const tsxBin = resolve(__dirname, '..', 'node_modules', 'tsx', 'dist', 'cli.mjs');
+  console.log('🔄 Regenerating twoslash .d.ts bundle...');
+  try {
+    execFileSync(process.execPath, [tsxBin, generatorScript], {
+      stdio: 'inherit',
+      cwd: resolve(__dirname, '..'),
+    });
+    console.log('✅ Twoslash types refreshed (src/data/twoslash/aspire.d.ts).');
+  } catch (error: unknown) {
+    console.error('❌ Twoslash type generation failed:', getErrorMessage(error));
+    process.exit(1);
+  }
 }
 
 main();

src/frontend/src/components/AppHostBuilder.astro

@@ -1215,7 +1215,7 @@ await builder.build().run();`,
             data-variant={key}
             style={key === 'frontend' ? '' : 'display: none;'}
           >
-            <Code code={code} lang="ts" title="apphost.ts" meta="twoslash" />
+            <Code code={code} lang="ts" title="apphost.ts" />
           </div>
         ))
       }