feat: injectTypes

.changeset/fresh-fans-study.md

@@ -0,0 +1,18 @@
+---
+'@astrojs/db': minor
+---
+
+Changes how typegen works
+
+The generated dts file is now at a new location:
+
+```diff
+- .astro/db-types.d.ts
++ .astro/astro/db.d.ts
+```
+
+The update made to `src/env.d.ts` can be undone:
+
+```diff
+- /// <reference path="../.astro/db-types.d.ts" />
+```

.changeset/mean-horses-kiss.md

@@ -0,0 +1,26 @@
+---
+'astro': minor
+---
+
+Adds a new `injectTypes` utility to the Integration API and refactors how typegen works
+
+Integrations can now use a new `injectTypes` utility exposed on the `astro:config:done` hook. It allows to inject types easily in the user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript (it will be formatted).
+
+Under the hood, it will create a file at `/.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path.
+
+```js
+const path = injectTypes({
+  filename: "types.d.ts",
+  content: "declare module 'virtual:integration' {}"
+})
+console.log(path) // URL
+```
+
+Codegen has been refactored. As a user, you just need to update `src/env.d.ts`:
+
+```diff
+- /// <reference types="astro/client" />
++ /// <reference path="../.astro/types.d.ts" />
+- /// <reference path="../.astro/env.d.ts" />
+- /// <reference path="../.astro/actions.d.ts" />
+```

examples/basics/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/blog/src/env.d.ts

@@ -1,2 +1 @@
 /// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />

examples/framework-alpine/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-lit/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-multiple/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-preact/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-react/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-solid/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-svelte/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/framework-vue/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/hackernews/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/middleware/src/env.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />
 declare namespace App {
 	interface Locals {
 		user: {

examples/minimal/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/non-html-pages/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/portfolio/src/env.d.ts

@@ -1,2 +1 @@
 /// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />

examples/ssr/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/with-markdoc/src/env.d.ts

@@ -1,2 +1 @@
 /// <reference path="../.astro/types.d.ts" />
-/// <reference types="astro/client" />

examples/with-markdown-plugins/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/with-markdown-shiki/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/with-mdx/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/with-nanostores/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

examples/with-tailwindcss/src/env.d.ts

@@ -1 +1 @@
-/// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />

packages/astro/src/@types/astro.ts

@@ -2345,6 +2345,11 @@ export interface AstroAdapterFeatures {
 	functionPerRoute: boolean;
 }
 
+export interface InjectedType {
+	filename: string;
+	content: string;
+}
+
 export interface AstroSettings {
 	config: AstroConfig;
 	adapter: AstroAdapter | undefined;
@@ -2380,6 +2385,7 @@ export interface AstroSettings {
 	latestAstroVersion: string | undefined;
 	serverIslandMap: NonNullable<SSRManifest['serverIslandMap']>;
 	serverIslandNameMap: NonNullable<SSRManifest['serverIslandNameMap']>;
+	injectedTypes: Array<InjectedType>;
 }
 
 export type AsyncRendererComponentFn<U> = (
@@ -3081,6 +3087,7 @@ declare global {
 			'astro:config:done': (options: {
 				config: AstroConfig;
 				setAdapter: (adapter: AstroAdapter) => void;
+				injectTypes: (injectedType: InjectedType) => URL;
 				logger: AstroIntegrationLogger;
 			}) => void | Promise<void>;
 			'astro:server:setup': (options: {

packages/astro/src/actions/consts.ts

@@ -1,6 +1,6 @@
 export const VIRTUAL_MODULE_ID = 'astro:actions';
 export const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
-export const ACTIONS_TYPES_FILE = 'actions.d.ts';
+export const ACTIONS_TYPES_FILE = 'astro/actions.d.ts';
 export const VIRTUAL_INTERNAL_MODULE_ID = 'astro:internal-actions';
 export const RESOLVED_VIRTUAL_INTERNAL_MODULE_ID = '\0astro:internal-actions';
 export const NOOP_ACTIONS = '\0noop-actions';

packages/astro/src/actions/index.ts

@@ -30,9 +30,6 @@ export default function astroActions({
 					throw error;
 				}
 
-				const stringifiedActionsImport = JSON.stringify(
-					viteID(new URL('./actions', params.config.srcDir))
-				);
 				params.updateConfig({
 					vite: {
 						plugins: [vitePluginUserActions({ settings }), vitePluginActions(fs)],
@@ -49,11 +46,18 @@ export default function astroActions({
 					entrypoint: 'astro/actions/runtime/middleware.js',
 					order: 'post',
 				});
+			},
+			'astro:config:done': (params) => {
+				const stringifiedActionsImport = JSON.stringify(
+					viteID(new URL('./actions', params.config.srcDir))
+				);
+				settings.injectedTypes.push({
+					filename: ACTIONS_TYPES_FILE,
+					content: `declare module "astro:actions" {
+	type Actions = typeof import(${stringifiedActionsImport})["server"];
 
-				await typegen({
-					stringifiedActionsImport,
-					root: params.config.root,
-					fs,
+	export const actions: Actions;
+}`,
 				});
 			},
 		},
@@ -119,24 +123,3 @@ const vitePluginActions = (fs: typeof fsMod): VitePlugin => ({
 		return code;
 	},
 });
-
-async function typegen({
-	stringifiedActionsImport,
-	root,
-	fs,
-}: {
-	stringifiedActionsImport: string;
-	root: URL;
-	fs: typeof fsMod;
-}) {
-	const content = `declare module "astro:actions" {
-	type Actions = typeof import(${stringifiedActionsImport})["server"];
-
-	export const actions: Actions;
-}`;
-
-	const dotAstroDir = new URL('.astro/', root);
-
-	await fs.promises.mkdir(dotAstroDir, { recursive: true });
-	await fs.promises.writeFile(new URL(ACTIONS_TYPES_FILE, dotAstroDir), content);
-}

packages/astro/src/cli/check/index.ts

@@ -30,7 +30,7 @@ export async function check(flags: Arguments) {
 		// For now, we run this once as usually `astro check --watch` is ran alongside `astro dev` which also calls `astro sync`.
 		const { default: sync } = await import('../../core/sync/index.js');
 		try {
-			await sync({ inlineConfig: flagsToAstroInlineConfig(flags) });
+			await sync(flagsToAstroInlineConfig(flags));
 		} catch (_) {
 			return process.exit(1);
 		}

packages/astro/src/cli/sync/index.ts

@@ -21,7 +21,7 @@ export async function sync({ flags }: SyncOptions) {
 	}
 
 	try {
-		await _sync({ inlineConfig: flagsToAstroInlineConfig(flags), telemetry: true });
+		await _sync(flagsToAstroInlineConfig(flags), { telemetry: true });
 		return 0;
 	} catch (_) {
 		return 1;

packages/astro/src/content/consts.ts

@@ -16,4 +16,4 @@ export const CONTENT_FLAGS = [
 	PROPAGATED_ASSET_FLAG,
 ] as const;
 
-export const CONTENT_TYPES_FILE = 'types.d.ts';
+export const CONTENT_TYPES_FILE = 'astro/content.d.ts';

packages/astro/src/content/types-generator.ts

@@ -499,7 +499,7 @@ async function writeContentFiles({
 	}
 
 	const configPathRelativeToCacheDir = normalizeConfigPath(
-		settings.dotAstroDir.pathname,
+		new URL('astro', settings.dotAstroDir).pathname,
 		contentPaths.config.url.pathname
 	);
 
@@ -515,8 +515,16 @@ async function writeContentFiles({
 		contentConfig ? `typeof import(${configPathRelativeToCacheDir})` : 'never'
 	);
 
-	await fs.promises.writeFile(
-		new URL(CONTENT_TYPES_FILE, settings.dotAstroDir),
-		typeTemplateContent
-	);
+	if (settings.injectedTypes.some((t) => t.filename === CONTENT_TYPES_FILE)) {
+		fs.promises.writeFile(
+			new URL(CONTENT_TYPES_FILE, settings.dotAstroDir),
+			typeTemplateContent,
+			'utf-8'
+		);
+	} else {
+		settings.injectedTypes.push({
+			filename: CONTENT_TYPES_FILE,
+			content: typeTemplateContent,
+		});
+	}
 }

packages/astro/src/core/config/settings.ts

@@ -14,7 +14,8 @@ import { loadTSConfig } from './tsconfig.js';
 
 export function createBaseSettings(config: AstroConfig): AstroSettings {
 	const { contentDir } = getContentPaths(config);
-	const preferences = createPreferences(config);
+	const dotAstroDir = new URL('.astro/', config.root);
+	const preferences = createPreferences(config, dotAstroDir);
 	return {
 		config,
 		preferences,
@@ -106,8 +107,9 @@ export function createBaseSettings(config: AstroConfig): AstroSettings {
 		watchFiles: [],
 		devToolbarApps: [],
 		timer: new AstroTimer(),
-		dotAstroDir: new URL('.astro/', config.root),
+		dotAstroDir,
 		latestAstroVersion: undefined, // Will be set later if applicable when the dev server starts
+		injectedTypes: [],
 	};
 }
 

packages/astro/src/core/dev/restart.ts

@@ -30,7 +30,6 @@ async function createRestartedContainer(
 }
 
 const configRE = /.*astro.config.(?:mjs|cjs|js|ts)$/;
-const preferencesRE = /.*\.astro\/settings.json$/;
 
 function shouldRestartContainer(
 	{ settings, inlineConfig, restartInFlight }: Container,
@@ -39,17 +38,19 @@ function shouldRestartContainer(
 	if (restartInFlight) return false;
 
 	let shouldRestart = false;
+	const normalizedChangedFile = vite.normalizePath(changedFile);
 
 	// If the config file changed, reload the config and restart the server.
 	if (inlineConfig.configFile) {
-		shouldRestart = vite.normalizePath(inlineConfig.configFile) === vite.normalizePath(changedFile);
+		shouldRestart = vite.normalizePath(inlineConfig.configFile) === normalizedChangedFile;
 	}
 	// Otherwise, watch for any astro.config.* file changes in project root
 	else {
-		const normalizedChangedFile = vite.normalizePath(changedFile);
 		shouldRestart = configRE.test(normalizedChangedFile);
-
-		if (preferencesRE.test(normalizedChangedFile)) {
+		const settingsPath = vite.normalizePath(
+			fileURLToPath(new URL('settings.json', settings.dotAstroDir))
+		);
+		if (settingsPath.match(normalizedChangedFile)) {
 			shouldRestart = settings.preferences.ignoreNextPreferenceReload ? false : true;
 
 			settings.preferences.ignoreNextPreferenceReload = false;

packages/astro/src/core/index.ts

@@ -23,4 +23,4 @@ export const build = (inlineConfig: AstroInlineConfig) => _build(inlineConfig);
  * @experimental The JavaScript API is experimental
  */
 // Wrap `_sync` to prevent exposing internal options
-export const sync = (inlineConfig: AstroInlineConfig) => _sync({ inlineConfig });
+export const sync = (inlineConfig: AstroInlineConfig) => _sync(inlineConfig);

packages/astro/src/core/sync/constants.ts

@@ -0,0 +1,2 @@
+// TODO: use types.d.ts for backward compatibility. Use astro.d.ts in Astro 5.0
+export const REFERENCE_FILE = './types.d.ts';