chore: unflag contentCollectionJsonSchema (#11379)

* chore: unflag contentCollectionJsonSchema * chore: improve json schema generation * remove config option * Update tasty-spoons-double.md * Update tasty-spoons-double.md * Update .changeset/tasty-spoons-double.md Co-authored-by: Sarah Rainsberger <[email protected]> * Update .changeset/tasty-spoons-double.md Co-authored-by: Sarah Rainsberger <[email protected]> * Update .changeset/tasty-spoons-double.md * revert whitespace changes * revert whitespace changes * revert whitespace changes * revert whitespace changes --------- Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Erika <[email protected]>
withastro · Jul 31, 2024 · e5e2d3e · e5e2d3e
1 parent 60b2766
commit e5e2d3e
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 62 deletions.
diff --git a/.changeset/tasty-spoons-double.md b/.changeset/tasty-spoons-double.md
@@ -0,0 +1,48 @@
+---
+'astro': minor
+---
+
+The `experimental.contentCollectionJsonSchema` feature introduced behind a flag in [v4.5.0](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md#450) is no longer experimental and is available for general use.
+
+If you are working with collections of type `data`, Astro will now auto-generate JSON schema files for your editor to get IntelliSense and type-checking. A separate file will be created for each data collection in your project based on your collections defined in `src/content/config.ts` using a library called [`zod-to-json-schema`](https://github.com/StefanTerdell/zod-to-json-schema).
+
+This feature requires you to manually set your schema's file path as the value for `$schema` in each data entry file of the collection:
+
+```json title="src/content/authors/armand.json" ins={2}
+{
+  "$schema": "../../../.astro/collections/authors.schema.json",
+  "name": "Armand",
+  "skills": ["Astro", "Starlight"]
+}
+```
+
+Alternatively, you can set this value in your editor settings. For example, to set this value in [VSCode's `json.schemas` setting](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings), provide the path of files to match and the location of your JSON schema:
+
+```json
+{
+  "json.schemas": [
+  {
+    "fileMatch": [
+      "/src/content/authors/**"
+    ],
+    "url": "./.astro/collections/authors.schema.json"
+  }
+  ]
+}
+```
+
+If you were previously using this feature, please remove the experimental flag from your Astro config:
+
+```diff
+import { defineConfig } from 'astro'
+
+export default defineConfig({
+-  experimental: {
+-    contentCollectionJsonSchema: true
+-  }
+})
+```
+
+If you have been waiting for stabilization before using JSON Schema generation for content collections, you can now do so.
+
+Please see [the content collections guide](https://docs.astro.build/en/guides/content-collections/#enabling-json-schema-generation) for more about this feature.
diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts
@@ -1896,54 +1896,6 @@ export interface AstroUserConfig {
 		 */
 		contentCollectionCache?: boolean;
 
-		/**
-		 * @docs
-		 * @name experimental.contentCollectionJsonSchema
-		 * @type {boolean}
-		 * @default `false`
-		 * @version 4.5.0
-		 * @description
-		 * This feature will auto-generate a JSON schema for content collections of `type: 'data'` which can be used as the `$schema` value for TypeScript-style autocompletion/hints in tools like VSCode.
-		 *
-		 * To enable this feature, add the experimental flag:
-		 *
-		 * ```diff
-		 * import { defineConfig } from 'astro/config';
-
-		 * export default defineConfig({
-		 * 	experimental: {
-		 * +		contentCollectionJsonSchema: true
-		 * 	}
-		 * });
-		 * ```
-		 *
-		 * This experimental implementation requires you to manually reference the schema in each data entry file of the collection:
-		 *
-		 * ```diff
-		 * // src/content/test/entry.json
-		 * {
-		 * +  "$schema": "../../../.astro/collections/test.schema.json",
-		 * 	"test": "test"
-		 * }
-		 * ```
-		 *
-		 * Alternatively, you can set this in your [VSCode `json.schemas` settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings):
-		 *
-		 * ```diff
-		 * "json.schemas": [
-		 * 	{
-		 * 		"fileMatch": [
-		 * 			"/src/content/test/**"
-		 * 		],
-		 * 		"url": "./.astro/collections/test.schema.json"
-		 * 	}
-		 * ]
-		 * ```
-		 *
-		 * Note that this initial implementation uses a library with [known issues for advanced Zod schemas](https://github.com/StefanTerdell/zod-to-json-schema#known-issues), so you may wish to consult these limitations before enabling the experimental flag.
-		 */
-		contentCollectionJsonSchema?: boolean;
-
 		/**
 		 * @docs
 		 * @name experimental.clientPrerender

diff --git a/packages/astro/src/content/types-generator.ts b/packages/astro/src/content/types-generator.ts
@@ -382,7 +382,6 @@ async function writeContentFiles({
 
 	const collectionSchemasDir = new URL('./collections/', settings.dotAstroDir);
 	if (
-		settings.config.experimental.contentCollectionJsonSchema &&
 		!fs.existsSync(collectionSchemasDir)
 	) {
 		fs.mkdirSync(collectionSchemasDir, { recursive: true });
@@ -425,8 +424,8 @@ async function writeContentFiles({
 		const resolvedType: 'content' | 'data' =
 			collection.type === 'unknown'
 				? // Add empty / unknown collections to the data type map by default
-					// This ensures `getCollection('empty-collection')` doesn't raise a type error
-					collectionConfig?.type ?? 'data'
+				// This ensures `getCollection('empty-collection')` doesn't raise a type error
+				collectionConfig?.type ?? 'data'
 				: collection.type;
 
 		const collectionEntryKeys = Object.keys(collection.entries).sort();
@@ -460,7 +459,7 @@ async function writeContentFiles({
 					dataTypesStr += `};\n`;
 				}
 
-				if (settings.config.experimental.contentCollectionJsonSchema && collectionConfig?.schema) {
+				if (collectionConfig?.schema) {
 					let zodSchemaForJson =
 						typeof collectionConfig.schema === 'function'
 							? collectionConfig.schema({ image: () => z.string() })
@@ -478,12 +477,15 @@ async function writeContentFiles({
 									name: collectionKey.replace(/"/g, ''),
 									markdownDescription: true,
 									errorMessages: true,
+									// Fix for https://github.com/StefanTerdell/zod-to-json-schema/issues/110
+									dateStrategy: ["format:date-time", "format:date", "integer"]
 								}),
 								null,
 								2
 							)
 						);
 					} catch (err) {
+						// This should error gracefully and not crash the dev server
 						logger.warn(
 							'content',
 							`An error was encountered while creating the JSON schema for the ${collectionKey} collection. Proceeding without it. Error: ${err}`

diff --git a/packages/astro/src/core/config/schema.ts b/packages/astro/src/core/config/schema.ts
@@ -85,7 +85,6 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		actions: false,
 		directRenderScript: false,
 		contentCollectionCache: false,
-		contentCollectionJsonSchema: false,
 		clientPrerender: false,
 		globalRoutePriority: false,
 		rewriting: false,
@@ -517,10 +516,6 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionCache),
-			contentCollectionJsonSchema: z
-				.boolean()
-				.optional()
-				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionJsonSchema),
 			clientPrerender: z
 				.boolean()
 				.optional()

diff --git a/packages/astro/test/fixtures/data-collections-schema/astro.config.mjs b/packages/astro/test/fixtures/data-collections-schema/astro.config.mjs
@@ -1,8 +1,4 @@
 import { defineConfig } from 'astro/config';
 
 // https://astro.build/config
-export default defineConfig({
-	experimental: {
-		contentCollectionJsonSchema: true
-	}
-});
+export default defineConfig({});