create-pracht 0.6.0 → 0.6.2

package/skills/upgrade-pracht/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: upgrade-pracht
-version: 1.0.1
+version: 1.0.2
 description: |
-  Upgrade the @pracht/* packages in an app safely: inventory installed
-  versions, read the changelogs between installed and target, map breaking
-  changes to actual usage in the codebase, apply the upgrade, and walk the
-  verification ladder (doctor, typegen, verify, build, tests).
-  Use when asked to "upgrade pracht", "update @pracht packages", "bump the
-  framework", "what changed in the new pracht version", or "is this pracht
-  upgrade safe".
+  Upgrade the `@pracht/*` packages safely: inventory installed versions, read the
+  changelogs between installed and target, map breaking changes to real usage,
+  apply, then walk the verification ladder (doctor, typegen, verify, build,
+  tests).
+  Use for "upgrade pracht", "update @pracht packages", "bump the framework", "what
+  changed in the new pracht version", "is this upgrade safe".
 allowed-tools:
   - Bash
   - Read
@@ -33,8 +32,9 @@ pnpm list --depth 1 --json | grep -A2 '@pracht/'   # or read package.json + lock
 
 The family: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
 `@pracht/adapter-node`, `@pracht/adapter-cloudflare`, `@pracht/adapter-vercel`,
-`@pracht/preact-ssr-precompile`, `@pracht/image`. Get the latest published
-versions with `npm view <pkg> version`.
+`@pracht/preact-ssr-precompile`, `@pracht/content`, `@pracht/markdown`,
+`@pracht/image`. Get the latest published versions with
+`npm view <pkg> version`.
 
 ## Step 2: Understand the versioning model
 
@@ -75,6 +75,8 @@ https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGE
 | `@pracht/vite-plugin` | `packages/vite-plugin` |
 | `@pracht/adapter-node` / `-cloudflare` / `-vercel` | `packages/adapter-*` |
 | `@pracht/preact-ssr-precompile` | `packages/preact-ssr-precompile` |
+| `@pracht/content` | `packages/content` |
+| `@pracht/markdown` | `packages/markdown` |
 | `@pracht/image` | `packages/image` |
 
 Changelogs are changesets-generated: `## X.Y.Z` sections containing

package/src/index.js

@@ -1298,6 +1298,11 @@ function createWranglerConfig(projectName) {
     // validates every named export of the deployed entry module and rejects the
     // build metadata (buildTarget, manifests, ...) server.js also exports.
     '  "main": "dist/server/worker.js",',
+    // Pracht's Vite build is the authoritative bundle and may contain lazy
+    // server chunks. A second Wrangler bundle would inline them again; the
+    // module rule makes Wrangler upload those chunks next to the entry.
+    '  "no_bundle": true,',
+    '  "rules": [{ "type": "ESModule", "globs": ["**/*.js", "**/*.mjs"] }],',
     `  "compatibility_date": ${JSON.stringify(compatibilityDate)},`,
     '  "assets": {',
     '    "binding": "ASSETS",',
@@ -1431,6 +1436,12 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   // needs the explicit `run` form the same way npm does.
   const runCmd =
     packageManager === "npm" || packageManager === "bun" ? `${packageManager} run` : packageManager;
+  // The pages router derives route ids from filenames, so the home page of a
+  // pages app is `index` (`src/pages/index.tsx`); the manifest scaffold names
+  // it `home` explicitly. Every id in the instructions below has to be one the
+  // scaffold actually generated, or the first link an agent writes is the very
+  // compile error these conventions exist to prevent.
+  const homeRouteId = router === "pages" ? "index" : "home";
 
   const lines = [
     "# Pracht App",
@@ -1535,6 +1546,21 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("- `netlify.toml` — Netlify build, publish, and functions configuration");
   }
 
+  lines.push("");
+  lines.push("## Conventions");
+  lines.push("");
+  lines.push(
+    `- Navigate by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
+      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes take ` +
+      "their segments through `params`. `<Link href>` is a type error — the id survives a path " +
+      "change and `pracht typegen` types both the id and its params. Use a plain `<a href>` for " +
+      "external and user-provided URLs.",
+  );
+  lines.push(
+    "- Run `pracht typegen` once to type route ids, params, and `apiFetch()`; `pracht dev` keeps " +
+      "them in sync.",
+  );
+
   if (agentTools) {
     lines.push("");
     lines.push("## Agent tooling");
@@ -1575,6 +1601,9 @@ function createReadme({
   const deployCommand = packageManager === "npm" ? "npm run deploy" : `${packageManager} deploy`;
   const typecheckCommand =
     packageManager === "npm" ? "npm run typecheck" : `${packageManager} typecheck`;
+  // The pages router derives route ids from filenames, so its home page is
+  // "index" where the manifest starter names it "home".
+  const homeRouteId = router === "pages" ? "index" : "home";
 
   const lines = [
     `# ${projectName}`,
@@ -1658,6 +1687,20 @@ function createReadme({
     lines.push("- `src/api/health.ts` is a sample API route.");
   }
 
+  // The one convention a new app trips over before it writes anything else,
+  // and AGENTS.md — where the same note lives for coding agents — is only
+  // seeded when agent tooling is enabled.
+  lines.push("");
+  lines.push("## Navigating");
+  lines.push("");
+  lines.push(
+    `Pracht navigates by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
+      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes ` +
+      "take their segments through `params`. The id survives a path change, and `pracht " +
+      "typegen` types both the id and its params — so `<Link href>` is a compile error. Use a " +
+      "plain `<a href>` for external and user-provided URLs.",
+  );
+
   if (packageManager === "pnpm") {
     lines.push(
       pnpmWorkspaceNotice