sync vue/react, starters

Author: galvez

docs/react/project-structure.md

@@ -99,13 +99,13 @@ The Vite application HTML template:
 <div id="root"><!-- element --></div>
 </body>
 <!-- hydration -->
-<script type="module" src="/:mount.js"></script>
+<script type="module" src="/$app/mount.js"></script>
 </html>
 ```
 
 It needs to have `head`, `element` and `hydration` placeholders.
 
-And it must import `/:mount.js` as the main module.
+And it must import `/$app/mount.js` as the main module.
 
 </td>
 </tr>
@@ -167,11 +167,11 @@ export default {
 }
 ```
 ```js [client/index.js]
-import routes from '/:routes.js'
-import create from '/:create.jsx'
+import routes from '$app/routes.js'
+import create from '$app/create.jsx'
 
 export default {
-  context: import('/:context.js'),
+  context: import('$app/context.js'),
   routes,
   create,
 }
@@ -188,7 +188,7 @@ export default {
 <div id="root"><!-- element --></div>
 </body>
 <!-- hydration -->
-<script type="module" src="/:mount.js"></script>
+<script type="module" src="/$app/mount.js"></script>
 </html>
 ```
 ```js [client/pages/index.jsx]
@@ -250,11 +250,11 @@ The core files of **`@fastify/react`** that make all of that (and a bit more) wo
 
 <div style="font-size: 1.2em !important">
 
-The way this works is via the `/:` prefix.
+The way this works is via the `$app/` prefix.
 
 </div>
 
-Notice how `client/index.html` imports the React application mounting script from `/:mount.js`, and `client/index.js` loads routes from `/:routes.js`, the application factory function from `/:create.jsx` and the [route context](/react/route-context) initialization module from `/:context.js`.
+Notice how `client/index.html` imports the React application mounting script from `$app/mount.js`, and `client/index.js` loads routes from `$app/routes.js`, the application factory function from `$app/create.jsx` and the [route context](/react/route-context) initialization module from `$app/context.js`.
 
 What this prefix does is **first check if the file exists** in your Vite project root directory, **and if not**, provide the **default versions** stored inside the `@fastify/react` package instead.
 
@@ -271,12 +271,12 @@ Below is a quick rundown of all smart imports available.
 <tr>
 <td>
 
-`/:core.js`
+`$app/core.js`
 
 </td>
 <td>
 
-This is used by `/:create.jsx` internally to create your React application instance, but it's also the location where to import the [`useRouteContext()`](/react/route-context) hook from.
+This is used by `$app/create.jsx` internally to create your React application instance.
 
 It also exports the `isServer` convenience flag.
 
@@ -285,7 +285,7 @@ It also exports the `isServer` convenience flag.
 <tr>
 <td>
 
-`/:create.jsx`
+`$app/create.jsx`
 
 </td>
 <td>
@@ -297,7 +297,7 @@ Where your React application factory function is exported from. It must be named
 <tr>
 <td>
 
-`/:mount.js`
+`$app/mount.js`
 
 </td>
 <td>
@@ -309,7 +309,7 @@ The Vite application mount script, imported by `index.html`.
 <tr>
 <td>
 
-`/:resource.js`
+`$app/resource.js`
 
 </td>
 <td>
@@ -321,7 +321,7 @@ Utilities to enable suspensed state in data fetching.
 <tr>
 <td>
 
-`/:root.jsx`
+`$app/root.jsx`
 
 </td>
 <td>
@@ -333,7 +333,7 @@ The main React component for your application.
 <tr>
 <td>
 
-`/:context.js`
+`$app/context.js`
 
 </td>
 <td>
@@ -345,7 +345,7 @@ The [route context](/react/route-context) initialization file.
 <tr>
 <td>
 
-`/:layouts/default.jsx`
+`$app/layouts/default.jsx`
 
 </td>
 <td>
@@ -363,15 +363,15 @@ The graph below indicates the relationships between them:
 
 ```mermaid
 flowchart TD
-    R("/:resource.js") --> A
-    V("/:root.jsx") --> B
-    A("/:core.jsx") --> B("/:create.jsx")
-    C("/:routes.js") --> D
+    R("$app/resource.js") --> A
+    V("$app/root.jsx") --> B
+    A("$app/core.jsx") --> B("$app/create.jsx")
+    C("$app/routes.js") --> D
     C --> E
-    B --> D("/:mount.js")
-    B --> E("/:index.js")
-    T("/:context.js") --> D
-    T("/:context.js") --> E
+    B --> D("$app/mount.js")
+    B --> E("$app/index.js")
+    T("$app/context.js") --> D
+    T("$app/context.js") --> E
     D --> CSR("Client-Side Rendering")
     E --> SSR("Server-Side Rendering")
 ```

docs/react/route-context.md

@@ -2,7 +2,7 @@
 
 # Route Context
 
-In **`@fastify/react`** applications, the **route context** is an object available in every [**route module**](/react/route-modules) and [**layout module**](/react/route-layouts). It is populated via the [**route context initialization module**](/react/route-context#init-module), and accessed via the `useRouteContext()` hook available from the `/:core.jsx` smart import — a default implementation is provided by **`@fastivy/react`** but you can extend or create your own by providing your own implementation of the `core.js` file.
+In **`@fastify/react`** applications, the **route context** is an object available in every [**route module**](/react/route-modules) and [**layout module**](/react/route-layouts). It is populated via the [**route context initialization module**](/react/route-context#init-module), and accessed via the `useRouteContext()` hook.
 
 This route context implementation is extremely simple and deliberately limited to essential features. Its goal is to be easy to understand, extend or completely modify if needed. Note that some aspects of this implementation are tightly coupled to the server. In **`@fastify/react`**'s source code, you can see the implementation of [`server/context.js`](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-react/server/context.js) and [its use in `createRoute()`](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-react/index.js) that first populates the route context object on the server and prepares it for hydration.
 
@@ -15,7 +15,7 @@ import FastifyReact from '@fastify/react'
 
 const server  = Fastify()
 await server.register(FastifyVite, {
-  root: import.meta.url,
+  root: import.meta.dirname,
   renderer: {
     ...FastifyReact,
     createRoute () {
@@ -86,7 +86,7 @@ export const actions = {
 ```jsx [client/pages/using-data.jsx]
 import { useState } from 'react'
 import { Link } from 'react-router'
-import { useRouteContext } from '/:core.jsx'
+import { useRouteContext } from '@fastify/react/client'
 
 export function getMeta () {
   return { title: 'Todo List — Using Data' }
@@ -135,7 +135,7 @@ export default function Index (props) {
 ```jsx [client/pages/using-store.jsx]
 import { useState } from 'react'
 import { Link } from 'react-router'
-import { useRouteContext } from '/:core.jsx'
+import { useRouteContext } from '@fastify/react/client'
 
 export function getMeta () {
   return { title: 'Todo List — Using Store' }
@@ -174,10 +174,12 @@ export default function Index (props) {
 
 ## Access hook
 
-As shown in the snippets above, the **route context** is accessed via the **`useRouteContext()`** hook, implemented in the `core.js` internal file and made available via `/:core.js` [smart import](/react/project-structure#smart-imports), which allows it to be shadowed by your own implementation in your project directory.
+As shown in the snippets above, the **route context** is accessed via the **`useRouteContext()`** hook, available via the `@fastfiy/react/client` module.
+
+> Contrary to all other [virtual modules](https://fastify-vite.dev/config/react/virtual-modules), which are available via the `$app` prefix, the `useRouteContext()` hook is provided by `@fastify/react/client`. This file is responsible for defining the route context, the Valtio state and also provides a couple of helpers. It's the only part of the setup you're encouraged to avoid changing. But in highly customized setups, you could still provide your own `useRouteContext()` from a local module.
 
 ```js
-import { useRouteContext } from '/:core.jsx'
+import { useRouteContext } from '@fastify/react/client'
 
 export default function Index (props) {
   const { ... } = useRouteContext()

docs/react/route-layouts.md

@@ -2,7 +2,7 @@
 
 `@fastify/react` will automatically load layouts from the `layouts/` folder.
 
-By default, the `/:layouts/default.jsx` [**smart import**](/react/project-structure#smart-imports) is used. If a project is missing `/layouts/default.jsx` file, the one provided by the virtual module is automatically used. **The default layout is defined as follows**:
+By default, the `$app/layouts/default.jsx` [**smart import**](/react/project-structure#smart-imports) is used. If a project is missing `/layouts/default.jsx` file, the one provided by the virtual module is automatically used. **The default layout is defined as follows**:
 
 ```jsx
 import { Suspense } from 'react'
@@ -26,7 +26,7 @@ That will cause the route to be wrapped in the layout component exported by a Re
 
 ```jsx
 import { Suspense } from 'react'
-import { useRouteContext } from '/:core.jsx'
+import { useRouteContext } from '@fastify/react/client'
 
 export default function Auth ({ children }) {
   const { actions, state, snapshot } = useRouteContext()

docs/react/route-modules.md

@@ -2,7 +2,7 @@
 
 # Route Modules
 
-Route modules are Vue components placed under the [route search path](/react/router-setup#routes-location), set to `<project-root>/pages` by default, or `client/pages` in the starter template, which follows the recommendation of using `client/` as the Vite project root.
+Route modules are React components placed under the [route search path](/react/router-setup#routes-location), set to `<project-root>/pages` by default, or `client/pages` in the starter template, which follows the recommendation of using `client/` as the Vite project root.
 
 Below is a rundown of supported exports:
 
@@ -22,7 +22,7 @@ Below is a rundown of supported exports:
 </td>
 <td>
 
-The Vue component.
+The React component.
 
 </td>
 </tr>
@@ -114,7 +114,7 @@ During client-side navigation (post first-render), a JSON request is fired to an
 The objet returned by `getData()` gets automatically assigned as `data` in the [universal route context](/react/route-context) object and is accessible from `getMeta()` and `onEnter()` functions and also via the `useRouteContext()` hook.
 
 ```jsx
-import { useRouteContext } from '/:core.jsx'
+import { useRouteContext } from '$app/core.jsx'
 
 export function getData (ctx) {
   return {
@@ -134,15 +134,80 @@ export default function Index (props) {
 
 > Under the hood, it uses the [`unihead`](https://github.com/galvez/unihead) library, which has a SSR function and a browser library that allows for dynamic changes during client-side navigation. This is a very small library built specifically for `@fastify/vite` core renderers, and used in the current implementation of `createHtmlFunction()` for `@fastify/react`. This may change in the future as other libraries are considered, but for most use cases it should be enough.
 
-To populate `<title>`, `<meta>` and `<link>` elements, export a `getMeta()` function that returns an object matching the interface expected by [unihead](https://github.com/galvez/unihead):
+To populate `<head>` elements, export a `getMeta()` function that returns an object matching the interface expected by [unhead](https://github.com/unjs/unhead):
 
 ```ts
-interface RouteMeta {
-  title?: string | null,
-  html?: Record<string, string> | null
-  body?: Record<string, string> | null
-  meta?: Record<string, string>[] | null,
-  link?: Record<string, string>[] | null,
+interface ReactiveHead {
+  /**
+   * The `<title>` HTML element defines the document's title that is shown in a browser's title bar or a page's tab.
+   * It only contains text; tags within the element are ignored.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
+   */
+  title?: ResolvableTitle;
+  /**
+   * Generate the title from a template.
+   */
+  titleTemplate?: ResolvableTitleTemplate;
+  /**
+   * Variables used to substitute in the title and meta content.
+   */
+  templateParams?: ResolvableProperties<{
+      separator?: '|' | '-' | '·' | string;
+  } & Record<string, Stringable | ResolvableProperties<Record<string, Stringable>>>>;
+  /**
+   * The `<base>` HTML element specifies the base URL to use for all relative URLs in a document.
+   * There can be only one <base> element in a document.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base
+   */
+  base?: ResolvableBase;
+  /**
+   * The `<link>` HTML element specifies relationships between the current document and an external resource.
+   * This element is most commonly used to link to stylesheets, but is also used to establish site icons
+   * (both "favicon" style icons and icons for the home screen and apps on mobile devices) among other things.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#attr-as
+   */
+  link?: ResolvableArray<ResolvableLink>;
+  /**
+   * The `<meta>` element represents metadata that cannot be expressed in other HTML elements, like `<link>` or `<script>`.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
+   */
+  meta?: ResolvableArray<ResolvableMeta>;
+  /**
+   * The `<style>` HTML element contains style information for a document, or part of a document.
+   * It contains CSS, which is applied to the contents of the document containing the `<style>` element.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style
+   */
+  style?: ResolvableArray<(ResolvableStyle | string)>;
+  /**
+   * The `<script>` HTML element is used to embed executable code or data; this is typically used to embed or refer to JavaScript code.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script
+   */
+  script?: ResolvableArray<(ResolvableScript | string)>;
+  /**
+   * The `<noscript>` HTML element defines a section of HTML to be inserted if a script type on the page is unsupported
+   * or if scripting is currently turned off in the browser.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/noscript
+   */
+  noscript?: ResolvableArray<(ResolvableNoscript | string)>;
+  /**
+   * Attributes for the `<html>` HTML element.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html
+   */
+  htmlAttrs?: ResolvableHtmlAttributes;
+  /**
+   * Attributes for the `<body>` HTML element.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body
+   */
+  bodyAttrs?: ResolvableBodyAttributes;
 }
 ```
 
@@ -163,7 +228,7 @@ export function getMeta (ctx) {
   return {
     title: ctx.data.page.title,
     meta: [
-      { name: 'twitter:title', value: ctx.data.page.title },
+      { name: 'twitter:title', content: ctx.data.page.title },
     ]
   }
 }

docs/react/router-setup.md

@@ -4,7 +4,7 @@
 
 By default, routes are loaded from the `<project-root>/pages` folder, where `<project-root>` refers to the `root` setting in your Vite configuration file.
 
-The route paths are **dynamically inferred from the directory structure**, very much like **Next.js**, and passed to the **React Router** instance in `/:create.js`
+The route paths are **dynamically inferred from the directory structure**, very much like **Next.js**, and passed to the **React Router** instance in `$app/create.js`
 
 Alternatively, you can also export a `path` constant from your route modules, in which case it will be used to **override the dynamically inferred paths**: