Set a clear .astro directory structure

[florian-lefebvre]

Body

Summary

Create a clear structure in .astro, for core and integrations

Background & Motivation

Back in February, I started working on withastro/astro#9952, innocently thinking that it would be easy. The goal was initially to do some tsconfig magic, then I scoped it down to allow integrations to inject types, then it was still too much so I closed it.

I uncovered that it requires a few things, including a rework of the .astro dir structure. According to @Princesseuh, it was initially planned for 4.0 but got postponed because of the Dev Toolbar.

Anyway, why do we need a clear structure? With more and more core and integrations features relying on codegen, the risk of collisions is increasing. The DX is not so great, and types require adding references in src/env.d.ts.

The goal is to unify all of this in a coherent structure.

Goals

• Create a convention for the .astro structure
• Refactor how core refers to / interacts with the .astro directory

Non goals

• Allow integrations to hook into this new structure

Example

.astro/
	types.d.ts // only references to other .d.ts. We keep this name for backward compatibility,
				  can be changed to something like astro.d.ts in Astro 5
	astro/
		content.d.ts // formerly types.d.ts
	integrations/
		<integration_name>/
			<dts_name>.d.ts

[Princesseuh]

Love this 😄

How would you imagine this types.d.ts be included into the TypeScript project? Using env.d.ts like right now? I know Nuxt uses two tsconfig.json and that you tried that and there was a bunch of issues, but maybe we can figure it out.

For reference, a way to include types.d.ts is required because TypeScript does not include hidden folders unless there's a direct reference.

[florian-lefebvre]

Yeah for now we would use the current types.d.ts to avoid breaking changes but the next step is actually getting a generated tsconfig to work. Then we can do a codemod to remove the explicit reference. But that's quite far ahead already

[matthewp]

Will this make it easier to do type generation?

[florian-lefebvre]

Exactly! Eventually, we'll track types filenames and generate relative references. In the end, the user will only need a reference to .astro/types.d.ts from src/env.d.ts

[Princesseuh]

And if we end up doing the tsconfig inside .astro thing, then the user won't need to do anything 🤩

[matthewp]

Is providing APIs for doing typegen in scope of this proposal?

[Princesseuh]

Is providing APIs for doing typegen in scope of this proposal?

No, this would go in a further RFC specific to codegen. This proposal aims to only inform about the shape of the codegen folder.

Unless you mean for core, in which case yes. The main post goals and non goals talk about this.

[florian-lefebvre]

Yeah typegen apis for integrations will be in a following rfc. That's because I tried to tackled this at once already, thinking it would be straight forward, and it was an absolute mess involving many parts in astro

[florian-lefebvre]

Changes have been made