diff --git a/app/docs/md/conventions/preflight.md b/app/docs/md/conventions/preflight.md
index 2852db55..fce8c388 100644
--- a/app/docs/md/conventions/preflight.md
+++ b/app/docs/md/conventions/preflight.md
@@ -3,8 +3,12 @@ title: Preflight
---
-The purpose of the preflight file is to supply default application state.
-It can also be used to customize data based on the request per route.
+The purpose of the preflight file is to populate the server-side store with default application state.
+The preflight function is passed the request object enabling you to populate the server-side store with customized data per route.
+
+You can use the preflight file as a way to incrementally build your data layer. Start with a static version of your store data to get everything working then progress to using API functions and a database as needed.
+
+Preflight can also work as a global middleware replacement for pages that require data in common with other pages that otherwise would not require an API route. A typical pattern that can be solved with preflight is needing authenticated account data on multiple pages without writing an API endpoint for each page.
Enhance looks for the preflight file in the root of your app.
@@ -14,7 +18,8 @@ Enhance looks for the preflight file in the root of your app.
app
├── api ............... data routes
│ └── index.mjs ..... override default preflight application state with api data
-└── preflight.mjs ..... pre-populate application state
+├── preflight.mjs ..... pre-populate server-side store
+└── head.mjs .......... custom component
```
@@ -22,25 +27,24 @@ app
The preflight function is passed the request object enabling you to customize data per requested route.
API responses are merged with the default state returned from preflight allowing you to override default state with specific API data per request.
-### Basic example
+### Basic example
```javascript
- export default function Preflight ({ req }) {
+ export default async function Preflight ({ req }) {
return { /* ...Your data here */ }
}
````
-
### Setting the page title using preflight
```javascript
- export default function Preflight ({ req }) {
+ export default async function Preflight ({ req }) {
return {
pageTitle: getPageTitle(req.path),
account: {
@@ -62,6 +66,30 @@ API responses are merged with the default state returned from preflight allowing
````
+### Access the page title from the store
+
+The data object you return from preflight will be available to your elements and the `head.mjs` file via the `state.store`
+
+
+
+ ```javascript
+ export default function Head(state) {
+ const { store = {} } = state
+ const { pageTitle = 'Enhance Starter Project' } = store
+ return `
+
+
+
+
+
+ ${pageTitle}
+
+
+ `
+ }
+ ```
+
+
### Overriding default preflight data with an API response
@@ -69,7 +97,7 @@ API responses are merged with the default state returned from preflight allowing
```javascript
- export default function Preflight ({ req }) {
+ export default async function Preflight ({ req }) {
return {
pageTitle: getPageTitle(req.path),
account: {