[feat] more info about prerendering errors and new strict option (#7264)

* [fix] more info about prerendering errors

Helps with #7183 and #7244

* Apply suggestions from code review

* swap ternary around, remove dead code

* small tweak

* another minor tweak

* drive-by-fix

* tweak when prerender.entries suggestion appears

* tweak

* add strict option

* Apply suggestions from code review

Co-authored-by: Rich Harris <[email protected]>
Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

.changeset/tame-bats-tell.md

@@ -0,0 +1,6 @@
+---
+'@sveltejs/adapter-static': patch
+'@sveltejs/kit': patch
+---
+
+[feat] more info about prerendering errors, add strict option to adapter-static

documentation/docs/13-page-options.md

@@ -74,11 +74,11 @@ Note that this will disable client-side routing for any navigation from this pag
 
 #### Troubleshooting
 
-If you encounter an error like 'The following routes were marked as prerenderable, but were not prerendered' it's because the route in question (or a parent layout, if it's a page) has `export const prerender = true` but the page wasn't actually prerendered.
+If you encounter an error like 'The following routes were marked as prerenderable, but were not prerendered' it's because the route in question (or a parent layout, if it's a page) has `export const prerender = true` but the page wasn't actually prerendered, because it wasn't reached by the prerendering crawler.
 
 Since these routes cannot be dynamically server-rendered, this will cause errors when people try to access the route in question. There are two ways to fix it:
 
-* Ensure that SvelteKit can find the route by following links from [`config.kit.prerender.entries`](/docs/configuration#prerender). The pages containing the links (e.g. your `/` page) must _themselves_ be prerenderable, or they will be ignored
+* Ensure that SvelteKit can find the route by following links from [`config.kit.prerender.entries`](/docs/configuration#prerender). Add links to dynamic routes (i.e. pages with `[parameters]` ) to this option if they are not found through crawling the other entry points, else they are not prerendered because SvelteKit doesn't know what value the parameters should have. Pages not marked as prerenderable will be ignored and their links to other pages will not be crawled, even if some of them would be prerenderable.
 * Change `export const prerender = true` to `export const prerender = 'auto'`. Routes with `'auto'` can be dynamically server rendered
 
 ### ssr

documentation/docs/16-configuration.md

@@ -252,7 +252,7 @@ See [Prerendering](/docs/page-options#prerender). An object containing zero or m
 - `concurrency` — how many pages can be prerendered simultaneously. JS is single-threaded, but in cases where prerendering performance is network-bound (for example loading content from a remote CMS) this can speed things up by processing other tasks while waiting on the network response
 - `crawl` — determines whether SvelteKit should find pages to prerender by following links from the seed page(s)
 - `enabled` — set to `false` to disable prerendering altogether
-- `entries` — an array of pages to prerender, or start crawling from (if `crawl: true`). The `*` string includes all non-dynamic routes (i.e. pages with no `[parameters]` )
+- `entries` — an array of pages to prerender, or start crawling from (if `crawl: true`). The `*` string includes all non-dynamic routes (i.e. pages with no `[parameters]`, because SvelteKit doesn't know what value the parameters should have)
 - `onError`
 
   - `'fail'` — (default) fails the build when a routing error is encountered when following a link

packages/adapter-static/README.md

@@ -18,7 +18,8 @@ export default {
       pages: 'build',
       assets: 'build',
       fallback: null,
-      precompress: false
+      precompress: false,
+      strict: true
     })
   }
 };
@@ -71,6 +72,10 @@ Specify a fallback page for SPA mode, e.g. `index.html` or `200.html` or `404.ht
 
 If `true`, precompresses files with brotli and gzip. This will generate `.br` and `.gz` files.
 
+### strict
+
+By default, `adapter-static` checks that either all pages and endpoints (if any) of your app were prerendered, or you have the `fallback` option set. This check exists to prevent you from accidentally publishing an app where some parts of it are not accessible, because they are not contained in the final output. If you know this is ok (for example when a certain page only exists conditionally), you can set `strict` to `false` to turn off this check.
+
 ## SPA mode
 
 You can use `adapter-static` to create a single-page app or SPA by specifying a **fallback page**.

packages/adapter-static/index.d.ts

@@ -5,6 +5,7 @@ export interface AdapterOptions {
 	assets?: string;
 	fallback?: string;
 	precompress?: boolean;
+	strict?: boolean;
 }
 
 export default function plugin(options?: AdapterOptions): Adapter;

packages/adapter-static/index.js

@@ -24,13 +24,31 @@ export default function (options) {
 					};
 				});
 
-				if (dynamic_routes.length > 0) {
+				if (dynamic_routes.length > 0 && options.strict) {
 					const prefix = path.relative('.', builder.config.kit.files.routes);
+					const has_param_routes = dynamic_routes.some((route) => route.includes('['));
+					const config_option =
+						has_param_routes || JSON.stringify(builder.config.kit.prerender.entries) !== '["*"]'
+							? `  - adjust the \`prerender.entries\` config option ${
+									has_param_routes
+										? '(routes with parameters are not part of entry points by default)'
+										: ''
+							  } — see https://kit.svelte.dev/docs/configuration#prerender for more info.`
+							: '';
+
 					builder.log.error(
-						`@sveltejs/adapter-static: all routes must be fully prerenderable (unless using the 'fallback' option — see https://github.com/sveltejs/kit/tree/master/packages/adapter-static#spa-mode). Try adding \`export const prerender = true\` to your root +layout.js/.ts file — see https://kit.svelte.dev/docs/page-options#prerender for more details`
-					);
-					builder.log.error(
-						dynamic_routes.map((id) => `  - ${path.posix.join(prefix, id)}`).join('\n')
+						`@sveltejs/adapter-static: all routes must be fully prerenderable, but found the following routes that are dynamic:
+${dynamic_routes.map((id) => `  - ${path.posix.join(prefix, id)}`).join('\n')}
+
+You have the following options:
+  - set the \`fallback\` option — see https://github.com/sveltejs/kit/tree/master/packages/adapter-static#spa-mode for more info.
+  - add \`export const prerender = true\` to your root \`+layout.js/.ts\` or \`+layout.server.js/.ts\` file. This will try to prerender all pages.
+  - add \`export const prerender = true\` to any \`+server.js/ts\` files that are not fetched by page \`load\` functions.
+${config_option}
+  - pass \`strict: false\` to \`adapter-static\` to ignore this error. Only do this if you are sure you don't need the routes in question in your final app, as they will be unavailable. See https://github.com/sveltejs/kit/tree/master/packages/adapter-static#strict for more info.
+
+If this doesn't help, you may need to use a different adapter. @sveltejs/adapter-static can only be used for sites that don't need a server for dynamic rendering, and can run on just a static file server.
+See https://kit.svelte.dev/docs/page-options#prerender for more details`
 					);
 					throw new Error('Encountered dynamic routes');
 				}

packages/kit/src/core/adapt/builder.js

@@ -33,10 +33,11 @@ export function create_builder({ config, build_data, routes, prerendered, log })
 		async createEntries(fn) {
 			/** @type {import('types').RouteDefinition[]} */
 			const facades = routes.map((route) => {
+				/** @type {Set<import('types').HttpMethod>} */
 				const methods = new Set();
 
 				if (route.page) {
-					methods.add('SET');
+					methods.add('GET');
 				}
 
 				if (route.endpoint) {

packages/kit/src/core/prerender/prerender.js

@@ -431,9 +431,9 @@ export async function prerender() {
 
 	if (not_prerendered.length > 0) {
 		throw new Error(
-			`The following routes were marked as prerenderable, but were not prerendered:\n${not_prerendered.map(
+			`The following routes were marked as prerenderable, but were not prerendered because they were not found while crawling your app:\n${not_prerendered.map(
 				(id) => `  - ${id}`
-			)}\n\nSee https://kit.svelte.dev/docs/page-options#prerender-troubleshooting for more info`
+			)}\n\nSee https://kit.svelte.dev/docs/page-options#prerender-troubleshooting for info on how to solve this`
 		);
 	}
 

packages/kit/src/utils/filesystem.js

@@ -6,7 +6,12 @@ export function mkdirp(dir) {
 	try {
 		fs.mkdirSync(dir, { recursive: true });
 	} catch (/** @type {any} */ e) {
-		if (e.code === 'EEXIST') return;
+		if (e.code === 'EEXIST') {
+			if (!fs.statSync(dir).isDirectory()) {
+				throw new Error(`Cannot create directory ${dir}, a file already exists at this position`);
+			}
+			return;
+		}
 		throw e;
 	}
 }

packages/kit/test/build-errors/prerender.spec.js

@@ -11,7 +11,7 @@ test('prerenderable routes must be prerendered', () => {
 				stdio: 'pipe',
 				timeout: 15000
 			}),
-		/The following routes were marked as prerenderable, but were not prerendered:\r?\n  - \[x\]/gs
+		/The following routes were marked as prerenderable, but were not prerendered because they were not found while crawling your app:\r?\n  - \[x\]/gs
 	);
 });