wip: new docs

fastify · Nov 23, 2023 · 25c95f5 · 25c95f5
1 parent 82c1507
commit 25c95f5
Show file tree

Hide file tree

Showing 58 changed files with 899 additions and 875 deletions.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -62,18 +62,8 @@ export default withMermaid({
 
     footer: {
       message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2021-present Jonas gALVEZ'
+      copyright: 'Copyright © 2021-present Jonas Galvez'
     },
-
-    search: {
-      provider: 'algolia',
-      options: {
-        appId: '8J64VVRP8K',
-        apiKey: 'a18e2f4cc5665f6602c5631fd868adfd',
-        indexName: 'vitepress'
-      }
-    },
-
   }
 })
 
@@ -84,6 +74,16 @@ function nav(): DefaultTheme.NavItem[] {
       link: '/guide/getting-started',
       activeMatch: '/guide/'
     },
+    {
+      text: 'Vue',
+      link: '/vue/index',
+      activeMatch: '/vue/'
+    },
+    {
+      text: 'React',
+      link: '/react/index',
+      activeMatch: '/react/'
+    },
     {
       text: 'Configuration',
       link: '/config/index',
@@ -96,27 +96,27 @@ function nav(): DefaultTheme.NavItem[] {
 function sidebarGuide(): DefaultTheme.SidebarItem[] {
   return [
     Guide(),
+    ...Common(),
     Vue(true),
     React(true),
-    { text: 'Configuration', base: '/config/', link: 'index' }
   ]
 }
 
 function sidebarVue(): DefaultTheme.SidebarItem[] {
   return [
     Guide(true),
+    ...Common(),
     Vue(),
     React(true),
-    { text: 'Configuration', base: '/config/', link: 'index' }    
   ]
 }
 
 function sidebarReact(): DefaultTheme.SidebarItem[] {
   return [
     Guide(true),
+    ...Common(),    
     Vue(true),
     React(),
-    { text: 'Configuration', base: '/config/', link: 'index' }
   ]
 }
 
@@ -130,7 +130,7 @@ function sidebarConfig(): DefaultTheme.SidebarItem[] {
         { text: 'root', link: 'index#root' },
         { text: 'dev', link: 'index#dev' },
         { text: 'spa', link: 'index#spa' },
-        { text: 'renderer', link: 'index#renderer' },
+        { text: 'renderer', link: 'index#renderer' }
       ],
     },
     {
@@ -144,23 +144,46 @@ function sidebarConfig(): DefaultTheme.SidebarItem[] {
         { text: 'createHtmlFunction', link: 'index#createhtmlfunction' },
         { text: 'createRouteHandler', link: 'index#createroutehandler' },
         { text: 'createErrorHandler', link: 'index#createerrorhandler' },
-        { text: 'createRoute', link: 'index#createroute' },
+        { text: 'createRoute', link: 'index#createroute' }
       ]
     },
     {
       text: '@fastify/vue',
-      collapsed: true,
+      collapsed: false,
       items: [
         { text: 'Vite Plugin', link: 'vue/vite-plugin' },
-        { text: 'Virtual Modules', link: 'vue/virtual-modules' },
+        { 
+          text: 'Virtual Modules', 
+          link: 'vue/virtual-modules',
+          items: [
+            { text: '/:root.vue', link: 'vue/virtual-modules#root-vue' },
+            { text: '/:routes.js', link: 'vue/virtual-modules#routes-js' },
+            { text: '/:core.js', link: 'vue/virtual-modules#core-js' },
+            { text: '/:create.js', link: 'vue/virtual-modules#create-js' },
+            { text: '/:layouts/default.vue', link: 'vue/virtual-modules#layouts-default-vue' },
+            { text: '/:mount.js', link: 'vue/virtual-modules#mount-js' }
+          ]
+        },
       ]
     },
     {
       text: '@fastify/react',
-      collapsed: true,
+      collapsed: false,
       items: [
         { text: 'Vite Plugin', link: 'react/vite-plugin' },
-        { text: 'Virtual Modules', link: 'react/virtual-modules' },
+        { 
+          text: 'Virtual Modules', 
+          link: 'react/virtual-modules',
+          items: [
+            { text: '/:root.jsx', link: 'react/virtual-modules#root-jsx' },
+            { text: '/:routes.js', link: 'react/virtual-modules#routes-js' },
+            { text: '/:core.jsx', link: 'react/virtual-modules#core-jsx' },
+            { text: '/:create.jsx', link: 'react/virtual-modules#create-jsx' },
+            { text: '/:layouts/default.jsx', link: 'react/virtual-modules#layouts-default-jsx' },
+            { text: '/:mount.js', link: 'react/virtual-modules#mount-js' },
+            { text: '/:resource.js', link: 'react/virtual-modules#resource-js' }
+          ]
+        },
       ]
     },
   ]
@@ -177,14 +200,14 @@ function Guide (collapsed = false) {
           { text: 'Why not a framework?', link: 'getting-started#why-not-a-framework' },
           { text: 'A quick walkthrough', link: 'getting-started#a-quick-walkthrough' },
           { text: 'Directory structure', link: 'getting-started#directory-structure' },
-          { text: 'Architectural primitives', link: 'getting-started#architectural-primitives' },
+          { text: 'Architectural primitives', link: 'getting-started#architectural-primitives' }
         ],
       },
       { text: 'Rendering Function', link: 'rendering-function', },
       { text: 'Router Integration', link: 'router-integration', },
       { text: 'Templating Function', link: 'templating-function' },
       { text: 'Build and Deploy', link: 'build-and-deploy' },
-      { text: 'Core Renderers', link: 'core-renderers' },
+      { text: 'Core Renderers', link: 'core-renderers' }
     ]
   }
 }
@@ -219,7 +242,7 @@ function Vue (collapsed = false) {
         items: [
           { text: 'Data fetching', link: 'route-modules#data-fetching' },
           { text: 'Page metadata', link: 'route-modules#page-metadata' },
-          { text: 'The onEnter event', link: 'route-modules#the-onenter-event' },
+          { text: 'The onEnter event', link: 'route-modules#the-onenter-event' }
         ],        
       },
       { 
@@ -232,7 +255,7 @@ function Vue (collapsed = false) {
         ]
       },
       { text: 'Route Layouts', link: 'route-layouts' },
-      { text: 'Rendering Modes', link: 'rendering-modes' },      
+      { text: 'Rendering Modes', link: 'rendering-modes' }
     ]
   }
 }
@@ -267,7 +290,7 @@ function React (collapsed = false) {
         items: [
           { text: 'Data fetching', link: 'route-modules#data-fetching' },
           { text: 'Page metadata', link: 'route-modules#page-metadata' },
-          { text: 'The onEnter event', link: 'route-modules#the-onenter-event' },
+          { text: 'The onEnter event', link: 'route-modules#the-onenter-event' }
         ],        
       },
       { 
@@ -280,7 +303,15 @@ function React (collapsed = false) {
         ]
       },
       { text: 'Route Layouts', link: 'route-layouts' },
-      { text: 'Rendering Modes', link: 'rendering-modes' },      
+      { text: 'Rendering Modes', link: 'rendering-modes' } 
     ]
   }
-}
+}
+
+function Common () {
+  return [
+    { text: 'Configuration', base: '/config/', link: 'index' },
+    { text: 'Roadmap', base: '/roadmap/', link: 'index' },
+    { text: 'Contributing', base: '/contributing/', link: 'index' }
+  ]
+}
diff --git a/docs/.vitepress/theme/components/VPDocFooter.vue b/docs/.vitepress/theme/components/VPDocFooter.vue
@@ -41,6 +41,7 @@ const showFooter = computed(() => {
       </div>
     </div>
 
+    <!--
     <nav v-if="control.prev?.link || control.next?.link" class="prev-next">
       <div class="pager">
         <a v-if="control.prev?.link" class="pager-link prev" :href="normalizeLink(control.prev.link)">
@@ -55,6 +56,7 @@ const showFooter = computed(() => {
         </a>
       </div>
     </nav>
+    -->
   </footer>
 </template>
 

diff --git a/docs/config/index.md b/docs/config/index.md
@@ -4,26 +4,34 @@
 
 ### `root`
 
+The location of your Vite configuration file.
+
+It works with `import.meta.url` too.
+
 ### `dev`
 
+Enables Vite's development server if set to `true`.
+
 ### `spa`
 
-**Disables SSR** and just sets up integration for delivering a static SPA application. When set to `true`, `clientModule` resolution is disabled and the `Reply.html()` method doesn't require a context object with variables for the `index.html` template.
+When set to `true`, **disables SSR** and just sets up integration for delivering a static SPA application.
+
+`clientModule` resolution is disabled and the `Reply.html()` method doesn't require a context object with variables for the `index.html` template. 
+
+This can be customized however by providing your own `createHtmlFunction()`.
 
 ### `renderer`
 
-A single configuration object which can be used to set all of the settings above. 
+A single configuration object which can be used to set all [Renderer options](/config/#renderer-options). 
 
 - `clientModule`
-  'createErrorHandler',
-  'createHtmlFunction',
-  'createHtmlTemplateFunction',
-  'createRenderFunction',
-  'createRoute',
-  'createRouteHandler',
-  'prepareClient'
-
-
+- `createErrorHandler`
+- `createHtmlFunction`
+- `createHtmlTemplateFunction`
+- `createRenderFunction`
+- `createRoute`
+- `createRouteHandler`
+- `prepareClient`
 
 ## Renderer options
 
@@ -35,65 +43,28 @@ If unset, **`@fastify/vite`** will automatically try to resolve `index.js` from
 
 As soon as the client module is loaded, it is passed to the `prepareClient()` configuration function. 
 
-See its default definition [here](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L39). If it finds `routes` defined, **`@fastify/vite`** will use it to register an individual Fastify (server-level) route for each of your client-level routes (`VueRouter`, `ReactRouter` etc). That's why `prepareClient()` is implemented that way by default.
-
-See the [`react-hydration`](https://github.com/fastify/fastify-vite/tree/dev/examples/react-hydration) and [`vue-hydration`](https://github.com/fastify/fastify-vite/tree/dev/examples/vue-hydration) examples to see how the same `routes.js` file is used to set up ReactRouter and VueRouter, and the associated Fastify routes.
+See its default definition [here](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L39). If it finds `routes` defined, **`@fastify/vite`** will use it to register an individual Fastify (server-level) route for each of your client-level routes (**Vue Router**, **React Router** etc). That's why `prepareClient()` is implemented that way by default.
 
 ### `createRenderFunction`
 
 This configuration function creates the `reply.render()` method.
 
+It's covered in detail in **[Rendering function](/guide/rendering-function)**.
+
 ### `createHtmlFunction`
 
 This configuration function creates the `reply.html()` method.
 
-### `createRouteHandler`
-
-# `createRouteHandler(client, scope, options)`
-
-This configuration function creates the default **route handler** for registering Fastify routes based on the client module `routes` exported array (if available). See its [default definition](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L71) below:
+It's covered in detail in **[Templating function](/guide/rendering-function)**.
 
-```js
-function createRouteHandler (client, scope, options) {
-  return async function (req, reply) {
-    const page = await reply.render(scope, req, reply)
-    reply.html(page)
-  }
-}
-```
+### `createRouteHandler`
 
+This configuration function creates the default **route handler** for registering Fastify routes based on the client module `routes` exported array (if available).
 
 ### `createErrorHandler`
 
-This configuration function creates the default **error handler** for the Fastify routes registered based on the client module `routes` exported array (if available). See its [default definition](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L79) below:
-
-```js
-function createErrorHandler (client, scope, config) {
-  return (error, req, reply) => {
-    if (config.dev) {
-      console.error(error)
-      scope.vite.devServer.ssrFixStacktrace(error)
-    }
-    scope.errorHandler(error, req, reply)
-  }
-}
-```
-
+This configuration function creates the default **error handler** for the Fastify routes registered based on the client module `routes` exported array.
 
 ### `createRoute`
 
-# `createRoute({ handler, errorHandler, route }, scope, config)`
-
-Finally, this configuration function is responsible for actually registering an individual Fastify route for each of your client-level routes. See its [default definition](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L60) below:
-
-```js
-function createRoute ({ handler, errorHandler, route }, scope, config) {
-  scope.route({
-    url: route.path,
-    method: 'GET',
-    handler,
-    errorHandler,
-    ...route,
-  })
-}
-```
+this configuration function is responsible for actually registering an individual Fastify route for each of your client-level routes.
diff --git a/docs/config/react/virtual-modules.md b/docs/config/react/virtual-modules.md
@@ -1 +1,68 @@
-virtual-modules.md
+# Virtual Modules
+
+As covered in [Project Structure](/react/project-structure#smart-links), **`@fastify/react`** relies on [virtual modules](https://github.com/rollup/plugins/tree/master/packages/virtual) to save your project from having too many boilerplate files. Virtual modules used in **`@fastify/react`** are **fully ejectable**. For instance, the starter template relies on the `/:root.jsx` virtual module to provide the React component shell of your application. If you copy the `root.jsx` file [from the @fastify/react package](https://github.com/fastify/fastify-vite/blob/main/packages/fastify-react/virtual/root.jsx) and place it your Vite project root, **that copy of the file is used instead**.
+
+## `/:root.jsx`
+
+This is the root React component. It's used internally by `/:create.jsx` and provided as part of the starter template. You can use this file to add a common layout to all routes, or just use it to add additional, custom context providers.
+
+Note that a top-level `<Suspense>` wrapper is necessary because **`@fastify/react`** has code-splitting enabled at the route-level. You can opt out of code-splitting by providing your own `routes.js` file, but that's very unlikely to be ever required for any reason.
+
+#### Source from `packages/fastify-react/virtual/root.jsx`:
+
+<<< @../../packages/fastify-react/virtual/root.jsx
+
+## `/:routes.js`
+
+**`@fastify/react`** has **code-splitting** out of the box. It does that by eagerly loading all route data on the server, and then hydrating any missing metadata on the client. That's why the routes module default export is conditioned to `import.meta.env.SSR`, and different helper functions are called for each rendering environment.
+
+> React Router's [nested routes](https://reactrouter.com/docs/en/v6/getting-started/concepts#nested-routes) aren't supported yet.
+
+
+#### Source from `packages/fastify-react/virtual/routes.js`:
+
+<<< @../../packages/fastify-react/virtual/routes.js
+
+## `/:core.jsx`
+
+Implements `useRouteContext()`, `App` and `AppRoute`. 
+
+`App` is imported by `root.jsx` and encapsulates **`@fastify/react`**'s route component API.
+
+#### Source from `packages/fastify-react/virtual/core.jsx`:
+
+<<< @../../packages/fastify-react/virtual/core.jsx
+
+## `/:create.jsx`
+
+This virtual module creates your root React component. 
+
+This is where `root.jsx` is imported.
+
+#### Source from `packages/fastify-react/virtual/create.jsx`:
+
+<<< @../../packages/fastify-react/virtual/create.jsx
+
+## `/:layouts/default.js`
+
+This is used internally by `/:core.jsx`. If a project has no `layouts/default.jsx` file, the default one from **`@fastify/react`** is used.
+
+#### Source from `packages/fastify-react/virtual/layouts/default.jsx`:
+
+<<< @../../packages/fastify-react/virtual/layouts/default.jsx
+
+## `/:mount.js`
+
+This is the file `index.html` links to by default. It sets up the application with an `unihead` instance for head management, the initial route context, and provides the conditional mounting logic to defer to CSR-only if `clientOnly` is enabled.
+
+#### Source from `packages/fastify-react/virtual/mount.js`:
+
+<<< @../../packages/fastify-react/virtual/mount.js
+
+## `/:resource.js`
+
+Provides the `waitResource()` and `waitFetch()` data fetching helpers implementing the [Suspense API](https://17.reactjs.org/docs/concurrent-mode-suspense.html). They're used by `/:core.jsx`.
+
+#### Source from `packages/fastify-react/virtual/resource.js`:
+
+<<< @../../packages/fastify-react/virtual/resource.js