Skip to content

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

Merged
IEvangelist merged 1 commit intomainfrom
dapine/ts-twoslash-source-control
Apr 21, 2026
Merged

Fix twoslash in AppHostBuilder; source-control twoslash .d.ts bundle#741
IEvangelist merged 1 commit intomainfrom
dapine/ts-twoslash-source-control

Conversation

@IEvangelist
Copy link
Copy Markdown
Member

Summary

The homepage AppHostBuilder component rendered a ts(2307) Cannot find module './.modules/aspire.js' error in the TypeScript view on aspire.dev, while MDX fenced samples (e.g. /get-started/first-app/?aspire-lang=typescript) 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 — which is why the two paths diverged in prod but behaved identically in dev (shared Vite module graph).

Changes

  • Remove meta="twoslash" from AppHostBuilder.astro — it wasn't wanted there anyway, and the component's TS view now renders as plain syntax-highlighted code.
  • Source-control the generated type bundle at src/frontend/src/data/twoslash/aspire.d.ts instead of producing it transiently under .twoslash-types/. Diffs are reviewable and dev/build startup is faster (no pre-build generation step).
  • Chain regeneration into scripts/update-ts-api.ts so aspire.d.ts stays in sync with src/data/ts-modules/*.json whenever the SDK is re-dumped.
  • Drop pnpm twoslash-types from dev/start/build scripts in package.json; the manual pnpm twoslash-types script is kept 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.

Validation

  • Unit tests: 6/6 pass (twoslash-types-generator.vitest.test.ts).
  • Playwright crawl against localhost:4321 across all 22 docs pages containing twoslash blocks: 0 twoslash errors, hovers render intact (including /app-host/container-registry/ with 194 hovers and /whats-new/aspire-13-2/ with 108 hovers).
  • Homepage AppHostBuilder TS view now renders without the ts(2307) error.

Opened as draft for review.

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.
@IEvangelist IEvangelist marked this pull request as ready for review April 21, 2026 18:12
Copilot AI review requested due to automatic review settings April 21, 2026 18:12
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Fixes a production-only twoslash resolution issue in the homepage AppHostBuilder TypeScript view by removing twoslash from that component path and moving the generated twoslash .d.ts bundle to a source-controlled location so hover types remain stable across build modes.

Changes:

  • Remove meta="twoslash" from the homepage AppHostBuilder code panel to avoid triggering broken twoslash resolution.
  • Store the consolidated twoslash declaration bundle under src/data/twoslash/aspire.d.ts and update config/tests/scripts to use it.
  • Chain twoslash bundle regeneration into update-ts-api and remove automatic generation from dev/build scripts.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated no comments.

Show a summary per file
File Description
src/frontend/tests/unit/twoslash-types-generator.vitest.test.ts Updates the generator test to regenerate/read the now source-controlled aspire.d.ts bundle in place.
src/frontend/src/components/AppHostBuilder.astro Removes twoslash meta from the homepage code view to prevent the prod-only module resolution failure.
src/frontend/scripts/update-ts-api.ts Regenerates the twoslash .d.ts bundle after updating ts-modules so hover types stay in sync.
src/frontend/scripts/generate-twoslash-types.ts Redirects generator output to src/data/twoslash/aspire.d.ts and updates documentation comments.
src/frontend/package.json Drops pnpm twoslash-types from dev/start/build since the bundle is now checked in.
src/frontend/ec.config.mjs Points expressive-code-twoslash at the new src/data/twoslash/aspire.d.ts location.
.gitignore Removes the now-unused .twoslash-types/ ignore entry.
.github/skills/update-integrations/SKILL.md Documents the new bundle location and the updated regeneration workflow.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@IEvangelist IEvangelist merged commit 4a4fdc0 into main Apr 21, 2026
9 checks passed
@IEvangelist IEvangelist deleted the dapine/ts-twoslash-source-control branch April 21, 2026 19:11
slang25 added a commit to slang25/aspire.dev that referenced this pull request Apr 21, 2026
Two small defensive changes on top of microsoft#741:

- Throw instead of warn when src/data/twoslash/aspire.d.ts is missing.
  Since microsoft#741 source-controls the bundle, a missing file means the tree
  is corrupted — catching that at build time beats silently shipping
  samples that can't resolve `./.modules/aspire.js`.
- Flip noErrorValidation to false so unannotated TS errors fail the
  build rather than rendering as squigglies in the shipped HTML.
  Samples that deliberately illustrate a compiler error can opt in
  with `// @errors: <codes>`; otherwise an error means the sample
  (or the generated SDK shape) is wrong and should be fixed, not
  shown to readers. Verified with a full build: zero unannotated
  errors across the current docs.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants