[i18nIgnore] Transpile Starlight packages by HiDeoo · Pull Request #3572 · withastro/starlight

HiDeoo · 2025-11-26T13:42:21Z

Description

This PR is an early draft (not yet ready for review) that transpiles Starlight packages from TypeScript to JavaScript to avoid publishing TypeScript which is not a recommended or even supported practice.

Approach

Multiples approaches are usually available when it comes to transpiling in monorepos and keeping the flexibility of working with TypeScript source code in development.

Custom export condition was one of the first options considered, and would probably be the most long-term solution, but we cannot currently use them for Starlight. For the docs/ site to properly consume custom conditions in development, in Astro, such conditions would need to be defined in the Astro configuration using the vite property, altho Starlight itself is imported in such configuration so it's a chicken-and-egg problem right now. There is a world in the future where we would be able to run Astro using node --conditions directly, and Vite automatically picks up those conditions, but this requires some changes in Node that are not yet available.

Considering the above, this PR relies on pnpm and specifically on the fact that pnpm automatically overrides some fields in package.json files when packages are published with pnpm publish by the one defined in the package.json publishConfig property. In the case of Starlight, we maintain 2 exports fields: one for development (pointing to the TypeScript source files like it is today) and one for production (pointing to the transpiled JavaScript files).

How to test

When getting closer to a reviewable state, some pre-release packages will probably be published to test the changes in a real-world scenario.

In the meantime, you can test the changes locally using a different Starlight project outside of the monorepo, e.g. one setup using pnpm create astro --template starlight.

# Move to the Starlight package
$ cd packages/starlight
# Build the package
$ pnpm build
# Pack the package to a temporary location like it would be published
$ pnpm pack --pack-destination ~

# Move to your test Starlight project
$ cd ~/path/to/your/test/starlight/project/that/is/outside/of/the/monorepo
# Remove existing Starlight package
$ pnpm remove @astrojs/starlight && pnpm add ~/astrojs-starlight-0.41.7.tgz

Remaining tasks

Transpile Starlight packages
- Starlight
- DocSearch plugin
- Markdoc preset (nothing to do)
- Tailwind CSS (nothing to do)
Male sure our release workflow, specifically pnpm changeset publish uses pnpm publish under the hood (it probably does, as package-manager-detector is used when actually publishing to figure out the package manager but need to double check) (explained here: If you are using pnpm as a package manager, this automatically detects it and uses pnpm publish instead.)
Changesets

changeset-bot · 2025-11-26T13:42:25Z

🦋 Changeset detected

Latest commit: 491b69c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@astrojs/starlight	Minor
@astrojs/starlight-docsearch	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

netlify · 2025-11-26T13:42:28Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`491b69c`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/6a97eed92438210008202823
😎 Deploy Preview	https://deploy-preview-3572--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

delucis

I think this is ready when the time comes! 🚀

Thanks again @HiDeoo 💖

HiDeoo · 2026-09-01T09:44:01Z

Thanks for thorough review considering the amount of changes 🙌

Added a changeset for the main change, altho not sure I'm super happy with the wording but didn't find a better way to phrase it for now.

codspeed · 2026-09-01T17:18:57Z

Merging this PR will not alter performance

✅ 2 untouched benchmarks

_{Comparing HiDeoo:hd/feat-ts-to-js (491b69c) with main (0138f22)¹}

No successful run was found on main (f765c81) during the generation of this report, so 0138f22 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

* main: [i18nIgnore] Transpile Starlight packages (withastro#3572) i18n(ru): update translations (withastro#4170) [ci] release (withastro#4169) Fix hidden heading anchor links (withastro#4167) perf: optimize route and sidebar lookups (withastro#4148) chore: add benchmarks (withastro#4157)

michaelfaith · 2026-09-02T10:58:33Z

Woohoo! Thanks for all the work on this 🙌

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [@astrojs/starlight](https://starlight.astro.build) ([source](https://github.com/withastro/starlight/tree/HEAD/packages/starlight)) | [`0.41.11` → `0.42.0`](https://renovatebot.com/diffs/npm/@astrojs%2fstarlight/0.41.11/0.42.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/@astrojs%2fstarlight/0.42.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/@astrojs%2fstarlight/0.41.11/0.42.0?slim=true) | --- ### Release Notes <details> <summary>withastro/starlight (@astrojs/starlight)</summary> ### [`v0.42.0`](https://github.com/withastro/starlight/blob/HEAD/packages/starlight/CHANGELOG.md#0420) [Compare Source](https://github.com/withastro/starlight/compare/@astrojs/starlight@0.41.11...@astrojs/starlight@0.42.0) ##### Minor Changes - [#3572](withastro/starlight#3572) [`292fb17`](withastro/starlight@292fb17) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Distributes package as JavaScript files with dedicated type declaration files instead of TypeScript source files. - [#4121](withastro/starlight#4121) [`2623ae6`](withastro/starlight@2623ae6) Thanks [@delucis](https://github.com/delucis)! - Simplifies markup for Starlight’s mobile menu toggle **⚠️ Potentially breaking change:** If you use a theme plugin, custom styles, or component overrides targeting the `MobileMenuToggle` button or `PageFrame` components, you may need to adjust these for the new markup. The button is no longer wrapped in a `<starlight-menu-button>` custom element and no longer uses the `aria-expanded` attribute. Instead, you can use the `.sl-menu-button` class name to target the button and the `:popover-open` pseudo-class to style the menu open state specifically. In the following example, custom styles for the menu button are updated for the new approach: ```diff - starlight-menu-button button { + .sl-menu-button { color: var(--sl-color-text); } - starlight-menu-button[aria-expanded='true'] button { + .sl-menu-button:has(~ :popover-open) { color: var(--sl-color-text-accent-high); } ``` See [`MobileMenuToggle.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/MobileMenuToggle.astro) and [`PageFrame.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageFrame.astro) on GitHub for the full source code of the updated components. - [#3572](withastro/starlight#3572) [`292fb17`](withastro/starlight@292fb17) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Removes the `tagline` configuration option, which was never used. If your configuration included a `tagline` option, you can safely remove it without any replacement. - [#4134](withastro/starlight#4134) [`6135f01`](withastro/starlight@6135f01) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Updates internal `@astrojs/mdx`, `@astrojs/markdown-satteri`, and `satteri` dependencies. ⚠️ **BREAKING CHANGE:** The following minimum versions are now required: - `astro` v7.2.10 or later - `@astrojs/markdown-satteri` 0.4.0 or later (if you use it) - `@astrojs/markdown-remark` 7.3.0 or later (if you use it) Please update Starlight and Astro together: ```sh npx @astrojs/upgrade ``` - [#4121](withastro/starlight#4121) [`2623ae6`](withastro/starlight@2623ae6) Thanks [@delucis](https://github.com/delucis)! - Refactors Starlight’s mobile menu toggle to work when JavaScript fails or is disabled ⚠️ **BREAKING CHANGE:** This release drops official support for Chromium-based browsers prior to version 116 (released August 2023), Safari-based browsers prior to version 17.0 (released September 2023), and Firefox prior to version 125 (released April 2024). You can find a list of currently supported browsers and their versions using this [browserslist query](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+116%2C+Edge+%3E%3D+116%2C+Firefox+%3E%3D+125%2C+Safari+%3E%3D+17.0%2C+iOS+%3E%3D+17.0%2C+not+op_mini+all). This change also removes the `data-mobile-menu-expanded` attribute, which was previously added to `<body>` while the mobile menu is open. If you have custom code that was depending on this attribute, you will need to update it to use a new selector to check if the mobile menu is open. In the following example, a custom background colour for the site header while the menu is open is updated for the new approach: ```diff - [data-mobile-menu-expanded] header { + body:has(sl-sidebar-pane:popover-open) header { background-color: var(--sl-color-bg); } ``` </details> --- ### Configuration 📅 **Schedule**: (UTC) - Branch creation - At any time (no schedule defined) - Automerge - At any time (no schedule defined) 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).

…t stops the build Dependabot's grouped npm bump (#61) carries `@astrojs/starlight` 0.41.10 -> 0.42.0, and 0.42.0 removes the top-level `tagline` option outright. Starlight validates its config strictly, so an unrecognised key is a hard error rather than a warning: `astro sync` — the first thing all three site jobs run — dies with [AstroUserError] Invalid config passed to starlight integration Hint: Unrecognized key: "tagline" which reds "Static build and publication contract", "Lighthouse performance budgets" and "Browser, accessibility, privacy, and visual regression" together, plus the Vercel deployment. Three red jobs and one failed deploy, all one unrecognised key. The upstream entry (withastro/starlight#3572) is explicit about the migration: "Removes the `tagline` configuration option, which was never used" — no replacement, safe to delete. So the sentence this repo had been setting there ("Generated from the tagged source this site was built from.") rendered NOWHERE on 0.41 either. Deleting the key changes no pixel, and the comment in its place says that, plus where the fact belongs if it is worth surfacing: page content, not a key the framework ignored. Verified in the order that makes it evidence rather than hope: reproduced the CI failure locally FIRST (`astro sync` exit 1, same "Unrecognized key" hint) against the bumped lockfile, then applied the deletion and re-ran. - `astro sync` exit 0; `npm run build` 43 pages, exit 0. - `npm run test:static` exit 0 — 5 marketing routes + 33 docs pages + registry index + 2 blog + 1 compare validated, 117 research cross-links resolved, registry render contract verified. - `npx playwright test` **139 passed** — including the visual-regression suite against the committed darwin baselines, so the `lucide-react` 1.37 -> 1.41 and astro/react bumps riding along change no rendered pixel. That was the live risk in taking this group. - `node scripts/lighthouse-audit.mjs` exit 0 — performance/accessibility/best-practices/seo 100 on every audited route. `npm audit --audit-level=moderate` exits 1 with 6 vulnerabilities (1 moderate, 5 high: browserslist, fast-uri, js-yaml, nanoid, postcss, undici). Measured against main's lockfile under the same command: byte-for-byte the same six. This bump introduces none of them — they are pre-existing transitive debt and want their own change, so they are reported here rather than folded in silently or used as a reason to hold the fix.  **Why no screenshot:** the deleted key rendered nothing on either version — upstream removed it as "never used" — and the visual-regression suite passing against unchanged baselines is the stronger evidence that the page is identical. Closes #61 Signed-off-by: Keyur Golani <keyurrgolani@gmail.com>

HiDeoo added 28 commits November 14, 2025 09:09

feat: basic build step

11c29ad

feat: publishConfig

0d9a647

fix: ./components export

d2932a4

fix: virtual module resolveLocalPath

0d93594

refactor: configuration types

c7f858d

chore: comment rolldown plugins

26c094a

fix: icon names inline union duplicated in declaration files

f598aec

feat(file-icons-generator): file icon names type

0428278

chore: update comment

2a3f437

feat: global type augmentation & interface merging

f54a515

feat: virtual.d.ts

be852cb

chore: add issue links to some comments

51c9ac4

feat: strict publint

bb51ebe

fix: docs

eb2124a

fix: file-icons-generator

04e4ee8

fix: unit tests

5c8678a

fix: coverage

2e7b34b

fix: typecheck

fb0ef81

fix: prettier

5ca7c4b

chore: gitignore build output

77fb4d3

fix: remove some dirty hacks we used when shipping TS

8d3d4cb

docs: update user component links

77c6c42

docs: update props.css link

def3441

docs: update component links

d81bb62

docs: update contributing guide links

18146d3

chore: add tagline changeset

07265af

fix(file-icons-generator): jsdoc links

1fe377d

ci: add build step

e09c58c

HiDeoo added 4 commits August 31, 2026 12:28

feat: disable fixedExtension for docsearch

46c968e

docs: add new commands to CONTRIBUTING.md

f52c51e

fix: missed types during merge

774518e

docs(i18n): update links

8126f45

github-actions Bot added the i18n Anything to do with internationalization & translation efforts label Aug 31, 2026

HiDeoo changed the title ~~Transpile Starlight packages~~ [i18nIgnore] Transpile Starlight packages Aug 31, 2026

delucis previously approved these changes Aug 31, 2026

View reviewed changes

delucis added ✅ approved Pull requests that have been approved and are ready to merge when next cutting a release and removed pr-preview Trigger a preview release for this PR using pkg.pr.new labels Aug 31, 2026

chore: add changeset

890fe19

HiDeoo dismissed delucis’s stale review via 890fe19 September 1, 2026 09:39

delucis mentioned this pull request Sep 1, 2026

Type Checking Fails #2387

Closed

1 task

delucis previously approved these changes Sep 1, 2026

View reviewed changes

Merge branch 'main' into pr/3572

8af6b11

delucis dismissed their stale review via 8af6b11 September 1, 2026 17:08

Fix imports in benchmark

2104d96

Merge branch 'main' into hd/feat-ts-to-js

491b69c

delucis approved these changes Sep 2, 2026

View reviewed changes

delucis merged commit 292fb17 into withastro:main Sep 2, 2026
19 checks passed

astrobot-houston mentioned this pull request Sep 2, 2026

[ci] release #4172

Merged

This was referenced Sep 8, 2026

fix(site): starlight 0.42 removed tagline, so the config that set it stops the build PersonalClaw/personalclaw.dev#62

Merged

build(deps): Bump the npm-minor-and-patch group across 1 directory with 8 updates PersonalClaw/personalclaw.dev#61

Closed

kosmoz mentioned this pull request Sep 10, 2026

chore: update website dependencies distr-sh/distr#3205

Merged

Navigation Menu

Repository navigation

[i18nIgnore] Transpile Starlight packages - #3572

[i18nIgnore] Transpile Starlight packages#3572
delucis merged 69 commits into
withastro:mainfrom
HiDeoo:hd/feat-ts-to-js

HiDeoo commented Nov 26, 2025 •

edited

Loading

Uh oh!

changeset-bot Bot commented Nov 26, 2025 •

edited

Loading

Uh oh!

netlify Bot commented Nov 26, 2025 •

edited

Loading

Uh oh!

delucis left a comment

Uh oh!

HiDeoo commented Sep 1, 2026

Uh oh!

codspeed Bot commented Sep 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

michaelfaith commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

HiDeoo commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Approach

How to test

Remaining tasks

Uh oh!

changeset-bot Bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify Bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

HiDeoo commented Sep 1, 2026

Uh oh!

codspeed Bot commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Uh oh!

michaelfaith commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

HiDeoo commented Nov 26, 2025 •

edited

Loading

changeset-bot Bot commented Nov 26, 2025 •

edited

Loading

netlify Bot commented Nov 26, 2025 •

edited

Loading

codspeed Bot commented Sep 1, 2026 •

edited

Loading