Update documentation on 'Middleware types'

[dominicbrauer]

Hi,
I was working with middleware and locals for the first time and I tried to follow the documentation for it right here. I understood that it is possible to configure types for the locals variable but I couldn't figure it out with the docs. The TS config page does talk about src/env.d.ts but doesn't precisely explain how the file must be structured for it to work.

My suggestion is to update the documentation to explain /// <reference types="astro/client" /> or declare global {... in more detail, escpecially for beginners like me :).

If it is already explained somewhere else, I would highly appreciate sharing that page's link with me.

Greetings,

Dominic Brauer

[ArmandPhilippot]

Hi!
We have a Middleware types section on the same page where you can see a code snippet showing how to use your env.d.ts file to extend the Local types. Actually, we have recently updated this example to show how to use imported types as well. Would this section have helped you?

We don't explain declare global {} or /// <reference types="astro/client" /> because you shouldn't need either of them:

• declare global {}: if you use import, you should use inline imports so the file remains an ambient declaration file. When you need declare global to make it work, then the file is no longer an ambient module declaration but a module augmentation, so you could do that in a regular .ts file instead of a .d.ts file. See: https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules
• /// <reference types="astro/client" /> should already be present in your project (in .astro/types.d.ts) so you don't need to add it manually in your env.d.ts file. This file is generated by Astro when you run the dev server or astro sync. So if it is not there, you might need to do that first.

And I think each page introducing a feature where .env.d.ts could be helpful shows an example of that file (often with imports but not all the time) on the same page.

But maybe a section in the Typescript guide could make sense since this is a question that comes back regularly (on Discord as well).

[dominicbrauer]

Hey!
Thank you for the fast reply and the explanations.
I was actually using the 'Middleware types' page for reference, but without the adjustments I couldn't get it to work for me. A friend of mine suggested me to use these additional annotations and it helped to solve the issue. I'll ask him about it again :)

[louisescher]

Hi, I'm that friend! I can confirm that I cannot get this to work without the declare global bit in a project of mine as well. The interesting thing is that it does work in a minimal reproduction. Not entirely sure what the issue is here, I'll keep digging.

Edit: It was the imports messing everything up. I think we should mention more clearly in the docs that normal imports can't be used in this file, as I feel like newcomers will just try to import types using the top-level import syntax. A quick note like
"If you want to use a type from another file, make sure to use inline imports. Otherwise, your types won't be applied."

[ArmandPhilippot]

Thanks for confirming! 😄 I updated this example, so I was surprised that it didn't work. Yeah, top-level imports/exports are probably always the culprit when it doesn't work.

But this is a Typescript thing, not Astro, so we generally don't document this kind of behavior. Unfortunately, even the Typescript documentation is not very clear on this (ambient/augmentation) and this question comes back often. So, I agree, there is probably something we can do here to make it more clear!

Because we use .env.d.ts in many pages, my suggestion would be an explanation on the Typescript guide that we could link from other pages to avoid repeating the same things everywhere.

[sarah11918]

So, if we have all the right pieces in place, would it be helpful if we updated this code block here on the TypeScript page:

To add another code comment line, depending on what's actually correct, like:

// only inline file imports allowed

[louisescher]

The biggest issue is really the bit about inline imports. I've been writing TS for quite a while now and didn't know about that, so I feel like it might catch a lot of people off-guard! The other things (like the triple slash reference), even though unnecessary, don't really make a difference anyway. So while they should be removed from examples, it's not a big issue as it doesn't break anything.
Perhaps this is something we can discuss in Talking & Doc'ing to a greater extent?

[sarah11918]

Alright, we'll put it on the stack for Thursday!

[ArmandPhilippot]

For context, if someone has opinion on this (following T&D), we had this issue #10945 referring to both Middleware and Environment variables pages (and there is additional PR/issues linked in that issue). And I know we also have some examples in third party guides.
So, it would probably be helpful to have this information in the Typescript guide to be able to link to that page directly instead of repeating the same explanation everywhere.

[Fryuni]

What if we didn't recommend using a separate ambient module at all and instead recommended declaring the middleware types in the middleware file itself, which would avoid the entire confusion?

People can use declare global {} wrapping the namespace on the file itself, no need to introduce an extra concept that is quite confusing even for TS ninjas.

[ArmandPhilippot]

This is not a bad idea, but the problem with this solution is that not everyone encounters this behavior when using Middleware specifically. Some people notice this when using environment variables (#11243 for example), and some others could already have a env.d.ts file because they follow some other guides (e.g. Supabase & Astro) and decide to reuse that file. We use env.d.ts in different pages of the docs.

So, I think it could help reduce the number of confused people, but I don't think this would solve the issue entirely.

[louisescher]

So after talking about this on Talking and Doc'ing, a few solutions were proposed, one of which was this comment by Fryuni. The other solution was to have two to three sentences about this weirdness in regards to ambient types, mentioning how top-level import / export statements break them and linking to the Ambient Modules section in TypeScript's reference documentation. We could then reference this part of Astro docs whenever the issue gets brought up in Support.

[ArmandPhilippot]

I'm still not sure what is the best solution here. I just wanted to share that we had another PR trying to add declare global to the Middleware snippet: #12045 and a feedback #12045 (comment) (and it seems people are struggling with this for a while, and not only in the docs repo, looking at the linked issue withastro/astro#7394)

Perhaps we should try Louis solution first (since the d.ts file is used in multiple places) and, if this problem keeps coming back, use Fryuni's suggestion for the Middleware example since that's the one causing the most problems for people? Or we could do both at the same time...

[louisescher]

Perhaps this is something to discuss on Talking & Doc'ing again?