Hello world from React and fastify-vite!
\n )\n}\n```\n\nNext we have the **client entry point**, which is the code that **mounts** the React instance to the **server-side rendered HTML element**. It is aptly named `client/mount.js`:\n\n```js\nimport { hydrateRoot } from 'react-dom/client'\nimport { createApp } from './base.jsx'\n\nhydrateRoot(document.querySelector('main'), createApp())\n```\n\n> If we were to skip **server-side rendering** (also possible!) and go straight to client-side rendering, we'd use the [`createRoot()`](https://reactjs.org/docs/react-dom-client.html#createroot) function from `react-dom`, but in this case, since we expect React to find readily available markup delivered by the server, we use [`hydrateRoot()`](https://reactjs.org/docs/react-dom-client.html#hydrateroot).\n\nNow, let's see `client/index.js`:\n\n```js\nimport { createApp } from './base.jsx'\n\nexport default { createApp }\n```\n\nAll it does is make the `createApp()` function available to the server-side code. In order to create `reply.render()`, **`fastify-vite`** expects you to provide a `createRenderFunction()` function as a plugin option. This function receives as first parameter the default export from your client module (`client/index.js` above).\n\nNow the following snippet, `server.js`, will be easy to follow:\n\n```js\nimport Fastify from 'fastify'\nimport FastifyVite from 'fastify-vite'\nimport { renderToString } from 'react-dom/server'\n\nconst server = Fastify()\n\nawait server.register(FastifyVite, { \n root: import.meta.url, \n createRenderFunction ({ createApp }) {\n return () => {\n return {\n element: renderToString(createApp())\n }\n }\n }\n})\n\nawait server.vite.ready()\nawait server.listen({ port: 3000 })\n```\n\nYou can guess the `createApp` value collected from the first argument passed to `createRenderFunction()` is coming from `client/index.js`. It proceeds to use that to create a new instance of your app, in this case, the root React component, and pass it to `renderToString()` from `react-dom/server`.\n\nA string with a the server-side renderered HTML fragment for your React component is produced by `renderToString()`, and then returned in an object as `element`. The only thing left to do in this example is manually specifying a route to call `reply.render()` from, but we also need to call `reply.html()`:\n\n```js\nserver.get('/', (req, reply) => {\n reply.html(reply.render())\n})\n```\n\nThat's what's required to get a SSR function for your Vite-bundled application and send the generated markup through a route handler — but there's a big question left to answer: \n\nHow does that HTML fragment end up in `index.html`? \n\n### Creating reply.html(), the HTML rendering function\n\nLet's shift attention to `client/index.html` now:\n\n```html\n\n\n\n```\n\nAs per Vite's documentation, `index.html` is a special file made part of the module resolution graph. It's how Vite finds all the code that runs client-side. \n\nWhen you run the `vite build` command, `index.html` is what Vite automatically looks for. Given this special nature, you probably want to keep it as simple as possible, using HTML comments to specify content placeholders. That's the pattern used across the official SSR examples from [Vite's playground](https://github.com/vitejs/vite/tree/main/packages/playground).\n\nBefore we dive into `reply.html()`, you should know **`fastify-vite`** packs a helper function that turns an HTML document with placeholders indicated by comments into a precompiled templating function:\n\n```js\nimport { createHtmlTemplateFunction } from 'fastify-vite'\n\nconst template = createHtmlTemplateFunction('')\nconst html = template({ foobar: 'This will be inserted '})\n```\n\nBy default, that function is used internally by the `createHtmlFunction()` configuration option, which is responsible for returning the function that is decorated as `reply.html()`. \n\nHere's how `createHtmlFunction()` is defined by default:\n\n```js\nfunction createHtmlFunction (source, scope, config) {\n const indexHtmlTemplate = config.createHtmlTemplateFunction(source)\n return function (ctx) {\n this.type('text/html')\n this.send(indexHtmlTemplate(ctx))\n }\n}\n```\n\nYou can see that default definition (and many others) in **`fastify-vite`**'s [internal `config.js`](https://github.com/fastify/fastify-vite/blob/dev/packages/fastify-vite/config.js#L51) file. \n\nLooking at the default `createHtmlFunction()` above, you can probably guess how the [`react-vanilla`](https://github.com/fastify/fastify-vite/tree/dev/examples/react-vanilla) example works now. The result of `render()` is a simple object with variables to be passed to `reply.html()`, which uses the precompiled templating function based on `index.html`.\n\nIn some cases, it's very likely you'll want to provide your own `createHtmlFunction()` option through **`fastify-vite`**'s plugin options. For instance, the [`vue-streaming`](https://github.com/fastify/fastify-vite/tree/dev/examples/react-vanilla) example demonstrates a custom implementation that works with a stream instead of a raw string.\n\n## Deployment\n\nIf you try to run any of the [`examples/`](https://github.com/fastify/fastify-vite/tree/dev/examples) without the `--dev` flag, you'll be greeted with an error message:\n\n```\n% node server.js\n/../node_modules/fastify-vite/mode/production.js:6\n throw new Error('No distribution bundle found.')\n ^\n\nError: No distribution bundle found.\n```\n\nThis means you're trying to run **`fastify-vite`** in production mode, in which case a **distribution bundle** is assumed to exist. To build your client application code in preparation for **`fastify-vite`**, you must run two `vite build` commands, one for the actual client bundle, that gets delivered to the browser, and another for the server-side version of it (what **`fastify-vite`** sees as the *_client module_*, or *_server entry point_*).\n\nAssuming you're using the default `clientModule` resolution (`/index.js`), these are the `scripts` needed in `package.json`:\n\n```json\n\"build\": \"npm run build:client && npm run build:server\",\n\"build:client\": \"vite build --outDir dist/client --ssrManifest\",\n\"build:server\": \"vite build --outDir dist/server --ssr /index.js\",\n```\n\nAfter running `npm run build` on [`react-vanilla`](https://github.com/fastify/fastify-vite/tree/dev/examples/react-vanilla), for example, you should see a new `client/dist` folder.\n\n\n```diff\n ├── client\n+ │ ├── dist\n │ ├── base.jsx\n │ ├── index.html\n │ ├── index.js\n │ └── mount.js\n ├── package.json\n ├── server.js\n └── vite.config.js\n```\n\nThat's where the production bundle of your Vite application is located, so this folder needs to exist before you can run a Fastify server with **`fastify-vite`** in production mode.\n\nAlso note that in **production mode**, **`fastify-vite`** will serve static assets from your Vite application via [`@fastify/static`](https://github.com/fastify/fastify-static) automatically, but you should consider using a CDN for those files if you can, or just serve through Nginx instead of directly through Node.js. A detailed guide on how to set this up will be added soon.\n\n## Configuration\n\nThe essential configuration options are `root`, `dev` and `createRenderFunction()`. Following the conventions covered in the previous section, setting those is enough to get most simple apps working well. \n\nBut all steps of the setup can be configured isolatedly. \n\nBelow is a execution flow diagram of all configuration functions:\n\n```\n├─ prepareClient()\n│ ├─ createHtmlFunction()\n│ ├─ createRenderFunction()\n│ ├─ createRouteHandler()\n│ └─ createErrorHandler()\n└─ createRoute()\n```\n\n### `clientModule`\n\nIf unset, **`fastify-vite`** will automatically try to resolve `index.js` from your Vite project root as your client module. You can override this behavior by setting this option.\n\n### `prepareClient({ routes, ...others }, scope, config)`\n\nAs soon as the client module is loaded, it is passed to the `prepareClient()` configuration function. \n\nSee 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.\n\nSee 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.\n\n### `createHtmlFunction(source, scope, config)`\n\nAs covered previously, this is the function that creates the `reply.html()` method.\n\n### `createRenderFunction(clientModule, scope, config)`\n\nAs covered previously, this is the function that creates the `reply.render()` method.\n\n### `createRouteHandler(client, scope, options)`\n\nThis 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:\n\n```js\nfunction createRouteHandler (client, scope, options) {\n return async function (req, reply) {\n const page = await reply.render(scope, req, reply)\n reply.html(page)\n }\n}\n```\n\n### `createErrorHandler(client, scope, config)`\n\nThis 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:\n\n```js\nfunction createErrorHandler (client, scope, config) {\n return (error, req, reply) => {\n if (config.dev) {\n console.error(error)\n scope.vite.devServer.ssrFixStacktrace(error)\n }\n scope.errorHandler(error, req, reply)\n }\n}\n```\n\n### `createRoute({ handler, errorHandler, route }, scope, config)`\n\nFinally, 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:\n\n```js\nfunction createRoute ({ handler, errorHandler, route }, scope, config) {\n scope.route({\n url: route.path,\n method: 'GET',\n handler,\n errorHandler,\n ...route,\n })\n}\n```\n\n### `renderer`\n\nA single configuration object which can be used to set all of the settings above. \n\nYou can see it in the streaming [examples/](https://github.com/fastify/fastify-vite/tree/dev/examples).\n\n### `spa`\n\n**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.\n\nYou can see it in the streaming [examples/](https://github.com/fastify/fastify-vite/tree/dev/examples).\n\n## ⁂\n\nYou can consider **`fastify-vite`** a **microframework for building full stack frameworks**. \n\nWith configuration functions hooking into every step of the setup process, you can easily implement advanced automation for a number of scenarios.\n\nFor example, collecting a Next-like `getServerSideProps()` function from every route component and registering an associated payload API endpoint for every route through `createRoute()`. \n\nSee this **[blog post](https://hire.jonasgalvez.com.br/2022/may/18/building-a-mini-next-js/)** for a walkthrough doing just that.\n\n## Meta\n\nCreated by [Jonas Galvez](https://hire.jonasgalvez.com.br/), Principal Engineer on Open Source at [NodeSource](https://www.nodesource.com).\n\nThis project is sponsored by [NodeSource](https://www.nodesource.com), [NearForm](https://www.nearform.com) and maintained with the help of [these brilliant contributors](https://github.com/fastify/fastify-vite/graphs/contributors).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}