withastro · florian-lefebvre · Sep 3, 2024 · Aug 28, 2024 · Aug 28, 2024 · Aug 28, 2024
diff --git a/.changeset/old-zebras-teach.md b/.changeset/old-zebras-teach.md
@@ -0,0 +1,19 @@
+---
+'astro': major
+---
+
+Updates `astro sync` behavior
+
+Astro examples default `tsconfig.json` has been updated to include generated types and exclude your build output. This means that `src/env.d.ts` is only necessary if you have added custom or if you're not using a `tsconfig.json` file.
+
+Additionally, running `astro sync` no longer creates, nor updates, `src/env.d.ts` as it is not required for type-checking standard Astro projects.
+
+To update your project to Astro's recommended TypeScript settings, please add the following `include` and `exclude` properties to `tsconfig.json`:
+
+```diff
+{
+    "extends": "astro/tsconfigs/base",
++    "include": ["**/*", ".astro/types.d.ts"],
++    "exclude": ["dist"]
+}
+```
diff --git a/examples/basics/tsconfig.json b/examples/basics/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/blog/src/env.d.ts b/examples/blog/src/env.d.ts
diff --git a/examples/blog/tsconfig.json b/examples/blog/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "strictNullChecks": true
   }

diff --git a/examples/component/tsconfig.json b/examples/component/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "jsx": "preserve"
   }

diff --git a/examples/container-with-vitest/tsconfig.json b/examples/container-with-vitest/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/framework-alpine/src/env.d.ts b/examples/framework-alpine/src/env.d.ts
diff --git a/examples/framework-alpine/tsconfig.json b/examples/framework-alpine/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/framework-multiple/src/env.d.ts b/examples/framework-multiple/src/env.d.ts
diff --git a/examples/framework-multiple/tsconfig.json b/examples/framework-multiple/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     // Needed for TypeScript intellisense in the template inside Vue files
     "jsx": "preserve"

diff --git a/examples/framework-preact/src/env.d.ts b/examples/framework-preact/src/env.d.ts
diff --git a/examples/framework-preact/tsconfig.json b/examples/framework-preact/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     // Preact specific settings
     "jsx": "react-jsx",

diff --git a/examples/framework-react/src/env.d.ts b/examples/framework-react/src/env.d.ts
diff --git a/examples/framework-react/tsconfig.json b/examples/framework-react/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "jsx": "react-jsx",
     "jsxImportSource": "react"

diff --git a/examples/framework-solid/src/env.d.ts b/examples/framework-solid/src/env.d.ts
diff --git a/examples/framework-solid/tsconfig.json b/examples/framework-solid/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     // Solid specific settings
     "jsx": "preserve",

diff --git a/examples/framework-svelte/src/env.d.ts b/examples/framework-svelte/src/env.d.ts
diff --git a/examples/framework-svelte/tsconfig.json b/examples/framework-svelte/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/framework-vue/src/env.d.ts b/examples/framework-vue/src/env.d.ts
diff --git a/examples/framework-vue/tsconfig.json b/examples/framework-vue/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     // Needed for TypeScript intellisense in the template inside Vue files
     "jsx": "preserve"

diff --git a/examples/hackernews/src/env.d.ts b/examples/hackernews/src/env.d.ts
diff --git a/examples/hackernews/tsconfig.json b/examples/hackernews/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/middleware/src/env.d.ts b/examples/middleware/src/env.d.ts
@@ -1,4 +1,3 @@
-/// <reference path="../.astro/types.d.ts" />
 declare namespace App {
 	interface Locals {
 		user: {

diff --git a/examples/middleware/tsconfig.json b/examples/middleware/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/minimal/src/env.d.ts b/examples/minimal/src/env.d.ts
diff --git a/examples/minimal/tsconfig.json b/examples/minimal/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/non-html-pages/src/env.d.ts b/examples/non-html-pages/src/env.d.ts
diff --git a/examples/non-html-pages/tsconfig.json b/examples/non-html-pages/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/portfolio/src/env.d.ts b/examples/portfolio/src/env.d.ts
diff --git a/examples/portfolio/tsconfig.json b/examples/portfolio/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/ssr/src/env.d.ts b/examples/ssr/src/env.d.ts
diff --git a/examples/ssr/tsconfig.json b/examples/ssr/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/starlog/tsconfig.json b/examples/starlog/tsconfig.json
@@ -1,4 +1,5 @@
 {
   "extends": "astro/tsconfigs/strict",
+  "include": ["**/*", ".astro/types.d.ts"],
   "exclude": ["dist"]
 }
diff --git a/examples/view-transitions/tsconfig.json b/examples/view-transitions/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "resolveJsonModule": true
   }

diff --git a/examples/with-markdoc/src/env.d.ts b/examples/with-markdoc/src/env.d.ts
diff --git a/examples/with-markdoc/tsconfig.json b/examples/with-markdoc/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     "strictNullChecks": true
   }

diff --git a/examples/with-markdown-plugins/src/env.d.ts b/examples/with-markdown-plugins/src/env.d.ts
diff --git a/examples/with-markdown-plugins/tsconfig.json b/examples/with-markdown-plugins/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/with-markdown-shiki/src/env.d.ts b/examples/with-markdown-shiki/src/env.d.ts
diff --git a/examples/with-markdown-shiki/tsconfig.json b/examples/with-markdown-shiki/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/with-mdx/src/env.d.ts b/examples/with-mdx/src/env.d.ts
diff --git a/examples/with-mdx/tsconfig.json b/examples/with-mdx/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/with-nanostores/src/env.d.ts b/examples/with-nanostores/src/env.d.ts
diff --git a/examples/with-nanostores/tsconfig.json b/examples/with-nanostores/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"],
   "compilerOptions": {
     // Preact specific settings
     "jsx": "react-jsx",

diff --git a/examples/with-tailwindcss/src/env.d.ts b/examples/with-tailwindcss/src/env.d.ts
diff --git a/examples/with-tailwindcss/tsconfig.json b/examples/with-tailwindcss/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/examples/with-vitest/tsconfig.json b/examples/with-vitest/tsconfig.json
@@ -1,3 +1,5 @@
 {
-  "extends": "astro/tsconfigs/base"
+  "extends": "astro/tsconfigs/base",
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/e2e/fixtures/actions-blog/tsconfig.json b/packages/astro/e2e/fixtures/actions-blog/tsconfig.json
@@ -4,5 +4,7 @@
     "strictNullChecks": true,
     "jsx": "react-jsx",
     "jsxImportSource": "react"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/e2e/fixtures/actions-react-19/tsconfig.json b/packages/astro/e2e/fixtures/actions-react-19/tsconfig.json
@@ -4,5 +4,7 @@
     "strictNullChecks": true,
     "jsx": "react-jsx",
     "jsxImportSource": "react"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/e2e/fixtures/client-only/tsconfig.json b/packages/astro/e2e/fixtures/client-only/tsconfig.json
@@ -1,5 +1,7 @@
 {
   "compilerOptions": {
     "importsNotUsedAsValues": "error"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/e2e/fixtures/custom-client-directives/tsconfig.json b/packages/astro/e2e/fixtures/custom-client-directives/tsconfig.json
@@ -4,5 +4,6 @@
     // This is only needed because we link Astro locally.
     "preserveSymlinks": true
   },
-  "include": ["./src/**/*"]
+  "include": ["./src/**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/performance/fixtures/md/src/env.d.ts b/packages/astro/performance/fixtures/md/src/env.d.ts
diff --git a/packages/astro/performance/fixtures/md/tsconfig.json b/packages/astro/performance/fixtures/md/tsconfig.json
@@ -3,5 +3,7 @@
   "compilerOptions": {
     "jsx": "react-jsx",
     "jsxImportSource": "react"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/performance/fixtures/mdoc/tsconfig.json b/packages/astro/performance/fixtures/mdoc/tsconfig.json
@@ -3,5 +3,7 @@
   "compilerOptions": {
     "jsx": "react-jsx",
     "jsxImportSource": "react"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/performance/fixtures/mdx/tsconfig.json b/packages/astro/performance/fixtures/mdx/tsconfig.json
@@ -3,5 +3,7 @@
   "compilerOptions": {
     "jsx": "react-jsx",
     "jsxImportSource": "react"
-  }
+  },
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]
 }
diff --git a/packages/astro/performance/fixtures/utils/tsconfig.json b/packages/astro/performance/fixtures/utils/tsconfig.json
@@ -2,5 +2,7 @@
   "compilerOptions": {               
     "jsx": "react-jsx",              
     "jsxImportSource": "react"       
-  }                                  
+  }       ,
+  "include": ["**/*", ".astro/types.d.ts"],
+  "exclude": ["dist"]                           
 }
diff --git a/packages/astro/src/core/sync/constants.ts b/packages/astro/src/core/sync/constants.ts
diff --git a/packages/astro/src/core/sync/index.ts b/packages/astro/src/core/sync/index.ts
@@ -30,7 +30,8 @@ import {
 import type { Logger } from '../logger/core.js';
 import { formatErrorMessage } from '../messages.js';
 import { ensureProcessNodeEnv } from '../util.js';
-import { writeFiles } from './write-files.js';
+import { dirname, relative } from 'node:path';
+import { normalizePath } from 'vite';
 
 export type SyncOptions = {
 	/**
@@ -135,7 +136,7 @@ export async function syncInternal({
 		}
 		syncAstroEnv(settings);
 
-		await writeFiles(settings, fs, logger);
+		writeInjectedTypes(settings, fs);
 		logger.info('types', `Generated ${dim(getTimeStat(timerStart, performance.now()))}`);
 	} catch (err) {
 		const error = createSafeError(err);
@@ -148,6 +149,33 @@ export async function syncInternal({
 	}
 }
 
+function getTsReference(type: 'path' | 'types', value: string) {
+	return `/// <reference ${type}=${JSON.stringify(value)} />`;
+}
+
+const CLIENT_TYPES_REFERENCE = getTsReference('types', 'astro/client');
+
+function writeInjectedTypes(settings: AstroSettings, fs: typeof fsMod) {
+	const references: Array<string> = [];
+
+	for (const { filename, content } of settings.injectedTypes) {
+		const filepath = fileURLToPath(new URL(filename, settings.dotAstroDir));
+		fs.mkdirSync(dirname(filepath), { recursive: true });
+		fs.writeFileSync(filepath, content, 'utf-8');
+		references.push(normalizePath(relative(fileURLToPath(settings.dotAstroDir), filepath)));
+	}
+
+	const astroDtsContent = `${CLIENT_TYPES_REFERENCE}\n${references.map((reference) => getTsReference('path', reference)).join('\n')}`;
+	if (references.length === 0) {
+		fs.mkdirSync(settings.dotAstroDir, { recursive: true });
+	}
+	fs.writeFileSync(
+		fileURLToPath(new URL('./types.d.ts', settings.dotAstroDir)),
+		astroDtsContent,
+		'utf-8',
+	);
+}
+
 /**
  * Generate content collection types, and then returns the process exit signal.
  *