feat: injectTypes

.changeset/fresh-fans-study.md

@@ -0,0 +1,18 @@
+---
+'@astrojs/db': minor
+---
+
+Changes how type generation works
+
+The generated `.d.ts` file is now at a new location:
+
+```diff
+- .astro/db-types.d.ts
++ .astro/integrations/astro_db/db.d.ts
+```
+
+The following line can now be removed from `src/env.d.ts`:
+
+```diff
+- /// <reference path="../.astro/db-types.d.ts" />
+```

.changeset/mean-horses-kiss.md

@@ -0,0 +1,31 @@
+---
+'astro': minor
+---
+
+Adds a new `injectTypes()` utility to the Integration API and refactors how type generation works
+
+Integrations can now use a new `injectTypes()` utility in the `astro:config:done` hook. This utility allows an integration to inject types into a user's project. `filename` must end 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
+// my-integration/index.js
+export default {
+  name: 'my-integration',
+  'astro:config:done': ({ injectTypes }) => {
+    injectTypes({
+      filename: "types.d.ts",
+      content: "declare module 'virtual:my-integration' {}"
+    })
+  }
+};
+```
+
+Codegen has been refactored. Although `src/env.d.ts` will continue to work as is, we recommend you update it:
+
+```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

@@ -2610,6 +2610,11 @@ export interface AstroAdapterFeatures {
 	functionPerRoute: boolean;
 }
 
+export interface InjectedType {
+	filename: string;
+	content: string;
+}
+
 export interface AstroSettings {
 	config: AstroConfig;
 	adapter: AstroAdapter | undefined;
@@ -2645,6 +2650,7 @@ export interface AstroSettings {
 	latestAstroVersion: string | undefined;
 	serverIslandMap: NonNullable<SSRManifest['serverIslandMap']>;
 	serverIslandNameMap: NonNullable<SSRManifest['serverIslandNameMap']>;
+	injectedTypes: Array<InjectedType>;
 }
 
 export type AsyncRendererComponentFn<U> = (
@@ -3346,6 +3352,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

@@ -24,10 +24,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

@@ -34,7 +34,7 @@ export const CONTENT_FLAGS = [
 	CONTENT_MODULE_FLAG,
 ] as const;
 
-export const CONTENT_TYPES_FILE = 'types.d.ts';
+export const CONTENT_TYPES_FILE = 'astro/content.d.ts';
 
 export const DATA_STORE_FILE = 'data-store.json';
 export const ASSET_IMPORTS_FILE = 'assets.mjs';

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

@@ -530,7 +530,7 @@ async function writeContentFiles({
 	}
 
 	const configPathRelativeToCacheDir = normalizeConfigPath(
-		settings.dotAstroDir.pathname,
+		new URL('astro', settings.dotAstroDir).pathname,
 		contentPaths.config.url.pathname,
 	);
 
@@ -546,8 +546,17 @@ async function writeContentFiles({
 		contentConfig ? `typeof import(${configPathRelativeToCacheDir})` : 'never',
 	);
 
-	await fs.promises.writeFile(
-		new URL(CONTENT_TYPES_FILE, settings.dotAstroDir),
-		typeTemplateContent,
-	);
+	// If it's the first time, we inject types the usual way. sync() will handle creating files and references. If it's not the first time, we just override the dts content
+	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

@@ -31,7 +31,6 @@ async function createRestartedContainer(
 }
 
 const configRE = /.*astro.config.(?:mjs|cjs|js|ts)$/;
-const preferencesRE = /.*\.astro\/settings.json$/;
 
 function shouldRestartContainer(
 	{ settings, inlineConfig, restartInFlight }: Container,
@@ -40,17 +39,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/errors/errors-data.ts

@@ -1291,6 +1291,17 @@ export const RewriteWithBodyUsed = {
 		'Astro.rewrite() cannot be used if the request body has already been read. If you need to read the body, first clone the request.',
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @description
+ * An unknown error occured while reading or writing files to disk. It can be caused by many things, eg. missing permissions or a file not existing we attempt to read.
+ */
+export const UnknownFilesystemError = {
+	name: 'UnknownFilesystemError',
+	title: 'An unknown error occured while reading or writing files to disk.',
+	hint: 'It can be caused by many things, eg. missing permissions or a file not existing we attempt to read. Check the error cause for more details.',
+} satisfies ErrorData;
+
 /**
  * @docs
  * @kind heading

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';