Troubleshooting Page - ideas to add

[sarah11918]

This thread is to collect a list of everyone's favourite:

• error messages, and what they mean/what you can do
• common "gotchas": things you're always forgetting to do or things new people might be confused by
• tips and tricks for troubleshooting/debugging your Astro project

No need to be formal about this! Random thoughts, bullet points... it's all good! We can turn it into docs. 😄

EDITED TO ADD: We will also be taking into consideration what is/isn't a bug or unexpected behaviour etc. And, we'll be carefully choosing what we feel are the most helpful, most common things. (And then deciding what to do with the knowledge base of all the rest.)

So, WE have a plan for how to evaluate the feedback you give us here. No need for you to necessarily worry about whether what you share "counts" as what we're looking for. Team Docs is ON IT!

[Pukimaa]

What about pinning this discussion?

[sarah11918]

Great idea. Done!

[lloydjatkinson]

• Any seemingly lacking in detail errors that mention anything with file path, localhost in my experience had usually meant one of these three things:
  • Invalid Typescript syntax that wasn’t highlighted by Astro VSCode extension making it less obvious - for example one case I saw was with destructuring const { a, b c} = thing
  • Rendering an imported component that has a problem - it’s not always clear the imported component is the problem instead of the current component you’re looking at
  • A dynamic import to a component that isn’t valid
• Any errors like expected a default export means you imported a component with a problem such as invalid syntax
• When using intersection types in TS it’s common to make each & on a new line which is valid TS however this results in unexpected & - probably not something you’d see often unless doing more advanced type stuff eg this line - bit of an esoteric bug but worth mentioning in case anyone hits it, it needs an issue raising.

[Princesseuh]

• Invalid Typescript syntax that wasn’t highlighted by Astro VSCode extension making it less obvious - for example one case I saw was with destructuring const { a, b c} = thing

I have a PR up for this on the language-tools. This should fix all the TS invalid syntax stuff not being highlighted properly. Assuming nothing goes wrong, it should be included in May 25's release

The expected a default export issue will require more work however, so feel free to document that one for sure 😅

[Princesseuh]

Update is now up which should fix most invalid TS syntax errors being silenced ✨

[ekafyi]

These trigger typecheck error but not actual (run/build time) error:

• Having a string containing the triple dash const foo = "here are some dashes ---"
• Importing from package whose exports entry point does not match its file name gives you a "module not found" false alarm
  • Example: https://github.com/aFuzzyBear/xelement/blob/main/packages/XElement/package.json#L24 (if you import from astro-xelement, TS shows a "module not found" error)

Knowledge prerequisites for using Astro beyond the starters, which could potentially trip up users:

• User must have enough knowledge about ES Modules, especially in terms of importing dependencies eg. packages in CommonJS. Probably need Vite knowledge too?
  • Collect common CJS vs ESM-related errors when importing external dependencies (dev or build)
    • What does it mean if I get this error message? Does it mean I cannot use this package at all? Are there workarounds (eg. how to check if I could import a different format)?
• User must have enough knowledge about IDE tools (eg. to investigate the prettier plugin issue)

[sarah11918]

Thanks for the contributions so far! This page is on our radar for this week, so this is really helpful!

[sarah11918]

@Chrissdroid Let me know when you've looked through the items here and decided what to add to your draft of this page for v1, and then I'm going to edit it this week so we can start to get a finalized page together! 🥳

(But, this thread is NOT going away, and welcomes more feedback! I just want to know when @Chrissdroid feels he's filled out a first version he's happy with!)

[Chrissdroid]

For now i added only the expected a default export section, i wish adding more to the set but the majority are more like "Astro VSC plugin gotchas" than "Astro's gotchas" so i don't think i can fit them too much in this page like i want

@ekafyi made a lot of great suggestion (notably on them Knowledge prerequisites) but i don't know how to introduce this in troubleshooting. I'm open to suggestion on this, for sure !

[sarah11918]

Hey everyone following this! Thanks to @Chrissdroid , we now have a draft of this page up!

It obviously doesn't include everything, but it's meant to expand on what's currently in "Debugging" and give a little more extra help with some common issues.

If there's something you feel strongly about that didn't get added there, then now would be a great time to add some suggestions there that we can simply "commit suggestion" on!

Or, if what's there seems good, but you'd like a little more time to think about adding something new, then consider making a PR to that page after we get it published! The good news is, the page never has to be "done" only good enough to go up live. :)