@quintype/framework
v7.31.0
Published
Libraries to help build Quintype Node.js apps
Downloads
5,054
Maintainers
Keywords
Readme
@quintype/framework
This is the framework that powers Malibu.
Please see Isomorphic Rendering for an overview of the architecture of this library.
The Documentation is available here: https://developers.quintype.com/quintype-node-framework
Please see malibu for a reference application using this architecture.
Some Topics which are not covered in the documentation (yet), are below
Implementing a new page
In your server.js, you will notice something like the following
isomorphicRoutes(app, {
generateRoutes: generateRoutes,
loadData: loadData,
pickComponent: pickComponent,
});
This highlights the three important places to put stuff for an isomorphic app
- Match the route against a
pageType
, typically inapp/server/routes.js
(see the routing section above) - Load the Data Required for that
pageType
, typically inapp/server/load-data.js
. This returns a promise with required data. - Render the correct component for that
pageType
, typically inapp/isomorphic/pick-component.js
. This must be a pure component
Forcing Updates
Since is difficult to force Service Workers to update, there is a provision to do such a thing. Add the following to the correct places. Whenever a change is to be forcefully pushed, update the version in app-version.js. The next AJAX page load via /route-data.json
will force the service worker to update in the background (and the next refresh will have changes).
Ideally, you will have to push this after purging caches on /shell.html and the service worker.
// app/isomorphic/app-version.js
module.exports = 1;
// app/server/app.js
import {isomorphicRoutes} from "@quintype/framework/server/routes";
isomorphicRoutes(app, {
...
appVersion: require("../isomorphic/app-version")
...
});
// app/client/app.js
startApp(renderApplication, CUSTOM_REDUCERS, {
...
appVersion: require("../isomorphic/app-version")
...
});
// views/js/service-worker.ejs
const REQUIRED_ASSETS = [
{url: '/shell.html', revision: '<%= appVersion %>'},
...
];
Structure of the /route-data.json
The response of the /route-data.json will look like the following:
{
appVersion: 42,
title: "This is the title of the page",
// When multi domain support is enabled, this will be the canonical url of the domainSlug.
// See multi domain support for more information
currentHostUrl: "https://canonical-root.your-host.com",
primaryHostUrl: "https://www.your-host.com",
// your loadData function is responsible for loading this entire data
data: {
pageType: "story-page",
story: {}
}
}
Multi Domain Support
Multi domain support is achieved by assigning a section to a domain via the domain manager in the editor. Once this is done, add the following entries into your publisher/config.yml
.
# publisher/config.yml
domain_mapping:
subdomain.my-domain.com: sub
another.my-domain.com: another
Doing this will enable a field called domainSlug
to be passed to various functions, such as generateRoutes
and loadData
. This can be used to load data specific to the domain.
Further, /route-data.json
will have two more fields at the root level. domainSlug
, which is the slug of the loaded domain. currentHostUrl
specifies which domain you are on. The currentHostUrl
is used by the link field to decide if it should do an ajax navigation or not.
Debugging
- In order to use
assetify
function, please annotate the application-js with id="app-js". The hostname specified here is assumed to be the cdn - All code related to the browser loading the service worker can be found in load-service-worker.js
- All code related to the service worker itself is found in service-worker-helper.js
Miscellaneous
Switching to generateCommonRoutes
Starting in @quintype/framework
v3, we are introducing multi domain support. The configuration for section page locations is now controlled by the editor. Please switch to using generateCommonRoutes
to generate story page, and section page routes.
import { generateCommonRoutes } from "@quintype/framework/server/generate-routes";
export function generateRoutes(config, domainSlug) {
return generateCommonRoutes(config, domainSlug, {
sectionPageRoutes: true,
storyPageRoutes: true,
});
}
OneSignal Integration
OneSignal interferes with our service worker, so a few changes have to be made to enable PWA with OneSignal.
// app/server/app.js
import {isomorphicRoutes} from "@quintype/framework/server/routes";
isomorphicRoutes(app, {
...
oneSignalServiceWorkers: true
...
});
// app/client/app.js
startApp(renderApplication, CUSTOM_REDUCERS, {
enableServiceWorker: true,
serviceWorkerLocation: "/OneSignalSDKWorker.js", // OneSignal will automatically register the service worker
})
FCM Integration
Steps to Integrate FCM in your project
- app/client/app.js While executing startApp in your project send the firebaseConfig via opts.
firebaseConfig
can either be an object or a function that returns the firebase config object
Example:
startApp(renderApplication,
CUSTOM_REDUCERS,
{
enableServiceWorker: process.env.NODE_ENV === "production",
firebaseConfig: {
messagingSenderId: --YOUR KEY-- ,
projectId: --YOUR KEY--,
apiKey: --YOUR KEY--,
storageBucket: --YOUR KEY--,
authDomain: --YOUR KEY--,
appId: --YOUR KEY--,
}
...
})
- app/server/app.js should have the fcm configuration as below:
isomorphicRoutes(app, {
...
fcmServerKey: (config) => <ServerKey> || fcmServerKey: <ServerKey> {(function|string)}
...
});
You should have service worker script named firebase-messaging-sw.js in /public
Example of the script:
importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-app-compat.js"); importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-messaging-compat.js"); firebase.initializeApp({ messagingSenderId: --YOUR KEY-- , projectId: --YOUR KEY--, apiKey: --YOUR KEY--, storageBucket: --YOUR KEY--, authDomain: --YOUR KEY--, appId: --YOUR KEY--, }); self.addEventListener('notificationclick', (event) => { const url = event.notification.data.url; if(url) { clients.openWindow(url); } clients.openWindow(-- YOUR Sketches Host --); }, false); const messaging = firebase.messaging(); messaging.onBackgroundMessage(function(payload) { const data = payload["data"]; const notificationTitle = data.title || "" const notificationOptions = { body: data.body, icon: data["hero_image_s3_url"], image: data["hero_image_s3_url"], data: { url: data["click_action"], } }; self.registration.showNotification(notificationTitle, notificationOptions); });
Make sure that the page data should have config with key fcmMessageSenderId refer doStartApp function in app/client/start.js.
Skipping loading data from /route-data.json
This can be used where /route-data.json
is not accessible (example preview).
Add the following:
<script type="text/javascript">
var staticPageStoreContent = <%- JSON.stringify(store.getState()) -%>;
</script>
The store will be initialized from staticPageStoreContent
Using Assets in JS and CSS
(to be documented)
Minimizing Page Load Speed
Make sure you do all of the following techniques to reduce page load time (notes to document these later)
Inline CSS
Add a window.initialFetch to do a fetch in the background
Add a initial-page to preRender chrome such as the menu without waiting for AJAX responses
<script type="application/json" id="initial-page">
{ "config": {} }
</script>
Use static-page to show a full page (this will prevent fetchData from calling)
<script type="application/json" id="static-page">
{ "config": {} }
</script>
Never require lodash directly. Always do lodash/get
Do not use moment. Use date-fns
LazyLoad Images
Separate polyfills
Use Link headers to do HTTP2 server push to prioritize important requests
Preloading app.js and /route-data.json can be triggered by passing preloadJS true, and preloadRouteData true to isomorphic handler
Options
manifest-fn
forwardAmp
multiple publishers
FIXME: Write notes on host_to_api_host
, host_to_automatic_api_host
, wildcard_to_api_host
and skip_warm_config
forwardFavicon
Optimising front-end javascript
- https://developers.google.com/web/fundamentals/performance/optimizing-javascript/tree-shaking/
Migration to framework@3
- Run the following to execute the script:
sh <(curl https://raw.githubusercontent.com/quintype/quintype-node-framework/master/scripts/framework-2-to-3-migration)
- Verify Changes with
git diff --cached
References
- This architecture is heavily influenced by the method described in this video
- Code for the available video is available here
- I know there is a good tutorial video I've seen. But I can't remember where.
- Great intro to pwa