63 | |
64 |
65 | ### An hypothetical React component
66 |
67 | For a React route component running in an hypothetical framework that implements this specification, here's what it might look like.
68 |
69 | At the top, we enable `stream` to determine that this route should be server-side rendered in streaming mode.
70 |
71 | Then the `getData()` function, which should run both in SSR and CSR route navigation. It is assumed this function received a **route context object**, and in this case, a generic `route` object is also provided by the framework to identify the current route.
72 |
73 | The `getMeta()` function runs after `getData()` and has access to the data returned by it via the `data` property. It's used to define the `` of the page and other page-level tags. Finally the route component function is executed, which in this case, has a data property prepopulated by the underlying hypothetical framework.
74 |
75 | </td>
76 | <td width="600px"><br>
77 |
78 | ```jsx
79 | export const streaming = true
80 |
81 | export async function getData ({ route, loadPageData }) {
82 | const pageData = await loadPageData(route)
83 | return pageData
84 | }
85 |
86 | export async function getMeta ({ data }) {
87 | return {
88 | html: { lang: data.lang },
89 | title: data.title,
90 | meta: [
91 | { name: 'twitter:title', value: data.title }
92 | ]
93 | }
94 | }
95 |
96 | export default function Route ({ data }) {
97 | return (
98 | <>
99 | <h1>{data.title}</h1>
100 | <p>{data.body}</p>
101 | </>
102 | )
103 | }
104 | ```
105 |
106 | </td>
107 | </tr>
108 | </table>
109 |
110 | ## Route Context Object
111 |
112 | <table>
113 | <tr>
114 | <td width="400px" valign="top">
115 |
116 | ### `context`
117 |
118 | In the case of **named function exports**, a `context` object must be passed to the function, providing universal access to route information, data and methods. See the TypeScript interface to the right for a minimal implementation.
119 |
120 | If the route context contains a `data` object, it must be made available during SSR (seamlessly hydrated on first-render) and CSR.
121 |
122 | It may contain references to the Request and Response objects following the convention and semantics of the underlying server used. In the case of Fastify, those would be `req` and `reply`.
123 |
124 | </td>
125 | <td width="600px"><br>
126 |
127 | It must implement at least the following TypeScript interface:
128 |
129 | ```ts
130 | interface RouteContext {
131 | readonly url: string
132 | readonly static: boolean
133 | readonly server: boolean
134 | readonly client: boolean
135 | fetch: () => Promise<Response>
136 | reload: () => Promise<Response>
137 | meta?: RouteMeta
138 | data?: any
139 | }
140 | ```
141 |
142 | </td>
143 | </tr>
144 | </table>
145 |
146 | ## Named Exports: Rendering Options
147 |
148 | By default, route modules **should** run universally, both on the server and on the client (with client-side hydration), but it **should** be possible specify different rendering modes or settings for a route module.
149 |
150 | <table>
151 | <tr>
152 | <td width="400px" valign="top">
153 |
154 | ### `streaming`
155 |
156 | Determines if **server-side rendering** should take place in **streaming mode** if the underlying framework supports it.
157 |
158 | </td>
159 | <td width="600px"><br>
160 |
161 | It must be set with a `boolean`:
162 |
163 | ```js
164 | export const streaming = true
165 | ```
166 |
167 | </td>
168 | </tr>
169 | </table>
170 |
171 | <table>
172 | <tr>
173 | <td width="400px" valign="top">
174 |
175 | ### `serverOnly`
176 |
177 | Determines that the component must only run on the server and no JavaScript code should run on the client, i.e., the client should receive the **static markup** produced by running the component on the server, making it effectively [SSR](https://web.dev/rendering-on-the-web/#server-rendering)-only).
178 |
179 | </td>
180 | <td width="600px"><br>
181 |
182 | It must be either set with a `boolean`:
183 |
184 | ```js
185 | export const serverOnly = true
186 | ```
187 |
188 | Or with a function that returns a `boolean`:
189 |
190 | ```js
191 | export function serverOnly (context) {
192 | return context.shouldRunOnlyOnTheServer
193 | }
194 | ```
195 |
196 | </td>
197 | </tr>
198 | </table>
199 |
200 | <table>
201 | <tr>
202 | <td width="400px" valign="top">
203 |
204 | ### `clientOnly`
205 |
206 | Determines that the component must only run on the client and no **server-side rendering** is to take splace, i.e., the client should perform rendering entirely on its own ([CSR](https://web.dev/rendering-on-the-web/#client-side-rendering-(csr))-only). It may either be a `boolean` or a function that returns a `boolean`.
207 |
208 | </td>
209 | <td width="600px"><br>
210 |
211 | It must be either set with a `boolean`:
212 |
213 | ```js
214 | export const clientOnly = true
215 | ```
216 |
217 | Or with a function that returns a `boolean`:
218 |
219 | ```js
220 | export function clientOnly (context) {
221 | return context.shouldRunOnlyOnTheClient
222 | }
223 | ```
224 |
225 | </td>
226 | </tr>
227 | </table>
228 |
229 | ## Named Exports: Route Navigation and Hydration
230 |
231 | <table>
232 | <tr>
233 | <td width="400px" valign="top">
234 |
235 | ## `onEnter()`
236 |
237 | Determines the universal **route handler** for the component. It must be implemented in way that it can run both on the server prior to **server-side rendering** and on the client prior to **client-side route navigation** (via **History API**).
238 |
239 | It **must** receive a route context object that **should** receive server request and response references during SSR and a client-side router reference during CSR, or hybrid APIs that can work in both environments.
240 |
241 | </td>
242 | <td width="600px"><br>
243 |
244 | ```js
245 | export async function onEnter ({ reply, isServer }) {
246 | if (isServer) {
247 | // This runs on the server where you have access,
248 | // for instance, to the Fastify Reply object
249 | reply.header('X-Custom-Header', 'value')
250 | } else {
251 | console.log('This should only appear in the browser')
252 | }
253 | }
254 | ```
255 |
256 | > This function could be used to reimplement `useAsyncData()` in Nuxt.js and `action()` in Remix.js.
257 |
258 | </td>
259 | </tr>
260 | </table>
261 |
262 | <table>
263 | <tr>
264 | <td width="400px" valign="top">
265 |
266 | ## `getData()`
267 |
268 | Determines the **server data function** for the route. It must be implemented in way that it can run both on the server prior to **server-side rendering** and **through an endpoint that can be fetched** prior to **client-side route navigation**. This function is expected to return an object, whose properties should be merged into the passed route context under a `data` property, which should be also seamlessly hydrated on first-render if populated during SSR. In the case of **static generation**, its return value should be embedded within each page as an inline `<script>`.
269 |
270 | </td>
271 | <td width="600px"><br>
272 |
273 | ```js
274 | export async function getData (context) {
275 | const url = context.req
276 | const data = await context.dataReturningFunction()
277 | return { data }
278 | }
279 | ```
280 |
281 | > This function could be used to reimplement `gerServerSideProps()` in Next.js, `load()` in SvelteKit and `loader()` in Remix.
282 |
283 | </td>
284 | </tr>
285 | </table>
286 |
287 | ## Named Exports: Page Metadata
288 |
289 | This specification recommends that `<head>` serialization (and other page-level tags) take place indepedently from SSR, for optimal performance and opening the possibility of delivering an application shell for CSR-only rendering. SSR may still yield additional `<link>` preload tags for dynamic component assets, but that should happen isolatedly from the main page metadata so the ability to stream it right away to the client is preserved.
290 |
291 | <table width="100%">
292 | <tr>
293 | <td width="400px" valign="top">
294 |
295 | ## `getMeta()`
296 |
297 | Determines HTML tags such as `<title>`, `<meta>` and `<link>`, as well as `<html>` and `<body>` tag attributes. It must be set either with an object or a function that returns an object described by the `RouteMeta` interface.
298 |
299 | </td>
300 | <td width="600px"><br>
301 |
302 | ```js
303 | export async function getMeta (context) {
304 | const title = context.post.title
305 | return {
306 | title: 'Page title',
307 | html: { lang: 'en' },
308 | meta: [
309 | { name: 'twitter:title', content: title }
310 | ]
311 | }
312 | }
313 | ```
314 |
315 | </td>
316 | </tr>
317 | </table>
318 |
319 |
320 | ## Acknowledgements
321 |
322 | Special thanks to my employeer, [NearForm](https://nearform.com), for sponsoring this project, and [Matteo Collina](https://github.com/mcollina) and [Simone Busoli](https://github.com/simoneb) for their honest feedback and guidance. Also a big shout out to [Sébastien Chopin](https://github.com/Atinux), [Pooya Parsa](https://github.com/pi0) and [Xin Du](https://github.com/clarkdo) from Nuxt.js — who I learned a lot from.
323 |
324 | This specification owes a lot to [Ryan Florence](https://github.com/ryanflorence) and [Michael Jackson](https://github.com/mjackson) for their time spent designing Remix and coming up with an excellent Route Module API for their framework. [Guillermo Rauch](https://github.com/rauchg) and [Tim Neutkens](https://github.com/timneutkens) also need to be ackowledged for their work in Next.js which helped shape up a lot of the developer experience we've come to expect from modern frameworks.
325 |
--------------------------------------------------------------------------------
/packages/fastify-svelte/README.md:
--------------------------------------------------------------------------------
1 | <br>
2 |
3 | # @fastify/svelte [](https://www.npmjs.com/package/@fastify/svelte) [](https://standardjs.com/)
4 |
5 | **Fastify DX for Svelte** (**`@fastify/svelte`**) is a renderer for [**@fastify/vite**](https://github.com/fastify/fastify-vite).
6 |
7 | It lets you run and SSR (server-side render) **Svelte applications built with Vite** on [Fastify](https://fastify.io/), with a minimal and transparent **server-first approach** — everything starts with `server.js`, your actual Fastify server).
8 |
9 | It has an extremely small core (~1k LOC total) and is built on top of [Fastify](https://github.com/fastify/fastify), [Vite](https://vitejs.dev/), [Valtio](https://github.com/pmndrs/valtio) and [Svelte Navigator](https://github.com/EmilTholin/svelte-navigator).
10 |
11 | ## Quick Start
12 |
13 | Ensure you have **Node v16+**.
14 |
15 | Make a copy of [**starters/svelte**](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte). If you have [`degit`](https://github.com/Rich-Harris/degit), run the following from a new directory:
16 |
17 | ```bash
18 | degit fastify/fastify-dx/starters/svelte
19 | ```
20 |
21 | > **If you're starting a project from scratch**, you'll need these packages installed.
22 | >
23 | > ```bash
24 | > npm i fastify fastify-vite fastify-dx-svelte -P
25 | > npm i @sveltejs/vite-plugin-svelte -D
26 | > ```
27 |
28 |
29 | Run `npm install`.
30 |
31 | Run `npm run dev`.
32 |
33 | Visit `http://localhost:3000/`.
34 |
35 | ## What's Included
36 |
37 | That will get you a **starter template** with:
38 |
39 | - A minimal [Fastify](https://github.com/fastify/fastify) server.
40 | - Some dummy API routes.
41 | - A `pages/` folder with some [demo routes](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte/client/pages).
42 | - All configuration files.
43 |
44 | It also includes some _**opinionated**_ essentials:
45 |
46 | - [**PostCSS Preset Env**](https://www.npmjs.com/package/postcss-preset-env) by [**Jonathan Neal**](https://github.com/jonathantneal), which enables [several modern CSS features](https://preset-env.cssdb.org/), such as [**CSS Nesting**](https://www.w3.org/TR/css-nesting-1/).
47 |
48 | - [**UnoCSS**](https://github.com/unocss/unocss) by [**Anthony Fu**](https://antfu.me/), which supports all [Tailwind utilities](https://uno.antfu.me/) and many other goodies through its [default preset](https://github.com/unocss/unocss/tree/main/packages/preset-uno).
49 |
50 | - [**Valtio**](https://github.com/pmndrs/valtio) by [**Daishi Kato**](https://blog.axlight.com/), with a global and SSR-ready store which you can use anywhere. <br>Svelte support is provided via [Sveltio](https://github.com/wobsoriano/sveltio) by [Robert Soriano](https://robsoriano.com/).
51 |
52 |
53 | ## Package Scripts
54 |
55 | - `npm run dev` boots the development server.
56 | - `npm run build` creates the production bundle.
57 | - `npm run serve` serves the production bundle.
58 |
59 |
60 | ## Basic setup
61 |
62 | The [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte) follows [fastify-vite](https://github.com/fastify/fastify-vite)'s convention of having a `client` folder with an `index.js` file, which is automatically resolved as your `clientModule` setting.
63 |
64 | If you want flat directory setup, where server and client files are mixed together, you can manually set `clientModule` to something else. Note that in this case you'll also need to update `root` in your `vite.config.js` file.
65 |
66 | When deploying to production, bear in mind the `client/dist` directory, generated when you run `npm run build`, needs to be included. You'll also want to enable Fastify's [built-in logging](https://www.fastify.io/docs/latest/Reference/Logging/):
67 |
68 | ```js
69 | const server = Fastify({ logger: true })
70 | ```
71 |
72 | The starter template's `server.js` file:
73 |
74 | ```js
75 | import Fastify from 'fastify'
76 | import FastifyVite from 'fastify-vite'
77 | import FastifyDXSvelte from 'fastify-dx-svelte'
78 |
79 | const server = Fastify()
80 |
81 | await server.register(FastifyVite, {
82 | root: import.meta.url,
83 | renderer: FastifyDXSvelte,
84 | })
85 |
86 | await server.vite.ready()
87 | await server.listen(3000)
88 | ```
89 |
90 | The starter template's [`vite.config.js`](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/vite.config.js) file:
91 |
92 | ```js
93 | import { join, dirname } from 'path'
94 | import { fileURLToPath } from 'url'
95 |
96 | import { svelte as viteSvelte } from '@sveltejs/vite-plugin-svelte'
97 | import viteSvelteFastifyDX from 'fastify-dx-svelte/plugin'
98 | import unocss from 'unocss/vite'
99 | import { extractorSvelte } from '@unocss/core'
100 |
101 | const path = fileURLToPath(import.meta.url)
102 |
103 | const root = join(dirname(path), 'client')
104 | const plugins = [
105 | unocss({ extractors: [extractorSvelte] }),
106 | viteSvelte({
107 | compilerOptions: {
108 | hydratable: true,
109 | }
110 | }),
111 | viteSvelteFastifyDX(),
112 | ]
113 |
114 | export default { root, plugins }
115 | ```
116 |
117 | Note that you only need to use Fastify DX's Vite plugin, which includes all functionality from [fastify-vite](https://github.com/fastify/fastify-vite)'s Vite plugin.
118 |
119 | </td>
120 | </tr>
121 | </table>
122 |
123 | ### Route exports
124 |
125 | Fastify DX picks up exports from route modules to determine route behavior and functionality, as per the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md).
126 |
127 | To add those exports, you must use `<script context="module">` (Svelte-specific syntax) which determines the script that runs in the general module namespace for a Svelte component. So in Fastify DX Svelte applications, it's commonplace to have two code blocks, a regular one and another with `context` set to `module`:
128 |
129 | ```html
130 | <script context="module">
131 | export function getData () {
132 | return { message: 'Hello from getData!' }
133 | }
134 | <script>
135 |
136 | <script>
137 | import { useRouteContext } = '/dx:core.js'
138 | const { data } = useRouteContext()
139 | </script>
140 |
141 | <p>{data.message}</p>
142 | ```
143 |
144 |
145 | ## Project Structure
146 |
147 | The [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte) looks like this:
148 |
149 | ```
150 | ├── server.js
151 | ├── client/
152 | │ ├── index.js
153 | │ ├── context.js
154 | │ ├── root.svelte
155 | │ ├── index.html
156 | │ ├── layouts/
157 | │ │ ├── default.svelte
158 | │ │ └── auth.svelte
159 | │ └── pages/
160 | │ ├── index.svelte
161 | │ ├── client-only.svelte
162 | │ ├── server-only.svelte
163 | │ ├── using-data.svelte
164 | │ └── using-store.svelte
165 | ├── vite.config.js
166 | └── package.json
167 | ```
168 |
169 | Several internal files are provided as virtual modules by Fastify DX. They are located inside the `fastify-dx-svelte` package in `node_modules`, and dynamically loaded so you don't have to worry about them unless you want them overriden.
170 |
171 | In this case, placing a file with the same name as the registered virtual module in your Vite project root will override it. Find the detailed rundown of all virtual modules [here][virtual-modules].
172 |
173 | [virtual-modules]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/virtual-modules.md
174 |
175 | The `server.js` file is your application entry point. It's the file that runs everything. It boots a Fastify server configured with [**fastify-vite**](https://github.com/fastify/fastify-vite) and **Fastify DX for Svelte** as a renderer adapter to **fastify-vite**.
176 |
177 | The `client/index.js` file is your Vite server entry point, it's the file that provides your client bundle (which runs in the Vite-enriched environment) to the Node.js environment where Fastify runs.
178 |
179 | > Right now, it's mostly a **boilerplate file** because it must exist but it will also probably never need to be changed.
180 |
181 | It exports your application's factory function (must be named `create`), the application routes (must be named `routes`) and the universal route context [initialization module](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md#initialization-module) (must be named `context` and have a dynamic module import so Fastify DX can pick up `default` and named exports).
182 |
183 | The `client/index.html` file is the [root HTML template of the application](https://vitejs.dev/guide/#index-html-and-project-root), which Vite uses as the client bundling entry point.
184 |
185 | > You can expand this file with additional `<meta>` and `<link>` tags if you wish, provided you don't remove any of the placeholders.
186 |
187 | This files links to `/dx:mount.js`, which is a virtual module provided by Fastify DX.
188 |
189 | Virtual modules are covered [here][virtual-modules].
190 |
191 | The `client/pages/` directory contains your route modules, whose paths are dynamically inferred from the directory structure itself. You can change this behavior easily. More on this [here][routing-config].
192 |
193 | [routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/routing-config.md
194 |
195 | The `client/layouts/` directory contains your route layout modules, which can be associated to any route. By default, `layouts/default.svelte` is used, but if you don't need to do any modifications on that file, you can safely removed as it's provided by Fastify DX in that case. The starter template also comes with `layouts/auth.svelte`, to demonstrate a more advanced use of layouts.
196 |
197 | [routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/routing-config.md
198 |
199 | The `client/context.js` file is the universal [route context][route-context] initialization module. Any named exports from this file are attached to the `RouteContext` class prototype on the server, preventing them from being reassigned on every request. The `default` export from this file, however, runs for every request so you can attach any request-specific data to it.
200 |
201 | [route-context]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md
202 |
203 | # Rendering modes
204 |
205 | Following the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), Fastify DX's route modules can be set for universal rendering (SSR + CSR hydration, the default behavior), SSR in streaming mode, SSR only (client gets no JavaScript) or CSR only (SSR fully disabled). Fastify DX for Svelte supports all of these modes minus streaming, which is currently not yet supported by Svelte itself.
206 |
207 | ## `serverOnly`
208 |
209 | If a route module exports `serverOnly` set to `true`, only SSR will take place. The client gets the server-side rendered markup without any accompanying JavaScript or data hydration.
210 |
211 | You should use this setting to deliver lighter pages when there's no need to run any code on them, such as statically generated content sites.
212 |
213 | ```html
214 | <script context="module">
215 | export const serverOnly = true
216 | </script>
217 |
218 | <p>This route is rendered on the server only!</p>
219 | ```
220 |
221 | [This example](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/client/pages/server-only.svelte) is part of the [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte).
222 |
223 | ## `clientOnly`
224 |
225 | If a route module exports `clientOnly` set to `true`, no SSR will take place, only data fetching and data hydration. The client gets the empty container element (the one that wraps `<!-- element -->` in `index.html`) and all rendering takes place on the client only.
226 |
227 | You can use this setting to save server resources on internal pages where SSR makes no significant diference for search engines or UX in general, such as a password-protected admin section.
228 |
229 | ```html
230 | <script context="module">
231 | export const clientOnly = true
232 | </script>
233 |
234 | <p>This route is rendered on the client only!</p>
235 | ```
236 |
237 | [This example](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/client/pages/client-only.svelte) is part of the [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte).
238 |
239 | ## Routing Configuration
240 |
241 | By default, routes are loaded from the `<project-root>/pages` folder, where `<project-root>` refers to the `root` setting in `vite.config.js`. The route paths are **dynamically inferred from the directory structure**, very much like Next.js and Nuxt.js.
242 |
243 | ### Dynamic parameters
244 |
245 | Dynamic route parameters follow the [Next.js convention](https://nextjs.org/docs/basic-features/pages#pages-with-dynamic-routes) (`[param]`), but that can be overriden by using the `paramPattern` plugin option. For example, this configuration switches the param pattern to the [Remix convention](https://remix.run/docs/en/v1/guides/routing#dynamic-segments) (`$param`).
246 |
247 | ```js
248 | // ...
249 | const plugins = [
250 | // ...
251 | viteSvelteFastifyDX({ paramPattern: /\$(\w+)/ }),
252 | ]
253 | ```
254 |
255 | ### Routes location
256 |
257 | You can also change the glob pattern used to determine where to route modules from.
258 |
259 | Since this setting is passed to [Vite's glob importers](https://vitejs.dev/guide/features.html#glob-import), the value needs to be a string:
260 |
261 | ```js
262 | // ...
263 | const plugins = [
264 | // ...
265 | viteSvelteFastifyDX({ globPattern: '/views/**/*.svelte' }),
266 | ]
267 | ```
268 |
269 | ### View modules
270 |
271 | You also can export a `path` constant from your route modules, in which case its value will be used to **override the dynamically inferred paths from the directory structure**.
272 |
273 | Additionally, [**you can provide your own routes**](https://github.com/fastify/fastify-dx/tree/dev/packages/fastify-dx-svelte#dxroutesjs).
274 |
275 | ```html
276 | <script context="module">
277 | export const path = '/my-page'
278 | </script>
279 |
280 | <p>Route with path export</p>
281 | ```
282 |
283 | ## Isomorphic data prefetching
284 |
285 | Fastify DX for Svelte implements the `getData()` hook from the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md) to solve this problem.
286 |
287 | ### `getData(ctx)`
288 |
289 | This hook is set up in a way that it runs server-side before any SSR takes place, so any data fetched is made available to the route component before it starts rendering. During first render, any data retrieved on the server is automatically sent to be hydrated on the client so no new requests are made. Then, during client-side navigation (post first-render), a JSON request is fired to an endpoint automatically registered for running the `getData()` function for that route on the server.
290 |
291 | The objet returned by `getData()` gets automatically assigned as `data` in the [universal route context](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md) object and is accessible from `getMeta()` and `onEnter()` hooks and also via the `useRouteContext()` hook.
292 |
293 | ```html
294 | <script context="module">
295 | export function getData (ctx) {
296 | return {
297 | message: 'Hello from getData!',
298 | }
299 | }
300 | </script>
301 |
302 | <script>
303 | import { useRouteContext } from '/dx:core.js'
304 | const { data } = useRouteContext()
305 | </script>
306 |
307 | <p>{data.message}</p>
308 | ```
309 |
310 | ## Route Context
311 |
312 | ### Initialization module
313 |
314 | The starter template includes a sample `context.js` file. This file is optional and can be safely removed. If it's present, Fastify DX automatically loads it and uses it to do any RouteContext extensions or data injections you might need. If you're familiar with [Nuxt.js](https://nuxtjs.org/), you can think of it as a [Nuxt.js plugin](https://nuxtjs.org/docs/directory-structure/plugins/).
315 |
316 | **Consuming the route context:**
317 |
318 | ```js
319 | import {
320 | useRouteContext
321 | } from '/dx:core.js'
322 |
323 | // ...
324 | const {
325 | state,
326 | actions
327 | } = useRouteContext()
328 |
329 | // ...
330 | actions.addTodoItem(state, value)
331 | ```
332 |
333 | See the [full example](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/client/pages/using-store.vue) in the starter template.
334 |
335 | This example demonstrates how to use it to set up an universally available (SSR and CSR) `$fetch` function (using [`ky-universal`](https://www.npmjs.com/package/ky-universal)) and also export some store actions. They're all made available by `useRouteContext()`, covered next.
336 |
337 | ```js
338 | import ky from 'ky-universal'
339 |
340 | export default (ctx) => {
341 | if (ctx.server) {
342 | // Populate state.todoList on the server
343 | ctx.state.todoList = ctx.server.db.todoList
344 | // It'll get automatically serialized to the client on first render!
345 | }
346 | }
347 |
348 | export const $fetch = ky.extend({
349 | prefixUrl: 'http://localhost:3000'
350 | })
351 |
352 | // Must be a function so each request can have its own state
353 | export const state = () => ({
354 | todoList: null,
355 | })
356 |
357 | export const actions = {
358 | async addTodoItem (state, item) {
359 | await $fetch.put('api/todo/items', {
360 | json: { item },
361 | })
362 | state.todoList.push(item)
363 | },
364 | }
365 | ```
366 |
367 | See the [full example](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/client/context.js) in the starter template.
368 |
369 | ### The `useRouteContext()` hook
370 |
371 | This hook can be used in any Vue component to retrieve a reference to the current route context. It's modelled after the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), with still some rough differences and missing properties in this **alpha release**.
372 |
373 | By default, It includes reference to `data` — which is automatically populated if you use the `getData()` function, and `state` which hold references to the global [`reactive()`](https://vuejs.org/api/reactivity-core.html#reactive) object.
374 |
375 | It automatically causes the component to be suspended if the `getData()`, `getMeta()` and `onEnter()` functions are asynchronous.
376 |
377 | ```html
378 | <script>
379 | import { useRouteContext } from '/dx:core.js'
380 | const { data } = useRouteContext()
381 | </script>
382 |
383 | <p>{data.message}</p>
384 | ```
385 |
386 | ### Execution order
387 |
388 | This graph illustrates the execution order to expect from route context initialization.
389 |
390 | ```
391 | context.js default function export
392 | └─ getData() function export
393 | └─ getMeta() function export
394 | └─ onEnter() function export
395 | └─ Route module
396 | ```
397 |
398 | First the `default` function export from `context.js` (if present) is executed. This is where you can manually feed global server data into your application by populating the global state (the route context's `state` property, which is automatically hydrated on the client.
399 |
400 | Then `getData()` runs — which populates the route context's `data` property, and is also automatically hydrated on the client. Then `getMeta()`, which populates the route context's `head` property. Then `onEnter()`, and finally your route component.
401 |
402 |
403 | ## Universal Route Enter Event
404 |
405 | ### `onEnter(ctx)`
406 |
407 | If a route module exports a `onEnter()` function, it's executed before the route renders, both in SSR and client-side navigation. That is, the first time a route render on the server, onEnter() runs on the server. Then, since it already ran on the server, it doesn't run again on the client for that first route. But if you navigate to another route on the client using `<Link>`, it runs normally as you'd expect.
408 |
409 | It receives the [universal route context][route-context] as first parameter, so you can make changes to `data`, `meta` and `state` if needed.
410 |
411 | [route-context]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md
412 |
413 | ```html
414 | <script context="module">
415 | export function onEnter (ctx) {
416 | if (ctx.server?.underPressure) {
417 | ctx.clientOnly = true
418 | }
419 | }
420 | </script>
421 |
422 | <p>No pre-rendered HTML sent to the browser.</p>
423 | ```
424 |
425 | The example demonstrates how to turn off SSR and downgrade to CSR-only, assuming you have a `pressureHandler` configured in [`underpressure`](https://github.com/fastify/under-pressure) to set a `underPressure` flag on your server instance.
426 |
427 |
428 | ## Route Layouts
429 |
430 | Fastify DX will automatically load layouts from the `layouts/` folder. By default, `/dx:layouts/default.svelte` is used — that is, if a project is missing a `layouts/defaults.svelte` file, the one provided by Fastify DX is used instead.
431 |
432 | See the section on [Virtual Modules](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/virtual-modules.md) to learn more about this.
433 |
434 | You assign a layout to a route by exporting `layout`.
435 |
436 | See [`pages/using-auth.svelte`](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/pages/using-auth.svelte) in the starter template:
437 |
438 | ```js
439 | export const layout = 'auth'
440 | ```
441 |
442 | That'll will cause the route to be wrapped in the layout component exported by [`layouts/auth.svelte`](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/layouts/auth.svelte):
443 |
444 | ```html
445 | <script>
446 | import { useRouteContext } from '/dx:core.js'
447 | const { snapshot, actions, state } = useRouteContext()
448 | </script>
449 |
450 | <div class="contents">
451 | {#if !$snapshot.user.authenticated}
452 | <p>This route needs authentication.</p>
453 | <button on:click={() => actions.authenticate(state)}>
454 | Click this button to authenticate.
455 | </button>
456 | {:else}
457 | <slot />
458 | {/if}
459 | </div>
460 | ```
461 |
462 | Note that like routes, it has access to `useRouteContext()`.
463 |
464 |
465 | ## Meta Tags
466 |
467 | Following the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), Fastify DX renders `<head>` elements independently from the SSR phase. This allows you to fetch data for populating the first `<meta>` tags and stream them right away to the client, and only then perform SSR.
468 |
469 | > Additional `<link>` preload tags can be produced from the SSR phase. This is **not currently implemented** in this **alpha release** but is a planned feature. If you can't wait for it, you can roll out your own (and perhaps contribute your solution) by providing your own [`createHtmlFunction()`](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/index.js#L57) to [fastify-vite](https://github.com/fastify/fastify-vite).
470 |
471 | ### `getMeta()`
472 |
473 | To populate `<title>`, `<meta>` and `<link>` elements, export a `getMeta()` function that returns an object matching the format expected by [unihead](https://github.com/galvez/unihead), the underlying library used by Fastify DX.
474 |
475 | It receives the [route context](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md#route-context) as first parameter and runs after `getData()`, allowing you to access any `data` populated by these other functions to generate your tags.
476 |
477 | ```html
478 | <script context="module">
479 | export function getMeta (ctx) {
480 | return {
481 | title: 'Route Title',
482 | meta: [
483 | { name: 'twitter:title', value: 'Route Title' },
484 | ]
485 | }
486 | }
487 | </script>
488 |
489 | <p>Route with meta tags.</p>
490 | ```
491 |
492 |
493 | ## Virtual Modules
494 |
495 | **Fastify DX** 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 are a [Rollup](https://rollupjs.org/guide/en/) feature exposed and fully supported by [Vite](https://vitejs.dev/). When you see imports that start with `/dx:`, you know a Fastify DX virtual module is being used.
496 |
497 | Fastify DX virtual modules are **fully ejectable**. For instance, the starter template relies on the `/dx:root.svelte` virtual module to provide the Vue shell of your application. If you copy the `root.svelte` file [from the fastify-dx-svelte package](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/root.svelte) and place it your Vite project root, **that copy of the file is used instead**. In fact, the starter template already comes with a custom `root.svelte` of its own to include UnoCSS.
498 |
499 | Aside from `root.svelte`, the starter template comes with two other virtual modules already ejected and part of the local project — `context.js` and `layouts/default.svelte`. If you don't need to customize them, you can safely removed them from your project.
500 |
501 | ### `/dx:root.svelte`
502 |
503 | This is the root Svelte component. It's provided as part of the starter template. You can use this file to add a common layout to all routes. The version provided as part of the starter template includes [UnoCSS](https://github.com/unocss/unocss)'s own virtual module import, necessary to enable its CSS engine.
504 |
505 | ```html
506 | <script>
507 | import 'uno.css'
508 | import { proxy } from 'sveltio'
509 | import { Router, Route } from 'svelte-routing'
510 | import DXRoute from '/dx:route.svelte'
511 |
512 | export let url = null
513 | export let payload
514 |
515 | let state = proxy(payload.serverRoute.state)
516 | </script>
517 |
518 | <Router url="{url}">
519 | {#each payload.routes as { path, component }}
520 | <Route path="{path}" let:location>
521 | <DXRoute
522 | path={path}
523 | location={location}
524 | state={state}
525 | payload={payload}
526 | component={component} />
527 | </Route>
528 | {/each}
529 | </Router>
530 | ```
531 |
532 | ### `/dx:route.svelte`
533 |
534 | This is used by `root.svelte` to enhance your route modules with the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md).
535 |
536 | <b>You'll rarely need to customize this file.</b>
537 |
538 | ```html
539 | <script>
540 | import { setContext } from 'svelte'
541 | import Loadable from 'svelte-loadable'
542 | import { routeContext, jsonDataFetch } from '/dx:core.js'
543 | import layouts from '/dx:layouts.js'
544 |
545 | const isServer = import.meta.env.SSR
546 |
547 | setContext(routeContext, {
548 | get routeContext () {
549 | return ctx
550 | }
551 | })
552 |
553 | export let path
554 | export let component
555 | export let payload
556 | export let state
557 | export let location
558 |
559 | let ctx = payload.routeMap[path]
560 |
561 | ctx.state = state
562 | ctx.actions = payload.serverRoute.actions
563 |
564 | if (isServer) {
565 | ctx.layout = payload.serverRoute.layout ?? 'default'
566 | ctx.data = payload.serverRoute.data
567 | ctx.state = state
568 | }
569 |
570 | async function setup () {
571 | if (payload.serverRoute.firstRender) {
572 | ctx.data = payload.serverRoute.data
573 | ctx.layout = payload.serverRoute.layout ?? 'default'
574 | payload.serverRoute.firstRender = false
575 | return
576 | }
577 | ctx.layout = ctx.layout ?? 'default'
578 | const { getMeta, getData, onEnter } = await ctx.loader()
579 | if (getData) {
580 | try {
581 | const fullPath = `${location.pathname}${location.search}`
582 | const updatedData = await jsonDataFetch(fullPath)
583 | if (!ctx.data) {
584 | ctx.data = {}
585 | }
586 | if (updatedData) {
587 | Object.assign(ctx.data, updatedData)
588 | }
589 | ctx.error = null
590 | } catch (error) {
591 | ctx.error = error
592 | }
593 | }
594 | if (getMeta) {
595 | const updatedMeta = await getMeta(ctx)
596 | if (updatedMeta) {
597 | payload.head.update(updatedMeta)
598 | }
599 | }
600 | if (onEnter) {
601 | const updatedData = await onEnter(ctx)
602 | if (updatedData) {
603 | Object.assign(ctx.data, updatedData)
604 | }
605 | }
606 | }
607 |
608 | let setupClientRouteContext = !isServer && setup()
609 | </script>
610 |
611 | {#if isServer}
612 | <svelte:component this={layouts[ctx.layout].default}>
613 | <svelte:component this={component} />
614 | </svelte:component>
615 | {:else}
616 | {#await setupClientRouteContext}{:then}
617 | <svelte:component this={layouts[ctx.layout].default}>
618 | <Loadable loader={component} />
619 | </svelte:component>
620 | {/await}
621 | {/if}
622 | ```
623 |
624 | What you see above is its [full definition](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/route.svelte).
625 |
626 |
627 | ### `/dx:routes.js`
628 |
629 | Fastify DX 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.
630 |
631 | ```js
632 | export default import.meta.env.SSR
633 | ? createRoutes(import.meta.globEager('$globPattern'))
634 | : hydrateRoutes(import.meta.glob('$globPattern'))
635 | ```
636 |
637 | See [the full file](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/routes.js) for the `createRoutes()` and `hydrateRoutes()` definitions.
638 |
639 | If you want to use your own custom routes list, you must eject this file as-is and replace the glob imports with your own routes list:
640 |
641 | ```js
642 | const routes = [
643 | {
644 | path: '/',
645 | component: () => import('/custom/index.svelte'),
646 | }
647 | ]
648 |
649 | export default import.meta.env.SSR
650 | ? createRoutes(routes)
651 | : hydrateRoutes(routes)
652 | ````
653 |
654 | **Nested routes aren't supported yet.**
655 |
656 |
657 | ### `/dx:core.js`
658 |
659 | Implements `useRouteContext()`.
660 |
661 | See its full definition [here](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/core.js).
662 |
663 | ### `/dx:layouts.js`
664 |
665 | This is responsible for loading **layout components**. It's part of `route.svelte` by default. If a project has no `layouts/default.svelte` file, the default one from Fastify DX is used. This virtual module works in conjunction with the `/dx:layouts/` virtual module which provides exports from the `/layouts` folder.
666 |
667 | <b>You'll rarely need to customize this file.</b>
668 |
669 | ```js
670 | import DefaultLayout from '/dx:layouts/default.svelte'
671 |
672 | const appLayouts = import.meta.globEager('/layouts/*.svelte')
673 |
674 | appLayouts['/layouts/default.svelte'] ??= DefaultLayout
675 |
676 | export default Object.fromEntries(
677 | Object.keys(appLayouts).map((path) => {
678 | const name = path.slice(9, -7)
679 | return [name, appLayouts[path]]
680 | }),
681 | )
682 |
683 | ```
684 |
685 | What you see above is its [full definition](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/layouts.js).
686 |
687 | ### `/dx:mount.js`
688 |
689 | 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.
690 |
691 | <b>You'll rarely need to customize this file.</b>
692 |
693 | [See the full file](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/virtual/mount.js) for the `mount()` function definition.
694 |
695 |
696 |
697 | ## Maintainance
698 |
699 | Created and maintained by [Jonas Galvez](https://github.com/sponsors/galvez), **Principal Engineer** and **Open Sourcerer** at [NodeSource](https://nodesource.com).
700 |
701 | New contributors are extremely welcome to look for [good first issues](https://github.com/fastify/fastify-dx/labels/good%20first%20issue).
702 |
703 | ## Gold Sponsors
704 |
705 | <a href="https://nodesource.com"><img width="200px" src="https://user-images.githubusercontent.com/12291/206885948-3fa742a2-1057-4db2-8648-46f5cb673461.svg"></a>
706 |
707 | [Contact me](mailto:jonasgalvez@gmail.com) to add your company's logo here.
708 |
709 | ## GitHub Sponsors
710 |
711 | - [**Duc-Thien Bui**](https://github.com/aecea)
712 | - [**Tom Preston-Werner**](https://github.com/mojombo)
713 | - [**Clifford Fajardo**](https://github.com/cliffordfajardo)
714 | - [**David Adam Coffey**](https://github.com/dacoffey)
715 | - [**Mezereon**](https://github.com/mezereon-co)
716 | - [**A-J Roos**](https://github.com/Asjas)
717 | - [**James Isaacs**](https://github.com/jamesisaacs2)
718 |
719 | [**Click here**](https://github.com/sponsors/galvez) to add your name to this list.
720 |
721 | _Thank you!_
722 |
--------------------------------------------------------------------------------
/packages/fastify-solid/README.md:
--------------------------------------------------------------------------------
1 | <br>
2 |
3 | # @fastify/solid [](https://www.npmjs.com/package/@fastify/solid) [](https://standardjs.com/)
4 |
5 | **Fastify DX for Solid** (**`@fastify/solid`**) is a renderer for [**@fastify/vite**](https://github.com/fastify/fastify-vite).
6 |
7 | It lets you run and SSR (server-side render) **Solid applications built with Vite** on [Fastify](https://fastify.io/), with a minimal and transparent **server-first approach** — everything starts with `server.js`, your actual Fastify server.
8 |
9 | It has an extremely small core (~1k LOC total) and is built on top of [Fastify](https://github.com/fastify/fastify), [Vite](https://vitejs.dev/) and [Solid Router](https://github.com/solidjs/solid-router).
10 |
11 | ## Quick Start
12 |
13 | Ensure you have **Node v16+**.
14 |
15 | Make a copy of [**starters/solid**](https://github.com/fastify/fastify-dx/tree/dev/starters/solid). If you have [`degit`](https://github.com/Rich-Harris/degit), run the following from a new directory:
16 |
17 | ```bash
18 | degit fastify/fastify-dx/starters/solid
19 | ```
20 |
21 | > **If you're starting a project from scratch**, you'll need these packages installed.
22 | >
23 | > ```bash
24 | > npm i fastify fastify-vite fastify-dx-solid -P
25 | > npm i vite-plugin-solid -D
26 | > ```
27 |
28 |
29 | Run `npm install`.
30 |
31 | Run `npm run dev`.
32 |
33 | Visit `http://localhost:3000/`.
34 |
35 | ## What's Included
36 |
37 | That will get you a **starter template** with:
38 |
39 | - A minimal [Fastify](https://github.com/fastify/fastify) server.
40 | - Some dummy API routes.
41 | - A `pages/` folder with some [demo routes](https://github.com/fastify/fastify-dx/tree/dev/starters/solid/client/pages).
42 | - All configuration files.
43 |
44 | It also includes some _**opinionated**_ essentials:
45 |
46 | - [**PostCSS Preset Env**](https://www.npmjs.com/package/postcss-preset-env) by [**Jonathan Neal**](https://github.com/jonathantneal), which enables [several modern CSS features](https://preset-env.cssdb.org/), such as [**CSS Nesting**](https://www.w3.org/TR/css-nesting-1/).
47 |
48 | - [**UnoCSS**](https://github.com/unocss/unocss) by [**Anthony Fu**](https://antfu.me/), which supports all [Tailwind utilities](https://uno.antfu.me/) and many other goodies through its [default preset](https://github.com/unocss/unocss/tree/main/packages/preset-uno).
49 |
50 | ## Package Scripts
51 |
52 | - `npm run dev` boots the development server.
53 | - `npm run build` creates the production bundle.
54 | - `npm run serve` serves the production bundle.
55 |
56 | ## Basic setup
57 |
58 | The [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/solid) follows [fastify-vite](https://github.com/fastify/fastify-vite)'s convention of having a `client` folder with an `index.js` file, which is automatically resolved as your `clientModule` setting.
59 |
60 | If you want flat directory setup, where server and client files are mixed together, you can manually set `clientModule` to something else. Note that in this case you'll also need to update `root` in your `vite.config.js` file.
61 |
62 | When deploying to production, bear in mind the `client/dist` directory, generated when you run `npm run build`, needs to be included. You'll also want to enable Fastify's [built-in logging](https://www.fastify.io/docs/latest/Reference/Logging/):
63 |
64 | ```js
65 | const server = Fastify({ logger: true })
66 | ```
67 |
68 | The starter template's `server.js` file:
69 |
70 | ```js
71 | import Fastify from 'fastify'
72 | import FastifyVite from 'fastify-vite'
73 | import FastifyDXSolid from 'fastify-dx-solid'
74 |
75 | const server = Fastify()
76 |
77 | await server.register(FastifyVite, {
78 | root: import.meta.url,
79 | renderer: FastifyDXSolid,
80 | })
81 |
82 | await server.vite.ready()
83 | await server.listen(3000)
84 | ```
85 |
86 | The starter template's [`vite.config.js`](https://github.com/fastify/fastify-dx/blob/main/starters/solid/vite.config.js) file:
87 |
88 | ```js
89 | import { join, dirname } from 'path'
90 | import { fileURLToPath } from 'url'
91 |
92 | import viteSolid from 'vite-plugin-solid'
93 | import viteSolidFastifyDX from 'fastify-dx-solid/plugin'
94 | import unocss from 'unocss/vite'
95 |
96 | const path = fileURLToPath(import.meta.url)
97 | const root = join(dirname(path), 'client')
98 |
99 | const plugins = [
100 | viteSolid({ ssr: true }),
101 | viteSolidFastifyDX(),
102 | unocss()
103 | ]
104 |
105 | const ssr = {
106 | noExternal: ['solid-app-router'],
107 | }
108 |
109 | export default { root, plugins, ssr }
110 | ```
111 |
112 | Note that you only need to use Fastify DX's Vite plugin, which includes all functionality from [fastify-vite](https://github.com/fastify/fastify-vite)'s Vite plugin.
113 |
114 | </td>
115 | </tr>
116 | </table>
117 |
118 | ## Project Structure
119 |
120 | The [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/solid) looks like this:
121 |
122 | ```
123 | ├── server.js
124 | ├── client/
125 | │ ├── index.js
126 | │ ├── context.js
127 | │ ├── root.jsx
128 | │ ├── index.html
129 | │ ├── layouts/
130 | │ │ ├── default.jsx
131 | │ │ └── auth.jsx
132 | │ └── pages/
133 | │ ├── index.jsx
134 | │ ├── client-only.jsx
135 | │ ├── server-only.jsx
136 | │ ├── using-data.jsx
137 | │ └── using-store.jsx
138 | ├── vite.config.js
139 | └── package.json
140 | ```
141 |
142 | Several internal files are provided as virtual modules by Fastify DX. They are located inside the `fastify-dx-solid` package in `node_modules`, and dynamically loaded so you don't have to worry about them unless you want them overriden.
143 |
144 | In this case, placing a file with the same name as the registered virtual module in your Vite project root will override it. Find the detailed rundown of all virtual modules [here][virtual-modules].
145 |
146 | [virtual-modules]: https://github.com/fastify/fastify-dx/blob/main/docs/solid/virtual-modules.md
147 |
148 | The `server.js` file is your application entry point. It's the file that runs everything. It boots a Fastify server configured with [**fastify-vite**](https://github.com/fastify/fastify-vite) and **Fastify DX for Solid** as a renderer adapter to **fastify-vite**.
149 |
150 | The `client/index.js` file is your Vite server entry point, it's the file that provides your client bundle (which runs in the Vite-enriched environment) to the Node.js environment where Fastify runs.
151 |
152 | > Right now, it's mostly a **boilerplate file** because it must exist but it will also probably never need to be changed.
153 |
154 | It exports your application's factory function (must be named `create`), the application routes (must be named `routes`) and the universal route context [initialization module](https://github.com/fastify/fastify-dx/blob/main/docs/solid/route-context.md#initialization-module) (must be named `context` and have a dynamic module import so Fastify DX can pick up `default` and named exports).
155 |
156 | The `client/index.html` file is the [root HTML template of the application](https://vitejs.dev/guide/#index-html-and-project-root), which Vite uses as the client bundling entry point.
157 |
158 | > You can expand this file with additional `<meta>` and `<link>` tags if you wish, provided you don't remove any of the placeholders.
159 |
160 | This files links to `/dx:mount.js`, which is a virtual module provided by Fastify DX.
161 |
162 | Virtual modules are covered [here][virtual-modules].
163 |
164 | The `client/pages/` directory contains your route modules, whose paths are dynamically inferred from the directory structure itself. You can change this behavior easily. More on this [here][routing-config].
165 |
166 | [routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/solid/routing-config.md
167 |
168 | The `client/layouts/` directory contains your route layout modules, which can be associated to any route. By default, `layouts/default.jsx` is used, but if you don't need to do any modifications on that file, you can safely removed as it's provided by Fastify DX in that case. The starter template also comes with `layouts/auth.jsx`, to demonstrate a more advanced use of layouts.
169 |
170 | [routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/solid/routing-config.md
171 |
172 | The `client/context.js` file is the universal [route context][route-context] initialization module. Any named exports from this file are attached to the `RouteContext` class prototype on the server, preventing them from being reassigned on every request. The `default` export from this file, however, runs for every request so you can attach any request-specific data to it.
173 |
174 | [route-context]: https://github.com/fastify/fastify-dx/blob/main/docs/solid/route-context.md
175 |
176 | # Rendering modes
177 |
178 | Following the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), Fastify DX's route modules can be set for universal rendering (SSR + CSR hydration, the default behavior), SSR in streaming mode, SSR only (client gets no JavaScript) or CSR only (SSR fully disabled). Fastify DX for Svelte supports all of these modes minus streaming, which is currently not yet supported by Svelte itself.
179 |
180 | ## `streaming`
181 |
182 | If a route module exports `streaming` set to `true`, SSR will take place in **streaming mode**. That means if you have components depending on asynchronous resources and `<Suspense>` sections with defined fallback components, they will be streamed right way while the resources finish processing.
183 |
184 | ```jsx
185 | import { createResource } from 'solid-js'
186 | import { useRouteContext } from '/dx:core.js'
187 |
188 | export const streaming = true
189 |
190 | export default function Streaming () {
191 | const {state} = useRouteContext()
192 | const [message] = createResource(async () => {
193 | // If already retrieved on the server, no need
194 | // to wait for it on the client
195 | if (state.message) {
196 | return state.message
197 | }
198 | // Note: assignments to useRouteContext().state on the server
199 | // are automatically relayed to the client in the hydration payload
200 | const message = await afterSeconds({
201 | message: 'Delayed by Resource API',
202 | seconds: 5,
203 | })
204 | state.message = message
205 | return message
206 | })
207 | return (
208 | <Suspense fallback={<p>Waiting for content</p>}>
209 | <Message message={message()} />
210 | </Suspense>
211 | )
212 | }
213 | ```
214 |
215 | [See the full example](https://github.com/fastify/fastify-dx/blob/main/starters/solid/client/pages/streaming.jsx) in the [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/solid).
216 |
217 | ## `serverOnly`
218 |
219 | If a route module exports `serverOnly` set to `true`, only SSR will take place. The client gets the server-side rendered markup without any accompanying JavaScript or data hydration.
220 |
221 | You should use this setting to deliver lighter pages when there's no need to run any code on them, such as statically generated content sites.
222 |
223 | ```jsx
224 | export const serverOnly = true
225 |
226 | export default function ServerOnly (props) {
227 | return <p>This route is rendered on the server only!</p>
228 | }
229 | ```
230 |
231 | [This example](https://github.com/fastify/fastify-dx/blob/main/starters/solid/client/pages/server-only.jsx) is part of the [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/solid).
232 |
233 | ## `clientOnly`
234 |
235 | If a route module exports `clientOnly` set to `true`, no SSR will take place, only data fetching and data hydration. The client gets the empty container element (the one that wraps `<!-- element -->` in `index.html`) and all rendering takes place on the client only.
236 |
237 | You can use this setting to save server resources on internal pages where SSR makes no significant diference for search engines or UX in general, such as a password-protected admin section.
238 |
239 | ```jsx
240 | export const clientOnly = true
241 |
242 | export default function Route (props) {
243 | return <p>This route is rendered on the client only!</p>
244 | }
245 | ```
246 |
247 | [This example](https://github.com/fastify/fastify-dx/blob/main/starters/solid/client/pages/client-only.jsx) is part of the [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/solid).
248 |
249 | ## Routing Configuration
250 |
251 | By default, routes are loaded from the `<project-root>/pages` folder, where `<project-root>` refers to the `root` setting in `vite.config.js`. The route paths are **dynamically inferred from the directory structure**, very much like Next.js and Nuxt.js.
252 |
253 | ### Dynamic parameters
254 |
255 | Dynamic route parameters follow the [Next.js convention](https://nextjs.org/docs/basic-features/pages#pages-with-dynamic-routes) (`[param]`), but that can be overriden by using the `paramPattern` plugin option. For example, this configuration switches the param pattern to the [Remix convention](https://remix.run/docs/en/v1/guides/routing#dynamic-segments) (`$param`).
256 |
257 | ```js
258 | // ...
259 | const plugins = [
260 | // ...
261 | viteSvelteFastifyDX({ paramPattern: /\$(\w+)/ }),
262 | ]
263 | ```
264 |
265 | ### Routes location
266 |
267 | You can also change the glob pattern used to determine where to route modules from.
268 |
269 | Since this setting is passed to [Vite's glob importers](https://vitejs.dev/guide/features.html#glob-import), the value needs to be a string:
270 |
271 | ```js
272 | // ...
273 | const plugins = [
274 | // ...
275 | viteSvelteFastifyDX({ globPattern: '/views/**/*.svelte' }),
276 | ]
277 | ```
278 |
279 | ### View modules
280 |
281 | You also can export a `path` constant from your route modules, in which case its value will be used to **override the dynamically inferred paths from the directory structure**.
282 |
283 | Additionally, [**you can provide your own routes**](https://github.com/fastify/fastify-dx/tree/dev/packages/fastify-dx-svelte#dxroutesjs).
284 |
285 | ```html
286 | <script context="module">
287 | export const path = '/my-page'
288 | </script>
289 |
290 | <p>Route with path export</p>
291 | ```
292 |
293 | ## Isomorphic data prefetching
294 |
295 | Fastify DX for Svelte implements the `getData()` hook from the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md) to solve this problem.
296 |
297 | ### `getData(ctx)`
298 |
299 | This hook is set up in a way that it runs server-side before any SSR takes place, so any data fetched is made available to the route component before it starts rendering. During first render, any data retrieved on the server is automatically sent to be hydrated on the client so no new requests are made. Then, during client-side navigation (post first-render), a JSON request is fired to an endpoint automatically registered for running the `getData()` function for that route on the server.
300 |
301 | The objet returned by `getData()` gets automatically assigned as `data` in the [universal route context](https://github.com/fastify/fastify-dx/blob/main/docs/solid/route-context.md) object and is accessible from `getMeta()` and `onEnter()` hooks and also via the `useRouteContext()` hook.
302 |
303 | ```jsx
304 | import { useRouteContext } from '/dx:core.js'
305 |
306 | export function getData (ctx) {
307 | return {
308 | message: 'Hello from getData!',
309 | }
310 | }
311 |
312 | export default function Route (props) {
313 | const { data } = useRouteContext()
314 | return <p>{data.message}</p>
315 | }
316 | ```
317 |
318 | ## Route Layouts
319 |
320 | Fastify DX will automatically load layouts from the `layouts/` folder. By default, `/dx:layouts/default.jsx` is used — that is, if a project is missing a `layouts/defaults.jsx` file, the one provided by Fastify DX is used instead.
321 |
322 | See the section on [Virtual Modules](https://github.com/fastify/fastify-dx/blob/main/docs/solid/virtual-modules.md) to learn more about this.
323 |
324 | You assign a layout to a route by exporting `layout`.
325 |
326 | See [`pages/using-auth.jsx`](https://github.com/fastify/fastify-dx/blob/main/starters/solid/pages/using-auth.jsx) in the starter template:
327 |
328 | ```js
329 | export const layout = 'auth'
330 | ```
331 |
332 | That'll will cause the route to be wrapped in the layout component exported by [`layouts/auth.jsx`](https://github.com/fastify/fastify-dx/blob/main/starters/solid/layouts/auth.jsx):
333 |
334 | ```jsx
335 | import { useRouteContext } from '/dx:core.js'
336 |
337 | export default function Auth (props) {
338 | const { actions, state } = useRouteContext()
339 | const authenticate = () => actions.authenticate(state)
340 | return (
341 | <div class="contents">
342 | {state.user.authenticated
343 | ? props.children
344 | : <Login onClick={() => authenticate()} /> }
345 | </div>
346 | )
347 | }
348 |
349 | function Login (props) {
350 | return (
351 | <>
352 | <p>This route needs authentication.</p>
353 | <button onClick={props.onClick}>
354 | Click this button to authenticate.
355 | </button>
356 | </>
357 | )
358 | }
359 | ```
360 |
361 | Note that like routes, it has access to `useRouteContext()`.
362 |
363 | ## Route Context
364 |
365 | ### Initialization module
366 |
367 | The starter template includes a sample `context.js` file. This file is optional and can be safely removed. If it's present, Fastify DX automatically loads it and uses it to do any RouteContext extensions or data injections you might need. If you're familiar with [Nuxt.js](https://nuxtjs.org/), you can think of it as a [Nuxt.js plugin](https://nuxtjs.org/docs/directory-structure/plugins/).
368 |
369 | **Consuming the route context:**
370 |
371 | ```js
372 | import {
373 | useRouteContext
374 | } from '/dx:core.js'
375 |
376 | // ...
377 | const {
378 | state,
379 | actions
380 | } = useRouteContext()
381 |
382 | // ...
383 | actions.addTodoItem(state, value)
384 | ```
385 |
386 | See the [full example](https://github.com/fastify/fastify-dx/blob/main/starters/solid/client/pages/using-store.vue) in the starter template.
387 |
388 | This example demonstrates how to use it to set up an universally available (SSR and CSR) `$fetch` function (using [`ky-universal`](https://www.npmjs.com/package/ky-universal)) and also export some store actions. They're all made available by `useRouteContext()`, covered next.
389 |
390 | ```js
391 | import ky from 'ky-universal'
392 |
393 | export default (ctx) => {
394 | if (ctx.server) {
395 | // Populate state.todoList on the server
396 | ctx.state.todoList = ctx.server.db.todoList
397 | // It'll get automatically serialized to the client on first render!
398 | }
399 | }
400 |
401 | export const $fetch = ky.extend({
402 | prefixUrl: 'http://localhost:3000'
403 | })
404 |
405 | // Must be a function so each request can have its own state
406 | export const state = () => ({
407 | todoList: null,
408 | })
409 |
410 | export const actions = {
411 | async addTodoItem (state, item) {
412 | await $fetch.put('api/todo/items', {
413 | json: { item },
414 | })
415 | state.todoList.push(item)
416 | },
417 | }
418 | ```
419 |
420 | See the [full example](https://github.com/fastify/fastify-dx/blob/main/starters/solid/client/context.js) in the starter template.
421 |
422 | ### The `useRouteContext()` hook
423 |
424 | This hook can be used in any Vue component to retrieve a reference to the current route context. It's modelled after the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), with still some rough differences and missing properties in this **alpha release**.
425 |
426 | By default, It includes reference to `data` — which is automatically populated if you use the `getData()` function, and `state` which hold references to the global [`reactive()`](https://vuejs.org/api/reactivity-core.html#reactive) object.
427 |
428 | It automatically causes the component to be suspended if the `getData()`, `getMeta()` and `onEnter()` functions are asynchronous.
429 |
430 | ```jsx
431 | import { useRouteContext } from '/dx:core.js'
432 |
433 | export default function Route (props) {
434 | const { data } = useRouteContext()
435 | return <p>{data.message}</p>
436 | }
437 | ```
438 |
439 | ### Execution order
440 |
441 | This graph illustrates the execution order to expect from route context initialization.
442 |
443 | ```
444 | context.js default function export
445 | └─ getData() function export
446 | └─ getMeta() function export
447 | └─ onEnter() function export
448 | └─ Route module
449 | ```
450 |
451 | First the `default` function export from `context.js` (if present) is executed. This is where you can manually feed global server data into your application by populating the global state (the route context's `state` property, which is automatically hydrated on the client.
452 |
453 | Then `getData()` runs — which populates the route context's `data` property, and is also automatically hydrated on the client. Then `getMeta()`, which populates the route context's `head` property. Then `onEnter()`, and finally your route component.
454 |
455 | ## Universal Route Enter Event
456 |
457 | ### `onEnter(ctx)`
458 |
459 | If a route module exports a `onEnter()` function, it's executed before the route renders, both in SSR and client-side navigation. That is, the first time a route render on the server, onEnter() runs on the server. Then, since it already ran on the server, it doesn't run again on the client for that first route. But if you navigate to another route on the client using `<Link>`, it runs normally as you'd expect.
460 |
461 | It receives the [universal route context][route-context] as first parameter, so you can make changes to `data`, `meta` and `state` if needed.
462 |
463 | [route-context]: https://github.com/fastify/fastify-dx/blob/main/docs/solid/route-context.md
464 |
465 | ```jsx
466 | export function onEnter (ctx) {
467 | if (ctx.server?.underPressure) {
468 | ctx.clientOnly = true
469 | }
470 | }
471 |
472 | export default function Route (props) {
473 | <p>No pre-rendered HTML sent to the browser.</p>
474 | }
475 | ```
476 |
477 | The example demonstrates how to turn off SSR and downgrade to CSR-only, assuming you have a `pressureHandler` configured in [`underpressure`](https://github.com/fastify/under-pressure) to set a `underPressure` flag on your server instance.
478 |
479 |
480 | ## Meta Tags
481 |
482 | Following the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md), Fastify DX renders `<head>` elements independently from the SSR phase. This allows you to fetch data for populating the first `<meta>` tags and stream them right away to the client, and only then perform SSR.
483 |
484 | > Additional `<link>` preload tags can be produced from the SSR phase. This is **not currently implemented** in this **alpha release** but is a planned feature. If you can't wait for it, you can roll out your own (and perhaps contribute your solution) by providing your own [`createHtmlFunction()`](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/index.js#L57) to [fastify-vite](https://github.com/fastify/fastify-vite).
485 |
486 | ### `getMeta()`
487 |
488 | To populate `<title>`, `<meta>` and `<link>` elements, export a `getMeta()` function that returns an object matching the format expected by [unihead](https://github.com/galvez/unihead), the underlying library used by Fastify DX.
489 |
490 | It receives the [route context](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/README.md#route-context) as first parameter and runs after `getData()`, allowing you to access any `data` populated by these other functions to generate your tags.
491 |
492 | ```jsx
493 | export function getMeta (ctx) {
494 | return {
495 | title: 'Route Title',
496 | meta: [
497 | { name: 'twitter:title', value: 'Route Title' },
498 | ]
499 | }
500 | }
501 |
502 | export default function Route (props) {
503 | return <p>Route with meta tags.</p>
504 | }
505 | ```
506 |
507 |
508 | ## Virtual Modules
509 |
510 | **Fastify DX** 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 are a [Rollup](https://rollupjs.org/guide/en/) feature exposed and fully supported by [Vite](https://vitejs.dev/). When you see imports that start with `/dx:`, you know a Fastify DX virtual module is being used.
511 |
512 | Fastify DX virtual modules are **fully ejectable**. For instance, the starter template relies on the `/dx:root.jsx` virtual module to provide the Vue shell of your application. If you copy the `root.jsx` file [from the fastify-dx-solid package](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/root.jsx) and place it your Vite project root, **that copy of the file is used instead**. In fact, the starter template already comes with a custom `root.jsx` of its own to include UnoCSS.
513 |
514 | Aside from `root.jsx`, the starter template comes with two other virtual modules already ejected and part of the local project — `context.js` and `layouts/default.jsx`. If you don't need to customize them, you can safely removed them from your project.
515 |
516 | ### `/dx:root.jsx`
517 |
518 | This is the root Solid component. It's provided as part of the starter template. You can use this file to add a common layout to all routes. The version provided as part of the starter template includes [UnoCSS](https://github.com/unocss/unocss)'s own virtual module import, necessary to enable its CSS engine.
519 |
520 | ```jsx
521 | import 'uno.css'
522 | import { createMutable } from 'solid-js/store'
523 | import { Router, Routes, Route } from 'solid-app-router'
524 | import DXRoute from '/dx:route.jsx'
525 |
526 | export default function Root (props) {
527 | props.payload.serverRoute.state = createMutable(props.payload.serverRoute.state)
528 | return (
529 | <Router url={props.url}>
530 | <Routes>{
531 | // eslint-disable-next-line solid/prefer-for
532 | props.payload.routes.map(route =>
533 | <Route path={route.path} element={
534 | <DXRoute
535 | state={props.payload.serverRoute.state}
536 | path={route.path}
537 | payload={props.payload}
538 | component={route.component} />
539 | } />
540 | )
541 | }</Routes>
542 | </Router>
543 | )
544 | }
545 | ```
546 |
547 | ### `/dx:route.jsx`
548 |
549 | This is used by `root.jsx` to enhance your route modules with the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md).
550 |
551 | <b>You'll rarely need to customize this file.</b>
552 |
553 | ```jsx
554 | import { createContext, createSignal, createResource, children } from 'solid-js'
555 | import { isServer, Suspense } from 'solid-js/web'
556 | import { Router, Routes, Route, useLocation } from 'solid-app-router'
557 | import { RouteContext, jsonDataFetch } from '/dx:core.js'
558 | import layouts from '/dx:layouts.js'
559 |
560 | export default function DXRoute (props) {
561 | const ctx = props.payload.routeMap[props.path]
562 | const location = useLocation()
563 |
564 | ctx.state = props.state
565 | ctx.actions = props.payload.serverRoute.actions
566 |
567 | if (isServer) {
568 | ctx.layout = props.payload.serverRoute.layout ?? 'default'
569 | ctx.data = props.payload.serverRoute.data
570 | }
571 |
572 | async function setup () {
573 | if (props.payload.serverRoute.firstRender) {
574 | // ctx.hydration = props.payload.serverRoute.hydration
575 | ctx.data = props.payload.serverRoute.data
576 | ctx.layout = props.payload.serverRoute.layout ?? 'default'
577 | props.payload.serverRoute.firstRender = false
578 | return ctx
579 | }
580 | ctx.layout = ctx.layout ?? 'default'
581 | const { getMeta, getData, onEnter } = await ctx.loader()
582 | if (getData) {
583 | try {
584 | const fullPath = `${location.pathname}${location.search}`
585 | const updatedData = await jsonDataFetch(fullPath)
586 | if (!ctx.data) {
587 | ctx.data = {}
588 | }
589 | if (updatedData) {
590 | Object.assign(ctx.data, updatedData)
591 | }
592 | ctx.error = null
593 | } catch (error) {
594 | ctx.error = error
595 | }
596 | }
597 | if (getMeta) {
598 | const updatedMeta = await getMeta(ctx)
599 | if (updatedMeta) {
600 | props.payload.head.update(updatedMeta)
601 | }
602 | }
603 | if (onEnter) {
604 | const updatedData = await onEnter(ctx)
605 | if (updatedData) {
606 | Object.assign(ctx.data, updatedData)
607 | }
608 | }
609 | return ctx
610 | }
611 |
612 | let element
613 | if (isServer) {
614 | element = (
615 | <RouteContext.Provider value={ctx}>
616 | <Layout id={ctx.layout}>
617 | <props.component />
618 | </Layout>
619 | </RouteContext.Provider>
620 | )
621 | } else {
622 | const [routeContext] = createResource(setup)
623 | element = (
624 | <Suspense>
625 | {!routeContext.loading &&
626 | <RouteContext.Provider value={routeContext()}>
627 | <Layout id={routeContext().layout}>
628 | <props.component />
629 | </Layout>
630 | </RouteContext.Provider>
631 | }
632 | </Suspense>
633 | )
634 | }
635 | return element
636 | }
637 |
638 | function Layout (props) {
639 | const Component = layouts[props.id].default
640 | return <Component>{props.children}</Component>
641 | }
642 | ```
643 |
644 | What you see above is its [full definition](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/route.jsx).
645 |
646 |
647 | ### `/dx:routes.js`
648 |
649 | Fastify DX 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.
650 |
651 | ```js
652 | export default import.meta.env.SSR
653 | ? createRoutes(import.meta.globEager('$globPattern'))
654 | : hydrateRoutes(import.meta.glob('$globPattern'))
655 | ```
656 |
657 | See [the full file](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/routes.js) for the `createRoutes()` and `hydrateRoutes()` definitions.
658 |
659 | If you want to use your own custom routes list, you must eject this file as-is and replace the glob imports with your own routes list:
660 |
661 | ```js
662 | const routes = [
663 | {
664 | path: '/',
665 | component: () => import('/custom/index.jsx'),
666 | }
667 | ]
668 |
669 | export default import.meta.env.SSR
670 | ? createRoutes(routes)
671 | : hydrateRoutes(routes)
672 | ````
673 |
674 | **Nested routes aren't supported yet.**
675 |
676 |
677 | ### `/dx:core.js`
678 |
679 | Implements `useRouteContext()`.
680 |
681 | See its full definition [here](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/core.js).
682 |
683 | ### `/dx:layouts.js`
684 |
685 | This is responsible for loading **layout components**. It's part of `route.jsx` by default. If a project has no `layouts/default.jsx` file, the default one from Fastify DX is used. This virtual module works in conjunction with the `/dx:layouts/` virtual module which provides exports from the `/layouts` folder.
686 |
687 | <b>You'll rarely need to customize this file.</b>
688 |
689 | ```js
690 | import DefaultLayout from '/dx:layouts/default.jsx'
691 |
692 | const appLayouts = import.meta.globEager('/layouts/*.jsx')
693 |
694 | appLayouts['/layouts/default.jsx'] ??= DefaultLayout
695 |
696 | export default Object.fromEntries(
697 | Object.keys(appLayouts).map((path) => {
698 | const name = path.slice(9, -4)
699 | return [name, appLayouts[path]]
700 | }),
701 | )
702 |
703 | ```
704 |
705 | What you see above is its [full definition](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/layouts.js).
706 |
707 | ### `/dx:mount.js`
708 |
709 | 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.
710 |
711 | <b>You'll rarely need to customize this file.</b>
712 |
713 | [See the full file](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-solid/virtual/mount.js) for the `mount()` function definition.
714 |
715 |
716 | ## Maintainance
717 |
718 | Created and maintained by [Jonas Galvez](https://github.com/sponsors/galvez), **Principal Engineer** and **Open Sourcerer** at [NodeSource](https://nodesource.com).
719 |
720 | New contributors are extremely welcome to look for [good first issues](https://github.com/fastify/fastify-dx/labels/good%20first%20issue).
721 |
722 | ## Gold Sponsors
723 |
724 | <a href="https://nodesource.com"><img width="200px" src="https://user-images.githubusercontent.com/12291/206885948-3fa742a2-1057-4db2-8648-46f5cb673461.svg"></a>
725 |
726 | [Contact me](mailto:jonasgalvez@gmail.com) to add your company's logo here.
727 |
728 | ## GitHub Sponsors
729 |
730 | - [**Duc-Thien Bui**](https://github.com/aecea)
731 | - [**Tom Preston-Werner**](https://github.com/mojombo)
732 | - [**Clifford Fajardo**](https://github.com/cliffordfajardo)
733 | - [**David Adam Coffey**](https://github.com/dacoffey)
734 | - [**Mezereon**](https://github.com/mezereon-co)
735 | - [**A-J Roos**](https://github.com/Asjas)
736 | - [**James Isaacs**](https://github.com/jamesisaacs2)
737 |
738 | [**Click here**](https://github.com/sponsors/galvez) to add your name to this list.
739 |
740 | _Thank you!_
741 |
--------------------------------------------------------------------------------
|