Generate a JSON schema for Wrangler (#5550)

* Generate JSON schema * fix: wrangler build with json config * Support $schema property * Fix $schema type * Create great-scissors-pretend.md * fixup after review * prettier-ignore
cloudflare · Apr 9, 2024 · 4f47f74 · 4f47f74
1 parent 777b4c7
commit 4f47f74
Show file tree

Hide file tree

Showing 29 changed files with 106 additions and 42 deletions.
diff --git a/.changeset/great-scissors-pretend.md b/.changeset/great-scissors-pretend.md
@@ -0,0 +1,6 @@
+---
+"create-cloudflare": minor
+"wrangler": minor
+---
+
+feat: Generate a JSON schema for the Wrangler package & use it in templates
diff --git a/.gitignore b/.gitignore
@@ -189,6 +189,9 @@ _routes.generated.json
 packages/quick-edit/vscode
 packages/quick-edit/web
 
+packages/wrangler/config-schema.json
+
+
 # Vendored npm dependencies
 !vendor/*.tgz
 

diff --git a/.prettierignore b/.prettierignore
@@ -1,4 +1,5 @@
 
+packages/wrangler/config-schema.json
 packages/wrangler/wrangler-dist/
 packages/wrangler/miniflare-dist/
 packages/wrangler/emitted-types/

diff --git a/fixtures/pages-workerjs-with-config-file-app/wrangler.toml b/fixtures/pages-workerjs-with-config-file-app/wrangler.toml
@@ -2,7 +2,7 @@ pages_build_output_dir = "./public"
 
 name = "pages-with-config-file-app"
 compatibility_date = "2024-01-01"
-#compatibility_flags = []
+compatibility_flags = []
 
 [vars]
 VAR1 = "celebrate"

diff --git a/packages/create-cloudflare/templates/astro/templates/wrangler.toml b/packages/create-cloudflare/templates/astro/templates/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/create-cloudflare/templates/common/js/wrangler.toml b/packages/create-cloudflare/templates/common/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.js"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/common/ts/wrangler.toml b/packages/create-cloudflare/templates/common/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/hello-world-durable-object/js/wrangler.toml b/packages/create-cloudflare/templates/hello-world-durable-object/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/hello-world-durable-object/ts/wrangler.toml b/packages/create-cloudflare/templates/hello-world-durable-object/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/hello-world-python/py/wrangler.toml b/packages/create-cloudflare/templates/hello-world-python/py/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/entry.py"
 compatibility_flags = ["python_workers"]

diff --git a/packages/create-cloudflare/templates/hello-world/js/wrangler.toml b/packages/create-cloudflare/templates/hello-world/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.js"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/hello-world/ts/wrangler.toml b/packages/create-cloudflare/templates/hello-world/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/next/wrangler.toml b/packages/create-cloudflare/templates/next/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 compatibility_flags = ["nodejs_compat"]

diff --git a/packages/create-cloudflare/templates/nuxt/templates/wrangler.toml b/packages/create-cloudflare/templates/nuxt/templates/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/create-cloudflare/templates/openapi/ts/wrangler.toml b/packages/create-cloudflare/templates/openapi/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"
diff --git a/packages/create-cloudflare/templates/pre-existing/js/wrangler.toml b/packages/create-cloudflare/templates/pre-existing/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.js"
 compatibility_date = "<TBD>"
diff --git a/packages/create-cloudflare/templates/queues/js/wrangler.toml b/packages/create-cloudflare/templates/queues/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.js"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/queues/ts/wrangler.toml b/packages/create-cloudflare/templates/queues/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/qwik/templates/wrangler.toml b/packages/create-cloudflare/templates/qwik/templates/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/create-cloudflare/templates/remix/templates/wrangler.toml b/packages/create-cloudflare/templates/remix/templates/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/create-cloudflare/templates/scheduled/js/wrangler.toml b/packages/create-cloudflare/templates/scheduled/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.js"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/scheduled/ts/wrangler.toml b/packages/create-cloudflare/templates/scheduled/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 main = "src/index.ts"
 compatibility_date = "<TBD>"

diff --git a/packages/create-cloudflare/templates/svelte/js/wrangler.toml b/packages/create-cloudflare/templates/svelte/js/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/create-cloudflare/templates/svelte/ts/wrangler.toml b/packages/create-cloudflare/templates/svelte/ts/wrangler.toml
@@ -1,3 +1,4 @@
+#:schema node_modules/wrangler/config-schema.json
 name = "<TBD>"
 compatibility_date = "<TBD>"
 

diff --git a/packages/wrangler/package.json b/packages/wrangler/package.json
@@ -47,18 +47,20 @@
 		"wrangler-dist",
 		"templates",
 		"kv-asset-handler.js",
-		"Cloudflare_CA.pem"
+		"Cloudflare_CA.pem",
+		"config-schema.json"
 	],
 	"scripts": {
 		"assert-git-version": "node -r esbuild-register scripts/assert-git-version.ts",
-		"build": "pnpm run clean && pnpm run bundle && pnpm run emit-types",
+		"build": "pnpm run clean && pnpm run bundle && pnpm run emit-types && pnpm run generate-json-schema",
 		"bundle": "node -r esbuild-register scripts/bundle.ts",
 		"check:lint": "eslint .",
 		"check:type": "tsc",
 		"clean": "rimraf wrangler-dist miniflare-dist emitted-types",
 		"dev": "pnpm run clean && concurrently -c black,blue --kill-others-on-fail false \"pnpm run bundle --watch\" \"pnpm run check:type --watch --preserveWatchOutput\"",
 		"emit-types": "tsc -p tsconfig.emit.json && node -r esbuild-register scripts/emit-types.ts",
-		"prepublishOnly": "SOURCEMAPS=false npm run build",
+		"generate-json-schema": "pnpm exec ts-json-schema-generator --no-type-check --path src/config/config.ts --type RawConfig --out config-schema.json",
+		"prepublishOnly": "SOURCEMAPS=false pnpm run build",
 		"start": "pnpm run bundle && cross-env NODE_OPTIONS=--enable-source-maps ./bin/wrangler.js",
 		"test": "pnpm run assert-git-version && jest",
 		"test:ci": "pnpm run test",
@@ -108,6 +110,7 @@
 		"resolve.exports": "^2.0.2",
 		"selfsigned": "^2.0.1",
 		"source-map": "0.6.1",
+		"ts-json-schema-generator": "^1.5.0",
 		"xxhash-wasm": "^1.0.1"
 	},
 	"devDependencies": {

diff --git a/packages/wrangler/src/config/config.ts b/packages/wrangler/src/config/config.ts
@@ -28,7 +28,7 @@ export type RawConfig = Partial<ConfigFields<RawDevConfig>> &
 	PagesConfigFields &
 	RawEnvironment &
 	DeprecatedConfigFields &
-	EnvironmentMap;
+	EnvironmentMap & { $schema?: string };
 
 // Pages-specific configuration fields
 export interface PagesConfigFields {
@@ -73,7 +73,7 @@ export interface ConfigFields<Dev extends RawDevConfig> {
 	 *
 	 * More details at https://developers.cloudflare.com/workers/learning/using-durable-objects#configuring-durable-object-classes-with-migrations
 	 *
-	 * @default `[]`
+	 * @default []
 	 */
 	migrations: {
 		/** A unique identifier for this migration. */
@@ -121,7 +121,7 @@ export interface ConfigFields<Dev extends RawDevConfig> {
 				 * items will be uploaded. Example: include = ["upload_dir"]
 				 *
 				 * @optional
-				 * @default `[]`
+				 * @default []
 				 */
 				include?: string[];
 
@@ -131,7 +131,7 @@ export interface ConfigFields<Dev extends RawDevConfig> {
 				 * uploads. Example: exclude = ["ignore_dir"]
 				 *
 				 * @optional
-				 * @default `[]`
+				 * @default []
 				 */
 				exclude?: string[];
 		  }
@@ -213,28 +213,28 @@ export interface DevConfig {
 	/**
 	 * IP address for the local dev server to listen on,
 	 *
-	 * @default `localhost`
+	 * @default localhost
 	 */
 	ip: string;
 
 	/**
 	 * Port for the local dev server to listen on
 	 *
-	 * @default `8787`
+	 * @default 8787
 	 */
 	port: number | undefined;
 
 	/**
 	 * Port for the local dev server's inspector to listen on
 	 *
-	 * @default `9229`
+	 * @default 9229
 	 */
 	inspector_port: number | undefined;
 
 	/**
 	 * Protocol that local wrangler dev server listens to requests on.
 	 *
-	 * @default `http`
+	 * @default http
 	 */
 	local_protocol: "http" | "https";
 
@@ -244,7 +244,7 @@ export interface DevConfig {
 	 * Setting this to `http` is not currently implemented for remote mode.
 	 * See https://github.com/cloudflare/workers-sdk/issues/583
 	 *
-	 * @default `https` in remote mode; same as local_protocol in local mode.
+	 * @default https
 	 */
 	upstream_protocol: "https" | "http";
 
@@ -293,7 +293,7 @@ interface EnvironmentMap {
 	 *
 	 * For more information, see the documentation at https://developers.cloudflare.com/workers/cli-wrangler/configuration#environments
 	 *
-	 * @default `{}`
+	 * @default {}
 	 */
 	env?: {
 		[envName: string]: RawEnvironment;

diff --git a/packages/wrangler/src/config/validation.ts b/packages/wrangler/src/config/validation.ts
@@ -126,6 +126,15 @@ export function normalizeAndValidateConfig(
 		"string"
 	);
 
+	// Support explicit JSON schema setting
+	validateOptionalProperty(
+		diagnostics,
+		"",
+		"$schema",
+		rawConfig.$schema,
+		"string"
+	);
+
 	// TODO: set the default to false to turn on service environments as the default
 	const isLegacyEnv =
 		typeof args["legacy-env"] === "boolean"
@@ -272,7 +281,7 @@ export function normalizeAndValidateConfig(
 		diagnostics,
 		"top-level",
 		Object.keys(rawConfig),
-		[...Object.keys(config), "env"]
+		[...Object.keys(config), "env", "$schema"]
 	);
 
 	experimental(diagnostics, rawConfig, "assets");

diff --git a/packages/wrangler/src/deprecated/index.ts b/packages/wrangler/src/deprecated/index.ts
@@ -35,6 +35,9 @@ export async function buildHandler(buildArgs: BuildArgs) {
 		"--dry-run",
 		"--outdir=dist",
 		...(buildArgs.env ? ["--env", buildArgs.env] : []),
+		...(buildArgs.config ? ["--config", buildArgs.config] : []),
+		...(buildArgs.experimentalJsonConfig ? ["--experimental-json-config"] : []),
+		...(buildArgs.experimentalVersions ? ["--experimental-versions"] : []),
 	]).parse();
 }