Document using / extending the Astro JSX definitions

[Princesseuh]

This is very advanced usage, nonetheless we see some people do it. Notably, our official image integration use them to provide img props completions and type checking in the components

Using them is done through a triple slash directive, this works both in Astro files and in TypeScript files

---
/// <reference types="astro/astro-jsx" />

// Access them directly:
export type Props = astroHTML.JSX.ImgHTMLAttributes;
---

<img ...>

Extending them is done through a .d.ts file redeclaring the namespace:

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    mycustomattribute?: any;
  }
}

People tend to extend them whenever they want non-standard attributes while still having typechecking. Another case is when we made a mistake and some attributes isn't included in our definitions 😅

[delucis]

Maybe we can add this to our Typescript page? Are there other use cases for triple-slash directives augmenting ambient types we would want to mention and does it matter where .d.ts are?

[Princesseuh]

Maybe we can add this to our Typescript page? Are there other use cases for triple-slash directives augmenting ambient types we would want to mention and does it matter where .d.ts are?

I do not think there's other use cases specific to Astro and it shouldn't matter where the .d.ts is in this case, though I have heard of issues when using a folder called "types" in the past