Merge pull request #187 from enhance-dev/preflight

Updates documentation for the preflight pattern based on user feedback.
enhance-dev · Jan 5, 2024 · b33dcbc · b33dcbc
2 parents 08b6da3 + 9d890e6
commit b33dcbc
Showing 1 changed file with 36 additions and 8 deletions.
diff --git 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,33 +18,33 @@ 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 <head> component
 
 ```
 </doc-code>
 
 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
 
 <doc-code filename="app/preflight.mjs">
 
   ```javascript
-  export default function Preflight ({ req }) {
+  export default async function Preflight ({ req }) {
     return { /* ...Your data here */ }
   }
 ````
 </doc-code>
 
 
-
 ### Setting the page title using preflight
 
 <doc-code filename="app/preflight.mjs">
 
   ```javascript
-  export default function Preflight ({ req }) {
+  export default async function Preflight ({ req }) {
     return {
       pageTitle: getPageTitle(req.path),
       account: {
@@ -62,14 +66,38 @@ API responses are merged with the default state returned from preflight allowing
 ````
 </doc-code>
 
+### 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`
+
+<doc-code filename="app/head.mjs">
+
+  ```javascript
+    export default function Head(state) {
+      const { store = {} } = state
+      const { pageTitle = 'Enhance Starter Project' } = store
+      return `
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>${pageTitle}</title>
+        </head>
+        <body class="font-sans">
+      `
+    }
+  ```
+
+</doc-code>
 
 
 ### Overriding default preflight data with an API response
 
 <doc-code filename="app/preflight.mjs">
 
   ```javascript
-  export default function Preflight ({ req }) {
+  export default async function Preflight ({ req }) {
     return {
       pageTitle: getPageTitle(req.path),
       account: {