CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.4.137](https://github.com/brillout/vite-plugin-ssr/compare/v0.4.136...v0.4.137) (2023-08-23)
+
+
+### Bug Fixes
+
+* [V1 design] improve error messages ([42e3b6c](https://github.com/brillout/vite-plugin-ssr/commit/42e3b6c83f7e5183054f1544a2fa93d32763497c))
+* apply config.redirects to URL without Base URL ([7202ab6](https://github.com/brillout/vite-plugin-ssr/commit/7202ab61ad07872335ad69147c00c358d87486f5))
+* check whether link is client-side routable only when strictly needed ([#1073](https://github.com/brillout/vite-plugin-ssr/issues/1073)) ([575d48c](https://github.com/brillout/vite-plugin-ssr/commit/575d48c96894627440cee8dff5e0582c279889fd))
+* don't call guard() hook for the error page (fix [#1090](https://github.com/brillout/vite-plugin-ssr/issues/1090)) ([4013ac6](https://github.com/brillout/vite-plugin-ssr/commit/4013ac66749dc56769596afb468ab9894102bff9))
+* don't pass _abortCaller to client-side ([359bddf](https://github.com/brillout/vite-plugin-ssr/commit/359bddf3c708f07481cd7f16c30a5e188ddbe818))
+* expose pageContext.abortStatusCode ([#1077](https://github.com/brillout/vite-plugin-ssr/issues/1077)) ([1f7b92b](https://github.com/brillout/vite-plugin-ssr/commit/1f7b92b9153f3f58f5d33e41678b10ace9e2386b))
+* improve RenderErrorPage() dev logging ([2dbc2a2](https://github.com/brillout/vite-plugin-ssr/commit/2dbc2a2dffc6e22ef5ac23780ac1fea70d30b065))
+* preserve URL origin upon URL path normalization redirection ([3b43bb7](https://github.com/brillout/vite-plugin-ssr/commit/3b43bb7bf790def4775d5ca58672b502d355fdea))
+* remove superfluous Node.js dependency ([fabbee3](https://github.com/brillout/vite-plugin-ssr/commit/fabbee3b5c8e30cdd7c6a09b93ef5b220ce44211))
+* show RenderErrorPage() deprecation warning more prominently ([6ba3a2a](https://github.com/brillout/vite-plugin-ssr/commit/6ba3a2a2fc1d8a547ce5b2476cbaea013a3dfe92))
+* warn users that still use CJS ([290403b](https://github.com/brillout/vite-plugin-ssr/commit/290403bda286fa39ac7c0233d373207dd02bd459))
+
+
+### Features
+
+* hook supressing by setting hook value to `null` (fix [#1075](https://github.com/brillout/vite-plugin-ssr/issues/1075)) ([11202d2](https://github.com/brillout/vite-plugin-ssr/commit/11202d24730af9e9477283f9e921609b421b6865))
+
+
+
 ## [0.4.136](https://github.com/brillout/vite-plugin-ssr/compare/v0.4.135...v0.4.136) (2023-08-15)
 
 
@@ -1070,8 +1094,8 @@
 
 ### Bug Fixes
 
-* assert Stem pacakges to define package.json#exports ([55c40b8](https://github.com/brillout/vite-plugin-ssr/commit/55c40b86d1cedb9dfc29ffcee1dedb465f3a8490))
-* don't assume Stem pacakges to always define a VPS config ([f5c41d6](https://github.com/brillout/vite-plugin-ssr/commit/f5c41d6a24d68c917cc86e4e4a805dfa929b92c3))
+* assert Stem packages to define package.json#exports ([55c40b8](https://github.com/brillout/vite-plugin-ssr/commit/55c40b86d1cedb9dfc29ffcee1dedb465f3a8490))
+* don't assume Stem packages to always define a VPS config ([f5c41d6](https://github.com/brillout/vite-plugin-ssr/commit/f5c41d6a24d68c917cc86e4e4a805dfa929b92c3))
 * fix resolving of Stem client entries ([cb2f359](https://github.com/brillout/vite-plugin-ssr/commit/cb2f35945d5644ef3961f0c6ba6fe0e80aac06d8))
 * refine wrong usage message ([#516](https://github.com/brillout/vite-plugin-ssr/issues/516)) ([1e4dbe6](https://github.com/brillout/vite-plugin-ssr/commit/1e4dbe65cf552665b388eac54e4dd3ad3f50db00))
 * workaround windows bug ([91393d7](https://github.com/brillout/vite-plugin-ssr/commit/91393d73ef4032059f3618fd652a09b0b80ee088))

boilerplates/boilerplate-react-ts/package.json

@@ -30,7 +30,7 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.1.6",
     "vite": "^4.4.9",
-    "vite-plugin-ssr": "^0.4.136"
+    "vite-plugin-ssr": "^0.4.137"
   },
   "type": "module"
 }

boilerplates/boilerplate-react/package.json

@@ -21,7 +21,7 @@
     "react-dom": "^18.2.0",
     "sirv": "^2.0.3",
     "vite": "^4.4.9",
-    "vite-plugin-ssr": "^0.4.136"
+    "vite-plugin-ssr": "^0.4.137"
   },
   "type": "module"
 }

boilerplates/boilerplate-vue-ts/package.json

@@ -21,7 +21,7 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.1.6",
     "vite": "^4.4.9",
-    "vite-plugin-ssr": "^0.4.136",
+    "vite-plugin-ssr": "^0.4.137",
     "vue": "^3.3.4"
   },
   "type": "module"

boilerplates/boilerplate-vue/package.json

@@ -15,7 +15,7 @@
     "express": "^4.18.2",
     "sirv": "^2.0.3",
     "vite": "^4.4.9",
-    "vite-plugin-ssr": "^0.4.136",
+    "vite-plugin-ssr": "^0.4.137",
     "vue": "^3.3.4"
   },
   "type": "module"

boilerplates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vite-plugin-ssr",
-  "version": "0.0.297",
+  "version": "0.0.298",
   "license": "MIT",
   "bin": {
     "create-vite-plugin-ssr": "index.js"

docs/headings.tsx

@@ -564,6 +564,11 @@ const headings = [
     title: 'Markdown',
     url: '/markdown'
   },
+  {
+    level: 2,
+    title: 'MDXEditor',
+    url: '/MDXEditor'
+  },
   {
     level: 2,
     title: 'Tauri',

docs/headingsDetached.tsx

@@ -296,5 +296,21 @@ const headingsDetached = [
   {
     title: 'Page Redirection',
     url: '/page-redirection'
+  },
+  {
+    title: (
+      <>
+        Migration <code>0.5</code>
+      </>
+    ),
+    url: '/migration/0.5'
+  },
+  {
+    title: "Vite's Lazy Transpiling",
+    url: '/lazy-transpiling'
+  },
+  {
+    title: 'CJS',
+    url: '/CJS'
   }
 ] satisfies HeadingDetachedDefinition[]

docs/package.json

@@ -5,14 +5,14 @@
     "preview": "docpress build && docpress preview"
   },
   "dependencies": {
-    "@brillout/docpress": "^0.5.4",
+    "@brillout/docpress": "^0.5.8",
     "@types/node": "^15.12.1",
     "@types/react": "^17.0.45",
     "@types/react-dom": "^17.0.6",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^5.0.3",
-    "vite-plugin-ssr": "0.4.136"
+    "vite-plugin-ssr": "0.4.137"
   },
   "type": "module"
 }

docs/pages/CJS.page.server.mdx

@@ -0,0 +1,41 @@
+While you can use vite-plugin-ssr with
+[CJS code](https://nodejs.org/api/modules.html#modules-commonjs-modules:~:text=CommonJS%20modules%20are%20the%20original%20way%20to%20package%20JavaScript%20code%20for%20Node.js.%20Node.js%20also%20supports%20the%20ECMAScript%20modules%20standard%20used%20by%20browsers%20and%20other%20JavaScript%20runtimes.),
+we recommend writing
+[ESM code](https://nodejs.org/api/esm.html#modules-ecmascript-modules:~:text=ECMAScript%20modules%20are%20the%20official%20standard%20format%20to%20package%20JavaScript%20code%20for%20reuse.%20Modules%20are%20defined%20using%20a%20variety%20of%20import%20and%20export%20statements.)
+instead.
+
+> The code you write that is processed by Vite is already ESM. But [some of your server code may not be processed by Vite](https://github.com/brillout/vite-plugin-ssr/issues/562) and may be CJS.
+
+If you get the following warning:
+
+```
+[vite-plugin-ssr][Warning] We recommend setting package.json#type to "module" (and therefore
+writing ESM code instead of CJS code)
+```
+
+Then, in order to remove the warning, add this to your `package.json`:
+
+```json5
+// package.json
+{
+   // ...
+   type: "module"
+}
+```
+
+This [makes Node.js treat all .js files as ESM](https://nodejs.org/docs/latest-v13.x/api/esm.html#esm_package_json_type_field:~:text=Files%20ending%20with%20.js%20will%20be%20loaded%20as%20ES%20modules%20when%20the%20nearest%20parent%20package.json%20file%20contains%20a%20top%2Dlevel%20field%20%22type%22%20with%20a%20value%20of%20%22module%22.).
+
+This means that, if you have .js files written in CJS, then you'll have to migrate them to ESM. For example:
+
+```js
+-// CJS code
+-const express = require('express')
+-const { renderPage } = require('vite-plugin-ssr/server')
++// ESM code
++import express from 'express'
++import { renderPage } from 'vite-plugin-ssr/server'
+```
+
+> An escape hatch is to use [the `.cjs` and `.mjs` file extensions](https://nodejs.org/api/esm.html#enabling:~:text=Authors%20can%20tell%20Node.js%20to%20use%20the%20ECMAScript%20modules%20loader%20via%20the%20.mjs%20file%20extension), enabling you to determine/change the module system on a file-by-file basis regardless of whether `package.json#type` is set to `"module"` or `"commonjs"`.
+
+> You still want to use CJS? Let us know why and we'll create a new `config.disableCJSWarning`.

docs/pages/MDXEditor.page.server.mdx

@@ -0,0 +1,3 @@
+To use [MDXEditor](https://github.com/mdx-editor/editor) make sure to [load it only on the client-side](https://vite-plugin-ssr.com/client-only-components).
+
+See conversation and example [here](https://github.com/brillout/vite-plugin-ssr/discussions/1084#discussioncomment-6778002).

docs/pages/architecture.page.server.mdx

@@ -21,7 +21,7 @@ We believe it's paramount for the web that these core constituents are developed
 
 Packages such as `vike-react`, `vike-vue` and `vike-solid` integrate UI frameworks so that you don't have to write any integration code.
 
-But, if you want, instead of using a `vike-*` package you can use the hooks `onRenderHtml()` and `onRenderClient()` for complete control over how pages are rendered.
+But, if you want, instead of using a <Link text={<><code>vike-*</code> package</>} href="/vike-packages" /> you can use the hooks `onRenderHtml()` and `onRenderClient()` for complete control over how pages are rendered.
 
 Not only can you manually integrate with any UI framework you want and however you want, you can also deeply integrate with your favorite data fetching tools. For example, you can integrate with Relay in ways that aren't possible with other frameworks.
 

docs/pages/client-only-components.page.server.mdx

@@ -1,26 +1,26 @@
 import { Link } from '@brillout/docpress'
 
-To render a component only on the client-side, wrap it with `<ClientOnly>`:
+You can render a component only on the client-side by wrapping it with a `<ClientOnly>` component.
 
 ```jsx
 <ClientOnly>
   <SomeComponent />
 </ClientOnly>
 ```
 
-> Alternatively, opt-out of SSR and render the page as SPA (while rendering other pages with SSR), see <Link href="/render-modes" />.
+> Alternatively, you can disable SSR and render the page as SPA instead (while rendering other pages with SSR). See <Link href="/render-modes" />.
 
 Common use cases:
 
- - **Library components that don't support SSR**. A solution is to render/load the problematic component only on the client-side.
+ - **Library components that don't support SSR**. A solution is to render/load the component only on the client-side.
    > Most component libraries nowadays support SSR but some don't. Some even crash when they're merely loaded on the server-side (for example, when libraries have hard references to browser-only APIs/objects such as `window`).
- - **Performance**. By using `<ClientOnly>` with a [dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), you can defer loading heavy components, for example as a complex interactive map. So that users can already interact with your page before even the browser starts loading the heavy component.
-   > Vite automatically code-splits `const { SomeComponent } = await import('some-library')`. In other words, the code of `<SomeComponent />` isn't included in the initial JavaScript client-side bundle: it's loaded only when/if `import()` is executed.
+ - **Performance**. By using `<ClientOnly>` with a [dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), you can defer loading heavy components, such as a complex interactive map. That way, your users can already interact with your page before even the browser starts loading that heavy component.
+   > Vite automatically code-splits `const { SomeComponent } = await import('some-library')`. In other words, the code of `<SomeComponent />` isn't included in the initial JavaScript client-side bundle: it's loaded only when and if `import()` is executed.
 
 
 ## React
 
-Rendering & loading a component only on the client-side:
+To render and load a component only on the client-side:
 
 ```jsx
 // /pages/location/select.page.jsx

docs/pages/debug.page.server.mdx

@@ -40,7 +40,7 @@ If you have a problem with Vite, we recommend considering injecting a bunch of `
 > Instead of:
 > ```bash
 > $ git clone git@github.com:vitejs/vite
-> $ cd vite/pacakges/vite/
+> $ cd vite/packages/vite/
 > $ pnpm install
 > $ pnpm run dev
 > $ cd ../../../my-app/

docs/pages/doNotPrerender.page.server.mdx

@@ -59,7 +59,7 @@ export const doNotPrerender = isCmsPreview() ? true : false
 
 > This is particularly useful for previewing CMS pages (we don't want to pre-renderer a CMS preview deploy).
 
-Note that <Link text={<><code>prerender()</code> hooks</>} href="prerender" /> are always called, regardless of `doNotPrerender`. If we want to call `prerender()` hooks conditionally as well:
+Note that <Link text={<><code>prerender()</code> hooks</>} href="/prerender" /> are always called, regardless of `doNotPrerender`. If we want to call `prerender()` hooks conditionally as well:
 
 ```js
 export const doNotPrerender = someCondition() ? true : false

docs/pages/error-page.page.server.mdx

@@ -1,6 +1,6 @@
 import { Link } from '@brillout/docpress'
 
-The error page, which is defined by `/renderer/_error.page.tsx`, is rendered when an error occurs. It's also rendered when you call <Link href="/render" text={<code>throw render(errorStatusCode)</code>}></Link>.
+The error page, which is defined by `/renderer/_error.page.tsx`, is rendered when an error occurs. It's also rendered when you call <Link href="/render" text={<code>throw render(abortStatusCode)</code>}></Link>.
 
 ```ts
 // /renderer/_error.page.ts
@@ -16,25 +16,22 @@ import { usePageContext } from 'vike-solid/usePageContext'
 function Page() {
   const pageContext = usePageContext()
 
-  // Message shown to the user
-  let msg: string
-
-  const abortReason: unknown = pageContext.abortReason
-  // Handle `throw render(403, { notAdmin: true })`
+  let msg: string // Message shown to the user
+  const { abortReason, abortStatusCode } = pageContext
   if (abortReason?.notAdmin) {
+    // Handle `throw render(403, { notAdmin: true })`
     msg = "You cannot access this page because you aren't an administrator."
-  }
-  // Handle `throw render(401, { notLoggedIn: true })`
-  if (abortReason?.notLoggedIn) {
-    msg = "You cannot access this page because you aren't logged in. Please log in."
-  }
-  // Handle `throw render(someErrorStatusCode, `You cannot access ${someCustomMessage}`)`
-  if (typeof abortReason === 'string') {
+  } else if (typeof abortReason === 'string') {
+    // Handle `throw render(abortStatusCode, `You cannot access ${someCustomMessage}`)`
     msg = abortReason
-  }
-
-  // Fallback error message
-  if (!msg) {
+  } else if (abortStatusCode === 403) {
+    // Handle `throw render(403)`
+    msg = "You cannot access this page because you don't have enough privileges."
+  } else if (abortStatusCode === 401) {
+    // Handle `throw render(401)`
+    msg = "You cannot access this page because you aren't logged in. Please log in."
+  } else {
+    // Fallback error message
     msg = pageContext.is404 ?
       "This page doesn't exist." :
       "Something went wrong. Sincere apologies. Try again (later)."
@@ -46,12 +43,12 @@ function Page() {
 
 > The <Link href="/usePageContext" /> UI component hook allows you to access <Link href="/pageContext" noBreadcrumb /> from any UI component.
 
-The `pageContext.abortReason` value is set by <Link href="/render" text={<code>throw render(errorStatusCode, abortReason)</code>} />, and `pageContext.is404` is set by vite-pugin-ssr.
+The `pageContext.abortReason` and `pageContext.abortStatusCode` values are set by <Link href="/render" text={<code>throw render(abortStatusCode, abortReason)</code>} />, and `pageContext.is404` is set by vite-pugin-ssr.
 
 The error page is rendered if:
  1. The URL didn't match the route of any of your pages (`404 Page Not Found`).
  2. One of your hooks threw an error (`500 Internal Error`).
- 3. You called <Link href="/render" text={<code>throw render(errorStatusCode)</code>} />.
+ 3. You called <Link href="/render" text={<code>throw render(abortStatusCode)</code>} />.
 
 > The error page is also rendered when vite-plugin-ssr throws an unexpected error (it has a bug), but since vite-plugin-ssr has no known bug this is very rare.
 

docs/pages/errors.page.server.mdx

@@ -30,7 +30,7 @@ Vite-plugin-ssr prettifies transpilation errors, such as errors thrown by [esbui
 While vite-plugin-ssr is careful about not removing relevant information, it may mistakenly do so. In that case [create a new GitHub issue](https://github.com/brillout/vite-plugin-ssr/issues/new?assignees=&labels=bug+%3Aboom%3A&projects=&template=bug_report.yml). Until a vite-plugin-ssr maintainer fixes the issue you can use the debug flag `DEBUG=vps:error`.
 
 ```shell
-# Original & verbose errors
+# Show verbose and original errors
 DEBUG=vps:error npm run dev
 ```
 

docs/pages/lazy-transpiling.page.server.mdx

@@ -0,0 +1,9 @@
+Vite introduces a novel development approach called Lazy Transpiling (aka On-demand Transpiling): instead of transpiling your entire codebase at once, Vite transpiles code only as your load that code.
+
+For example, if you define 100 pages and then open one of these pages in your browser then, in development, only the code for that one page is transpiled while the code for all the other 99 pages isn't transpiled.
+
+Thanks to lazy-transpiling, you can scale to extremely large codebases while preserving a fast development DX.
+
+This is a foundational novelty and is at the cornerstone of why Vite is fundamentally faster than alternatives.
+
+We believe Lazy Transpiling to be the future of web tooling.