Fix TSC5090 TypeScript compiler error

[mondeja]

Description (required)

It seems that TypeScript added at some point a check to forbid non-explicit relative paths when baseUrl is not set. As astro/tsconfigs/strict does not define baseUrl, this can be reproduced in new astro projects following the Get Started guide and in the Astro docs itself.

To reproduce this problem:

1. Create an example project with npm create astro@latest.
2. cd <project-name>
3. Add the changes proposed by the Import Aliases section of the TypeScript setup guide to tsconfig.json file.
4. Run tsc. The error is displayed:

$ tsc 
tsconfig.json:7:25 - error TS5090: Non-relative paths are not allowed when 'baseUrl' is not set. Did you forget a leading './'?
7       "@components/*": ["src/components/*"],
                          ~~~~~~~~~~~~~~~~~~

tsconfig.json:8:22 - error TS5090: Non-relative paths are not allowed when 'baseUrl' is not set. Did you forget a leading './'?
8       "@layouts/*": ["src/layouts/*"]
                       ~~~~~~~~~~~~~~~

Found 2 errors in the same file, starting at: tsconfig.json:7

Apply the fix proposed by this PR and the error disappears.

Related issues & labels (optional)

What I did find, which documents the historical behavior and discussions around it (and shows where the restriction comes from), are these relevant points:

• The historical decision that paths requires baseUrl is in the original discussion about path mappings in the repository (this entry explains the semantics and explicitly states that paths can only be used if baseUrl is defined):
  Path mappings based module resolution microsoft/TypeScript#5039

• Later proposals and discussions about allowing paths without baseUrl (showing that the requirement has been deliberate and debated since 2019):
  Proposal: Allow paths compilerOption without baseUrl microsoft/TypeScript#31869

• Examples of issues/errors in ecosystems (Nuxt, Svelte, etc.) that report exactly this message in tooling around 2022–2024 (proving that the diagnostic appears in modern versions; e.g. a Nuxt issue showing the message with TypeScript v5.2.2):
  Non-relative paths are not allowed when 'baseUrl' is not set. Typescript v5.2.2 nuxt/nuxt#23157

First-time contributor to Astro Docs?

mondeja.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	8022d11
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68d12d39c5fb4f0008903d0e
😎 Deploy Preview	https://deploy-preview-12358--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/typescript.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[ArmandPhilippot]

Thanks you for taking the time to open a PR to fix an issue in docs! But, I tried to reproduce the issue following your steps and using "@components/*": ["src/components/*"] works fine on my side. Unless you're able to provide a reproduction where this fails, I don't think we need those changes.

baseUrl was dropped in withastro/astro#14064 because this is no longer required with paths aliases. And looking at the tests fixtures implemented in that PR, this seems to match what we described in the docs:
https://github.com/jp-knj/astro/blob/1a448231dc68d48b8b0532fb84f05f9dd13bfe4d/packages/astro/test/fixtures/alias-tsconfig-no-baseurl/tsconfig.json#L1-L7

[mondeja]

Hi @ArmandPhilippot. Thanks for your initial review.

Unless you're able to provide a reproduction where this fails, I don't think we need those changes.

I'm able to reproduce it on GitHub actions.

• Repository: https://github.com/mondeja/astro-docs-12358
• Run: https://github.com/mondeja/astro-docs-12358/actions/runs/17896035697/job/50882792680#step:6:7
• Workflow file: https://github.com/mondeja/astro-docs-12358/blob/e99012bd2c71b4be1a6da90e9336ae4b729f4dab/.github/workflows/ci.yml

Commands:

npm create astro@latest ./my-project -- --template minimal --yes
cd my-project
# tsc (OK)
tsc
# Edit tsconfig.json
jq '.compilerOptions.paths = {"@components/*": ["src/components/*"]}' tsconfig.json > tsconfig.tmp && mv tsconfig.tmp tsconfig.json
# Show new tsconfig.json content
cat tsconfig.json
# tsc (fails)
tsc
# Error: tsconfig.json(13,9): error TS5090: Non-relative paths are not allowed when 'baseUrl' is not set. Did you forget a leading './'?
echo $?
# 2

[ArmandPhilippot]

Oh sorry, maybe I was too quick earlier. I'm so used to run astro check in Astro projects that I misread the step 4. I didn't run tsc... I've only tried running the dev server and astro check. Both didn't complained and the path aliases was working just fine.

So, yes, I can see an error reported using tsc both with the previous steps and the new ones! I wonder why astro check didn't catch that and why this works (both with dev and build) without even a warning...

Looking at Typescript docs, it seems they always use relative paths when declaring paths aliases and I can confirm this works.

So, the changes looks good to me. Thank you both for fixing the docs and your patience! Welcome to team Docs! 🎉