docs(getting-started): warn that the published base tsconfig disables emit

docs/getting-started/add-to-existing-project.md

@@ -42,9 +42,17 @@ the shortest correct route:
 Make sure `include` covers wherever you keep your own source as well as your
 routes.
 
+The base config sets `"noEmit": true`: Veryfront bundles your routes itself and
+uses `tsc` only for typechecking. If your existing build emits JavaScript with
+`tsc`, do not replace your config with the extends form: the build keeps
+exiting 0 but silently stops emitting, and your output directory goes stale.
+Keep your own config and add the three options below instead, or set
+`"noEmit": false` in the config your build compiles with.
+
 ### Setting the options yourself
 
-If your project cannot extend that config, three settings matter:
+If your project cannot extend that config, including when your build emits
+with `tsc`, three settings matter:
 
 ```json
 {
@@ -131,6 +139,10 @@ runs:
 npm run build
 ```
 
+If that build emits files, check that its output was actually regenerated. A
+`tsc` build that inherited `"noEmit": true` still exits 0 while writing
+nothing.
+
 ## Next steps
 
 | Goal                    | Page                                    |

docs/getting-started/installation.md

@@ -87,6 +87,12 @@ Veryfront expects, including `"jsx": "react-jsx"` and
 }
 ```
 
+The base config sets `"noEmit": true` because Veryfront bundles your routes. If
+your existing build uses `tsc` to emit JavaScript, do not use this extends form:
+the build exits 0 but stops emitting. Keep your existing config and add the
+required compiler options, or set `"noEmit": false` in the config your build
+uses. See [Add to an existing project](./add-to-existing-project.md).
+
 ### Add a page and run it
 
 Veryfront discovers routes under `app/`. Create a home page:

tests/docs/guide-code-examples.test.ts

@@ -1072,6 +1072,14 @@ describe("Guide: installation.md", () => {
       assertStringIncludes(guide, heading);
     }
   });
+
+  it("warns emitting projects about the inherited noEmit setting", async () => {
+    const guide = await readGuide("installation.md");
+
+    assertStringIncludes(guide, '"noEmit": true');
+    assertStringIncludes(guide, "stops emitting");
+    assertStringIncludes(guide, "./add-to-existing-project.md");
+  });
 });
 
 describe("Guide: create-project.md", () => {
@@ -1134,6 +1142,21 @@ describe("Guide: add-to-existing-project.md", () => {
     assertStringIncludes(dnt, './tsconfig.json"] = "./tsconfig.json"');
   });
 
+  it("warns that the published base config disables emit", async () => {
+    // The shipped `veryfront/tsconfig.json` sets `noEmit: true`. A host
+    // project whose build is `tsc -p ...` keeps exiting 0 after switching to
+    // `extends` but silently stops emitting to its outDir — the page must
+    // steer emitting projects away from the extends route.
+    const dnt = await Deno.readTextFile(
+      new URL("../../scripts/build/build-npm-dnt.ts", import.meta.url),
+    );
+    assertStringIncludes(dnt, "noEmit: true");
+
+    const guide = await readGuide("add-to-existing-project.md");
+    assertStringIncludes(guide, '"noEmit": true');
+    assertStringIncludes(guide, "stops emitting");
+  });
+
   it("documents the install command and the entry route the server needs", async () => {
     const guide = await readGuide("add-to-existing-project.md");
 

tests/docs/guide-contracts.test.ts

@@ -780,6 +780,7 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
       '"moduleResolution": "bundler"',
       '"jsx": "react-jsx"',
       '"skipLibCheck": true',
+      '"noEmit": true',
       "@types/mdx",
       "// app/page.tsx",
       "npx veryfront dev",