Merge pull request #19 from fastify/svelte-support

Svelte support

Author: galvez

README.md

@@ -39,6 +39,23 @@ Try out the [**alpha release** of Fastify DX for Vue](https://github.com/fastify
 </table>  
 
 
+<table>
+<tr>
+<td width="200px" valign="top">
+
+### [fastify-dx-svelte](https://github.com/fastify/fastify-dx/tree/main/packages/fastify-dx-svelte)<br><br>[![NPM version](https://img.shields.io/npm/v/fastify-dx-svelte.svg?style=flat)](https://www.npmjs.com/package/fastify-dx-svelte) 
+ 
+</td>
+<td width="500px"><br>
+
+Try out the [**alpha release** of Fastify DX for Svelte](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).
+
+</td>
+</tr>
+</table>  
+
+
+
 ## Status
 
 Fastify DX is currently in **alpha**.

docs/svelte/basic-setup.md

@@ -0,0 +1,87 @@
+<sub>**Go back to the [index](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).**</sub>
+
+<br>
+
+## Basic setup
+
+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.
+
+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.
+
+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/):
+
+```js
+const server = Fastify({ logger: true })
+```
+
+The starter template's `server.js` file:
+
+```js
+import Fastify from 'fastify'
+import FastifyVite from 'fastify-vite'
+import FastifyDXSvelte from 'fastify-dx-svelte'
+
+const server = Fastify()
+
+await server.register(FastifyVite, { 
+  root: import.meta.url, 
+  renderer: FastifyDXSvelte,
+})
+
+await server.vite.ready()
+await server.listen(3000)
+```
+
+The starter template's [`vite.config.js`](https://github.com/fastify/fastify-dx/blob/main/starters/svelte/vite.config.js) file:
+
+```js
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+import { svelte as viteSvelte } from '@sveltejs/vite-plugin-svelte'
+import viteSvelteFastifyDX from 'fastify-dx-svelte/plugin'
+import unocss from 'unocss/vite'
+import { extractorSvelte } from '@unocss/core'
+
+const path = fileURLToPath(import.meta.url)
+
+const root = join(dirname(path), 'client')
+const plugins = [
+  unocss({ extractors: [extractorSvelte] }),
+  viteSvelte({
+    compilerOptions: {
+      hydratable: true,
+    }
+  }),
+  viteSvelteFastifyDX(),
+]
+
+export default { root, plugins }
+```
+
+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.
+
+</td>
+</tr>
+</table>
+
+### Route exports
+
+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). 
+
+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`:
+
+```html
+<script context="module">
+export function getData () {
+  return { message: 'Hello from getData!' }
+}
+<script>
+
+<script>
+import { useRouteContext } = '/dx:core.js'
+const { data } = useRouteContext()
+</script>
+
+<p>{data.message}</p>
+```

docs/svelte/data-prefetching.md

@@ -0,0 +1,30 @@
+<sub>**Go back to the [index](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).**</sub>
+
+<br>
+
+## Isomorphic data prefetching
+
+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.
+
+### `getData(ctx)`
+
+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.
+
+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.
+
+```html
+<script context="module">
+export function getData (ctx) {
+  return {
+    message: 'Hello from getData!',
+  }
+}
+</script>
+
+<script>
+import { useRouteContext } from '/dx:core.js'
+const { data } = useRouteContext()
+</script>
+
+<p>{data.message}</p>
+```

docs/svelte/index.md

@@ -0,0 +1,94 @@
+# fastify-dx-svelte [![NPM version](https://img.shields.io/npm/v/fastify-dx-svelte.svg?style=flat)](https://www.npmjs.com/package/fastify-dx-svelte) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
+
+- [**Introduction**](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md#introduction)
+- [**Quick Start**](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md#quick-start)
+- [**Package Scripts**](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md#package-scripts)
+- [**Basic Setup**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/basic-setup.md)
+- [**Project Structure**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/project-structure.md)
+- [**Rendering Modes**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/rendering-modes.md)
+- [**Routing Configuration**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/routing-config.md)
+- [**Data Prefetching**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/data-prefetching.md)
+- [**Route Layouts**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-layouts.md)
+- [**Route Context**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md)
+- [**Route Enter Event**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-enter.md)
+- [**Virtual Modules**](https://github.com/fastify/fastify-dx/blob/main/docs/svelte/virtual-modules.md)
+
+## Introduction
+
+**Fastify DX for Svelte** is a renderer adapter for [**fastify-vite**](https://github.com/fastify/fastify-vite).
+
+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). 
+
+It also provides a set of built-in utilities for ease of development and managing a universal JavaScript context (SSR to CSR), very much like **Nuxt.js**, **Next.js** and **Remix**. All **Fastify DX** framework adapters implement the [URMA specification](https://github.com/fastify/fastify-dx/blob/main/URMA.md) and have almost the same API, with only minimal differences due to specific framework APIs or idioms.
+
+It is a **fast**, **lightweight** alternative to Nuxt.js packed with **Developer Experience** features.
+
+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 Routing](https://github.com/EmilTholin/svelte-routing).
+
+[**See the release notes for the 0.0.1 alpha release**](https://github.com/fastify/fastify-dx/releases/tag/svelte-v0.0.1).
+
+> At this stage this project is mostly a [**one-man show**](https://github.com/sponsors/galvez), who's devoting all his free time to its completion. Contributions are extremely welcome, as well as bug reports for any issues you may find. 
+
+In this first alpha release it's still missing a test suite. The same is true for [**fastify-vite**](https://github.com/fastify/fastify-vite). 
+
+It'll move into **beta** status when test suites are added to both packages.
+
+## Quick Start
+
+Ensure you have **Node v16+**.
+
+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:
+
+```bash
+degit fastify/fastify-dx/starters/svelte
+```
+
+> **If you're starting a project from scratch**, you'll need these packages installed.
+>
+> ```bash
+> npm i fastify fastify-vite fastify-dx-svelte -P
+> npm i @sveltejs/vite-plugin-svelte -D
+> ```
+
+
+Run `npm install`. 
+  
+Run `npm run dev`. 
+
+Visit `http://localhost:3000/`.
+
+## What's Included
+
+That will get you a **starter template** with:
+  
+- A minimal [Fastify](https://github.com/fastify/fastify) server.
+- Some dummy API routes.
+- A `pages/` folder with some [demo routes](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte/client/pages).
+- All configuration files.
+
+It also includes some _**opinionated**_ essentials:
+
+- [**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/).
+
+- [**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). 
+
+- [**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/).
+
+
+## Package Scripts
+
+`npm run dev` boots the development server.
+  
+`npm run build` creates the production bundle.
+  
+`npm run serve` serves the production bundle.
+
+## Meta
+
+Created by [Jonas Galvez](https://github.com/sponsors/galvez), **Engineering Manager** and **Open Sourcerer** at [NearForm](https://nearform.com).
+
+## Sponsors
+
+<a href="https://nearform.com"><img width="200px" src="https://user-images.githubusercontent.com/12291/172310344-594669fd-da4c-466b-a250-a898569dfea3.svg"></a>
+
+Also [**Duc-Thien Bui**](https://github.com/aecea) and [**Tom Preston-Werner**](https://github.com/mojombo) [via GitHub Sponsors](https://github.com/sponsors/galvez). _Thank you!_

docs/svelte/meta-tags.md

@@ -0,0 +1,30 @@
+<sub>**Go back to the [index](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).**</sub>
+
+<br>
+
+## Meta Tags
+
+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.
+
+> 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).
+
+### `getMeta()`
+
+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.
+  
+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.
+
+```html
+<script context="module">
+export function getMeta (ctx) {
+  return {
+    title: 'Route Title',
+    meta: [
+      { name: 'twitter:title', value: 'Route Title' },
+    ]
+  }
+}
+</script>
+
+<p>Route with meta tags.</p>
+```

docs/svelte/project-structure.md

@@ -0,0 +1,61 @@
+<sub>**Go back to the [index](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).**</sub>
+
+<br>
+
+## Project Structure
+
+The [starter template](https://github.com/fastify/fastify-dx/tree/dev/starters/svelte) looks like this:
+
+```
+├── server.js
+├── client/
+│    ├── index.js
+│    ├── context.js
+│    ├── root.svelte
+│    ├── index.html
+│    ├── layouts/
+│    │    ├── default.svelte
+│    │    └── auth.svelte
+│    └── pages/
+│          ├── index.svelte
+│          ├── client-only.svelte
+│          ├── server-only.svelte
+│          ├── using-data.svelte
+│          └── using-store.svelte
+├── vite.config.js
+└── package.json
+```
+  
+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. 
+
+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].
+
+[virtual-modules]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/virtual-modules.md
+
+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**. 
+
+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. 
+
+> Right now, it's mostly a **boilerplate file** because it must exist but it will also probably never need to be changed.
+
+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).
+
+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. 
+
+> You can expand this file with additional `<meta>` and `<link>` tags if you wish, provided you don't remove any of the placeholders. 
+
+This files links to `/dx:mount.js`, which is a virtual module provided by Fastify DX. 
+
+Virtual modules are covered [here][virtual-modules].
+  
+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].
+
+[routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/routing-config.md
+
+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.
+
+[routing-config]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/routing-config.md
+
+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.
+
+[route-context]: https://github.com/fastify/fastify-dx/blob/main/docs/svelte/route-context.md

docs/svelte/rendering-modes.md

@@ -0,0 +1,39 @@
+<sub>**Go back to the [index](https://github.com/fastify/fastify-dx/blob/main/packages/fastify-dx-svelte/README.md).**</sub>
+
+<br>
+
+# Rendering modes
+
+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.
+
+## `serverOnly`
+
+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.
+
+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.
+
+```html
+<script context="module">
+export const serverOnly = true
+</script>
+
+<p>This route is rendered on the server only!</p>
+```
+
+[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).
+
+## `clientOnly`
+
+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.
+
+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.
+
+```html
+<script context="module">
+export const clientOnly = true
+</script>
+
+<p>This route is rendered on the client only!</p>
+```
+
+[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).