When customizing Shoptet projects with code, one of the limitations is the inability to manipulate the HTML outside of dedicated fields (e.g. global <head> code). Using Cloudflare as a proxy opens up this possibility. With Cloudflare Workers and Workers Routes, it is possible to programmatically modify the HTML before it reaches the user. The purpose of this package is to provide a starting point for developing customization workers.
Benefits of using Cloudflare workers for HTML rewriting include
- Avoid flashing and moving elements due to client-side JavaScript customizations.
- Less burden on client devices. This is especially noticeable on older mobile devices or on slow networks, where client-side JavaScript customizations inadvertently increase page load times.
One potential drawback is that the browser must wait a bit longer for the HTML document itself. However, this time can be minimized to tens of milliseconds.
This will give you a simple Cloudflare Worker that can be run locally:
- Requirements:
- Node.js installed on your system
- Clone this repo and navigate to its root directory
- Run
npm i. - Run
npm run dev:localDue to Cloudflare restrictions, you must usenpm run dev:remotewhen developing against the site that is already using Cloudflare as a proxy. - At http://localhost:8787/ you should see a modified showcase project https://classic.shoptet.cz/ The project can be switched by changing
SHOP_URLenv variable inwrangler.toml. - You can play around with
src/index.tsand see your changes applied.
- Requirements:
- Shoptet project using Cloudflare as proxy (see Shoptet docs)
- Cloudflare account with access to project's Cloudflare dashboard. You will need
All domainsaccess withCloudflare Workers Adminrights.
- Run
npm run dev:remotefor local development. - Run
npm run deploy:productionto deploy using Wrangler. - Once you have deployed the worker, set up Workers Routes in the Cloudflare dashboard of the selected domain. This tells Cloudflare which routes to trigger your worker on. It is important to exclude common system routes, assets, etc. to save resources and prevent unexpected behavior. Recommended disabled routes are listed here.
Example of typical settings of Workers Routes (see docs for matching rules):
This example uses node-html-parser, which parses the entire HTML document into memory. It offers similar possibilities as DOM manipulation in the browser (querySelector etc.). This makes it suitable for large changes in HTML documents. Average slowdown of TTFB with node-html-parser is about 50-70ms. We recommend it for most use cases.
Switch to the with-html-rewriter branch to use Cloudflare's own HTMLRewriter. Its main appeal is that it rewrites HTML while streaming the response, making it faster in comparison to libraries like node-html-parser or cheerio. On the other hand, its modifying capabilities are limited. For example, by definition, you cannot change an element based on another element further down in the HTML document, because the former is already sent to the user when the latter is processed. The average slowdown of TTFB with HTMLRewriter is about 15ms. We recommend it for cases where only very simple HTML changes are required.
To deploy your worker to a staging environment (where you can show your changes to a client, for example) instead of production, you can use worker environment variables. In the example, this is what npm run deploy:staging does. It will publish your worker to a workers.dev URL where it will run in dev mode, similar to localhost. See the Cloudflare documentation for more information on deployments and environment variables.
- Adding livereload to
dev:remote(currently not available) - Example of developing and deploying worker together with client-side customizations (JavaScript and CSS) in an unified workflow. This is doable since Cloudflare Workers can serve static assets.
- Deployment with GitHub actions