[C3] Improve type support in Qwik template (#5052)

* Add helper script for developing codemods

* Add a function for handling directories of snippets to be used in codemods

* Improve out of the box support for types in qwik template

* Add build-cf-types script to nuxt

* Adding changeset

* fixing typo

* Add an env variable that overrides e2e project path for debug purposes

* Fix e2e test

* Update gitignore

* Renaming codemode dev script

* Update qwik vite codemod to be less destructive

* Fix bug in codemod

* Attempt to de-flake verifyDev with retry

* Increase retry interval

Author: jculvey

.changeset/two-ants-work.md

@@ -0,0 +1,7 @@
+---
+"create-cloudflare": patch
+---
+
+feature: Add script to Qwik template for building Env type definitions.
+
+When creating a project with the Qwik template, the `QwikCityPlatform` type will be updated to contain a definition for the `env` property. These types can be re-generated with a newly added `build-cf-types` script.

packages/create-cloudflare/.gitignore

@@ -12,3 +12,6 @@ templates/**/pnpm-lock.yaml
 
 # the build step renames .gitignore files to __dot__gitignore
 templates/**/__dot__gitignore
+
+scripts/snippets
+!scripts/snippets/.gitkeep

packages/create-cloudflare/e2e-tests/frameworks.test.ts

@@ -442,8 +442,15 @@ const verifyDevScript = async (
 		logStream
 	);
 
-	// Wait an eternity for the dev server to spin up
-	await sleep(12000);
+	// Retry requesting the test route from the devserver
+	await retry({ times: 10 }, async () => {
+		await sleep(2000);
+		const res = await fetch(`http://localhost:${TEST_PORT}${verifyDev.route}`);
+		const body = await res.text();
+		if (!body.match(verifyDev?.expectedText)) {
+			throw new Error("Expected text not found in response from devserver.");
+		}
+	});
 
 	// Make a request to the specified test route
 	const res = await fetch(`http://localhost:${TEST_PORT}${verifyDev.route}`);
@@ -472,8 +479,17 @@ const verifyBuildScript = async (
 
 	const { outputDir, script, route, expectedText } = verifyBuild;
 
-	// Run the build script
 	const { name: pm, npx } = detectPackageManager();
+
+	// Run the `build-cf-types` script to generate types for bindings in fixture
+	const buildTypesProc = spawnWithLogging(
+		[pm, "run", "build-cf-types"],
+		{ cwd: projectPath },
+		logStream
+	);
+	await waitForExit(buildTypesProc);
+
+	// Run the build scripts
 	const buildProc = spawnWithLogging(
 		[pm, "run", script],
 		{

packages/create-cloudflare/e2e-tests/helpers.ts

@@ -233,9 +233,9 @@ const normalizeTestName = (ctx: TaskContext) => {
 };
 
 export const testProjectDir = (suite: string) => {
-	const tmpDirPath = realpathSync(
-		mkdtempSync(join(tmpdir(), `c3-tests-${suite}`))
-	);
+	const tmpDirPath =
+		process.env.E2E_PROJECT_PATH ??
+		realpathSync(mkdtempSync(join(tmpdir(), `c3-tests-${suite}`)));
 
 	const randomSuffix = crypto.randomBytes(4).toString("hex");
 	const baseProjectName = `${C3_E2E_PREFIX}${randomSuffix}`;
@@ -244,6 +244,11 @@ export const testProjectDir = (suite: string) => {
 	const getPath = (suffix: string) => join(tmpDirPath, getName(suffix));
 	const clean = (suffix: string) => {
 		try {
+			if (process.env.E2E_PROJECT_PATH) {
+				return;
+			}
+
+			realpathSync(mkdtempSync(join(tmpdir(), `c3-tests-${suite}`)));
 			const path = getPath(suffix);
 			rmSync(path, {
 				recursive: true,

packages/create-cloudflare/package.json

@@ -27,6 +27,7 @@
 	],
 	"scripts": {
 		"build": "node -r esbuild-register scripts/build.ts",
+		"dev:codemod": "node -r esbuild-register scripts/codemodDev.ts",
 		"check:lint": "eslint .",
 		"check:type": "tsc",
 		"lint": "eslint",

packages/create-cloudflare/scripts/codemodDev.ts

@@ -0,0 +1,62 @@
+import { join } from "path";
+import { parseFile, parseTs } from "helpers/codemod";
+import { writeFile } from "helpers/files";
+import * as recast from "recast";
+
+/**
+ * Writing code-mods often requires some trial and error. Since they are often
+ * applied later on in a c3 run, manual testing can become a hassle. This script was meant
+ * to help test and develop transforms in isolation without having to write a throw-away script.
+ *
+ * Replace your codemod below and run the script with `pnpm run dev:codemod`.
+ *
+ * Test files can be kept in the `./snippets` directory, where you will also find the output from
+ * the last run.
+ *
+ */
+
+/**
+ * This function mocks the `transformFile` API but outputs it to the console and writes it
+ * to a dedicated output file for easier testing.
+ */
+export const testTransform = (
+	filePath: string,
+	methods: recast.types.Visitor
+) => {
+	const ast = parseFile(join(__dirname, filePath));
+
+	if (ast) {
+		recast.visit(ast, methods);
+		const code = recast.print(ast).code;
+		console.log(code);
+		writeFile(join(__dirname, "snippets", "output"), code);
+	}
+};
+
+// Use this function to experiment with a codemod in isolation
+const testCodemod = () => {
+	// const b = recast.types.builders;
+	// const snippets = loadSnippets(join(__dirname, "snippets"));
+
+	testTransform("snippets/test.ts", {
+		visitIdentifier(n) {
+			n.node.name = "Potato";
+
+			return false;
+		},
+	});
+};
+testCodemod();
+
+// This function can be used to inspect the AST of a particular snippet
+const printSnippet = () => {
+	const snippet = `
+    if(true) {
+      console.log("potato");
+    }
+  `;
+
+	const program = parseTs(snippet).program;
+	console.log(program.body[0].consequent);
+};
+// printSnippet();

packages/create-cloudflare/scripts/snippets/.gitkeep

@@ -1,10 +1,13 @@
-import path from "path";
+import { existsSync, lstatSync, readdirSync } from "fs";
+import path, { extname, join } from "path";
 import { crash } from "@cloudflare/cli";
 import * as recast from "recast";
 import * as esprimaParser from "recast/parsers/esprima";
 import * as typescriptParser from "recast/parsers/typescript";
+import { getTemplatePath } from "../templates";
 import { readFile, writeFile } from "./files";
 import type { Program } from "esprima";
+import type { C3Context } from "types";
 
 /*
   CODEMOD TIPS & TRICKS
@@ -55,7 +58,7 @@ export const parseFile = (filePath: string) => {
 		const fileContents = readFile(path.resolve(filePath));
 
 		if (fileContents) {
-			return recast.parse(fileContents, { parser }) as Program;
+			return recast.parse(fileContents, { parser }).program as Program;
 		}
 	} catch (error) {
 		crash(`Error parsing file: ${filePath}`);
@@ -76,3 +79,37 @@ export const transformFile = (
 		writeFile(filePath, recast.print(ast).code);
 	}
 };
+
+export const loadSnippets = (parentFolder: string) => {
+	const snippetsPath = join(parentFolder, "snippets");
+
+	if (!existsSync(snippetsPath)) {
+		return {};
+	}
+
+	if (!lstatSync(snippetsPath).isDirectory) {
+		return {};
+	}
+
+	const files = readdirSync(snippetsPath);
+
+	return (
+		files
+			// don't try loading directories
+			.filter((fileName) => lstatSync(join(snippetsPath, fileName)).isFile)
+			// only load js or ts files
+			.filter((fileName) => [".js", ".ts"].includes(extname(fileName)))
+			.reduce((acc, snippetPath) => {
+				const [file, ext] = snippetPath.split(".");
+				const key = `${file}${ext === "js" ? "Js" : "Ts"}`;
+				return {
+					...acc,
+					[key]: parseFile(join(snippetsPath, snippetPath))?.body,
+				};
+			}, {}) as Record<string, recast.types.ASTNode[]>
+	);
+};
+
+export const loadTemplateSnippets = (ctx: C3Context) => {
+	return loadSnippets(getTemplatePath(ctx));
+};

packages/create-cloudflare/src/helpers/codemod.ts

@@ -93,6 +93,7 @@ const config: TemplateConfig = {
 		scripts: {
 			deploy: `${npm} run build && wrangler pages deploy ./dist`,
 			preview: `${npm} run build && wrangler pages dev ./dist`,
+			"build-cf-types": `wrangler types`,
 		},
 	}),
 };

packages/create-cloudflare/templates/nuxt/c3.ts

@@ -1,13 +1,13 @@
-import { endSection } from "@cloudflare/cli";
+import { crash, endSection } from "@cloudflare/cli";
 import { brandColor } from "@cloudflare/cli/colors";
 import { spinner } from "@cloudflare/cli/interactive";
-import { parseTs, transformFile } from "helpers/codemod";
+import { loadTemplateSnippets, transformFile } from "helpers/codemod";
 import { runCommand, runFrameworkGenerator } from "helpers/command";
 import { usesTypescript } from "helpers/files";
 import { detectPackageManager } from "helpers/packages";
+import * as recast from "recast";
 import { quoteShellArgs } from "../../src/common";
 import type { TemplateConfig } from "../../src/templates";
-import type * as recast from "recast";
 import type { C3Context } from "types";
 
 const { npm, npx } = detectPackageManager();
@@ -23,6 +23,7 @@ const configure = async (ctx: C3Context) => {
 	await runCommand(cmd);
 
 	addBindingsProxy(ctx);
+	populateCloudflareEnv();
 };
 
 const addBindingsProxy = (ctx: C3Context) => {
@@ -35,43 +36,90 @@ const addBindingsProxy = (ctx: C3Context) => {
 	const s = spinner();
 	s.start("Updating `vite.config.ts`");
 
-	// Insert the env declaration after the last import (but before the rest of the body)
-	const envDeclaration = `
-let env = {};
-
-if(process.env.NODE_ENV === 'development') {
-  const { getPlatformProxy } = await import('wrangler');
-  const platformProxy = await getPlatformProxy();
-  env = platformProxy.env;
-}
-`;
+	const snippets = loadTemplateSnippets(ctx);
+	const b = recast.types.builders;
 
 	transformFile("vite.config.ts", {
+		// Insert the env declaration after the last import (but before the rest of the body)
 		visitProgram: function (n) {
 			const lastImportIndex = n.node.body.findLastIndex(
 				(t) => t.type === "ImportDeclaration"
 			);
-			n.get("body").insertAt(lastImportIndex + 1, envDeclaration);
+			const lastImport = n.get("body", lastImportIndex);
+			lastImport.insertAfter(...snippets.getPlatformProxyTs);
+
+			return this.traverse(n);
+		},
+		// Pass the `platform` object from the declaration to the `qwikCity` plugin
+		visitCallExpression: function (n) {
+			const callee = n.node.callee as recast.types.namedTypes.Identifier;
+			if (callee.name !== "qwikCity") {
+				return this.traverse(n);
+			}
+
+			// The config object passed to `qwikCity`
+			const configArgument = n.node.arguments[0] as
+				| recast.types.namedTypes.ObjectExpression
+				| undefined;
+
+			const platformPropery = b.objectProperty.from({
+				key: b.identifier("platform"),
+				value: b.identifier("platform"),
+				shorthand: true,
+			});
+
+			if (!configArgument) {
+				n.node.arguments = [b.objectExpression([platformPropery])];
+
+				return false;
+			}
+
+			if (configArgument.type !== "ObjectExpression") {
+				crash("Failed to update `vite.config.ts`");
+			}
+
+			// Add the `platform` object to the object
+			configArgument.properties.push(platformPropery);
 
 			return false;
 		},
 	});
 
-	// Populate the `qwikCity` plugin with the platform object containing the `env` defined above.
-	const platformObject = parseTs(`{ platform: { env } }`);
+	s.stop(`${brandColor("updated")} \`vite.config.ts\``);
+};
 
-	transformFile("vite.config.ts", {
-		visitCallExpression: function (n) {
-			const callee = n.node.callee as recast.types.namedTypes.Identifier;
-			if (callee.name === "qwikCity") {
-				n.node.arguments = [platformObject];
+const populateCloudflareEnv = () => {
+	const entrypointPath = "src/entry.cloudflare-pages.tsx";
+
+	const s = spinner();
+	s.start(`Updating \`${entrypointPath}\``);
+
+	transformFile(entrypointPath, {
+		visitTSInterfaceDeclaration: function (n) {
+			const b = recast.types.builders;
+			const id = n.node.id as recast.types.namedTypes.Identifier;
+			if (id.name !== "QwikCityPlatform") {
+				this.traverse(n);
 			}
 
-			this.traverse(n);
+			const newBody = [
+				["env", "Env"],
+				// Qwik doesn't supply `cf` to the platform object. Should they do so, uncomment this
+				// ["cf", "CfProperties"],
+			].map(([varName, type]) =>
+				b.tsPropertySignature(
+					b.identifier(varName),
+					b.tsTypeAnnotation(b.tsTypeReference(b.identifier(type)))
+				)
+			);
+
+			n.node.body.body = newBody;
+
+			return false;
 		},
 	});
 
-	s.stop(`${brandColor("updated")} \`vite.config.ts\``);
+	s.stop(`${brandColor("updated")} \`${entrypointPath}\``);
 };
 
 const config: TemplateConfig = {
@@ -89,6 +137,8 @@ const config: TemplateConfig = {
 	transformPackageJson: async () => ({
 		scripts: {
 			deploy: `${npm} run build && wrangler pages deploy ./dist`,
+			preview: `${npm} run build && wrangler pages dev ./dist`,
+			"build-cf-types": `wrangler types`,
 		},
 	}),
 };