Fallback HTML

The fallback middleware is designed for single-page applications (SPAs) to serve a base HTML file, ensuring proper search engine optimization (SEO) and a consistent initial load experience. It dynamically injects critical metadata and Blocklet-specific scripts into the HTML response based on runtime conditions and page-specific data.

This middleware is crucial for Blocklets that render their content client-side, allowing them to still provide rich, server-rendered metadata for crawlers and social media previews. It works in conjunction with other middlewares such as Authentication and CSRF Protection to provide a complete web serving solution.

How It Works#

The fallback middleware intercepts incoming requests. If the request is a GET or HEAD request, accepts HTML, and is not for a static resource (as determined by RESOURCE_PATTERN), it proceeds to read a specified base HTML file. It then performs several dynamic modifications to this HTML, including injecting page-specific metadata, Open Graph tags, and Blocklet SDK client-side scripts. It also incorporates a caching mechanism to improve performance for subsequent requests.

fallback Middleware Function#

The fallback function returns an Express middleware that serves your SPA's index HTML file.

Parameters

Name	Type	Description
file	string	The path to the fallback HTML file (e.g., index.html). This file must exist.
options	FallbackOptions	An optional configuration object for the middleware.

Returns

Name	Type	Description
middleware	(req: Request, res: Response, next: NextFunction) => Promise<void>	An Express.js middleware function that handles the fallback HTML serving logic.

FallbackOptions Interface#

Name	Type	Description	Default Value
root	string	Optional. The root directory where the file is located. If not provided, file is treated as an absolute path.	undefined
getPageData	(req: Request) => PageData | Promise<PageData>	Optional. An asynchronous function that returns dynamic page-specific data (title, description, ogImage, embed) based on the incoming request.	() => Promise.resolve({})
timeout	number	Optional. The maximum time (in milliseconds) allowed for the getPageData function to execute.	5000
maxLength	number	Optional. The maximum allowed length for title and description fields returned by getPageData.	1000
cacheTtl	number	Optional. The time-to-live (in milliseconds) for cached HTML responses. If 0 or not set, Cache-Control: no-store headers are used to prevent client-side caching.	60 * 1000 (1 minute)
injectBlockletJs	boolean	Optional. Whether to inject the Blocklet SDK client-side JavaScript.	true

PageData Interface#

The PageData object returned by getPageData allows you to customize the HTML metadata.

Name	Type	Description	Default Value
title	string	Optional. The title of the HTML page.	env.appName
description	string	Optional. The description for the HTML page's meta tag.	env.appDescription
ogImage	string	Optional. The URL for the Open Graph image.	env.appUrl + / + SERVICE_PREFIX + /blocklet/og.png
embed	string	Optional. A URL for blocklet-open-embed meta tag, used for Blocklet Open Embed integration.	undefined

Example Response for PageData (from getPageData function)

HTML Injection and Modification#

The fallback middleware dynamically modifies the base HTML file to enhance SEO and integrate Blocklet-specific functionalities. The process involves reading the HTML, applying transformations, and then serving the modified content.