From 44ff8b42baf9c1e63c286c59194c7174d4543ad2 Mon Sep 17 00:00:00 2001 From: kj Date: Wed, 3 Jan 2024 16:33:46 -0800 Subject: [PATCH 1/2] Updates documentation for the preflight pattern based on user feedback. --- app/docs/md/conventions/preflight.md | 44 +++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/app/docs/md/conventions/preflight.md b/app/docs/md/conventions/preflight.md index 2852db55..5e611d5a 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 but you may not want to be required to write an API endpoint for. A common pattern that can be solved with preflight is needing authenticated account data on a page that doesn't have an API endpoint. 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: { From 9d890e6a6fa764116fa3be06659f613e58442641 Mon Sep 17 00:00:00 2001 From: kj Date: Thu, 4 Jan 2024 16:49:10 -0800 Subject: [PATCH 2/2] Updates middleware paragraph --- app/docs/md/conventions/preflight.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/docs/md/conventions/preflight.md b/app/docs/md/conventions/preflight.md index 5e611d5a..fce8c388 100644 --- a/app/docs/md/conventions/preflight.md +++ b/app/docs/md/conventions/preflight.md @@ -8,7 +8,7 @@ The preflight function is passed the request object enabling you to populate the 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 but you may not want to be required to write an API endpoint for. A common pattern that can be solved with preflight is needing authenticated account data on a page that doesn't have an API endpoint. +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.