Let’s say we have a large website that we need to re-platform. Perhaps the competition are delivering a better digital experience, or maybe we’re beginning to struggle with legacy infrastructure. The motivations aren’t important, but the decision has been made, we’re moving to another platform, e.g., Jamstack.
That’s going to take many months, maybe years. The business can’t stand still while we wait for the new site to be ready. So we have to keep adding features to the legacy site while we build the new site in the background.
Every feature we add to the legacy site adds scope to the new site and delays the release, increasing the window to add yet more features before the rebuild is complete. It’s a vicious cycle.
If you’ve ever re-platformed a large website in a competitive market, then this probably sounds familiar. What if there was a way to avoid the problematic scope creep of the ‘big bang’ release and deliver customer value sooner?
The ‘big bang’ release problem
The problem with the ‘big bang’ release is that we’ve got to rebuild the complete functionality of the site before we can release it. That takes time, during which customers and the business will demand new functionality.
If we resist the urge to add new features, we risk losing out to the competition. So we keep building functionality into the legacy site. That delivers customer value but comes with high costs.
First, we’re duplicating the development effort as any new functionality added to the legacy site also needs to be added to the new site. That doubles the development costs. You might assume that’s the end of it, but it’s actually worse. By adding scope to the rebuild, we delay the release, increasing the opportunity to add yet more features and delay the release even further.
Imagine setting off to run a marathon, then reaching mile 26 only to find out that while you’ve been running towards the finish line, it’s been moving away, and you’ve got another 12 miles to run. You’d be pretty upset.
All this, while under the context of rising pressures from the stakeholders within the business as they’re pushing to complete the new site so that the investment put into building it can start delivering value to customers.
An incremental alternative
What if, instead of waiting for the new site to be completed, we could release the new site in sections, replacing the existing site bit-by-bit?
With HTTP rewriting, we can direct traffic to the same domain to different destinations on the server-side, based on the request path. So if we break the site up into sections based on the URL paths, we can deliver the new site incrementally in these sections, using this path-based routing.
We could break a site up into sections multiple ways, but the most straightforward is likely by-product (e.g., Search, Customer Portal, etc.).
Let’s take the sitemap of a typical e-commerce website. We could break that up into the following sections:
Each section maps to a set of URL paths on the existing website, e.g., Browse, which contains the following:
Once these page routes are built and signed off for release, we can update the path-based routing to direct requests for these pages to the new site while the remaining traffic continues to be served by the legacy site.
You might have spotted some issues with the practicalities here. An incremental release approach is by no means a silver bullet for re-platforming sites. There are some trade-offs to consider.
First, there’s the management overhead of running two sites on different stacks side-by-side in production. Second, we can’t have customers noticing that they’re jumping between two different sites, or this will create a jarring experience.
To create a truly seamless experience, we need to consider the following:
- The layout
- The session
- Third-party tags / scripts
- Cookie management
- Error pages
Let’s tackle these one by one.
Assuming a conventional site design, the layout, i.e., header and footer, needs to be consistent between the sites, in both design and content.
This is straightforward if the design is not changing and the content is static. We simply replicate the legacy site’s header and footer on the new site, and away we go.
If, however, the site is getting a visual refresh as part of the re-platform, as is often the case, or the header or footer contain dynamic content, then more must be done here.
If the design is changing, we have two options. Either we;
- Update the legacy site with the new design,
- Or we replicate the legacy site’s header and footer on the new site, then implement the new design at the end of the project—once the new site is serving all of the pages.
What is best for your site will depend on your circumstances; for example, how easy will the new design be to implement on the legacy site? And so on.
Some sites will have dynamic content in the header or footer. That content could be product categories that appear/disappear based on stock levels, or it could be different actions within the header that show based on whether the user is logged in or not. Whatever the dynamic content is, we have three choices. We either remove it, make it static, or expose it for reuse by the new site, likely via API endpoints.
Ah yes, the session. We can’t have a user partially log in to the site, or need to log in twice. We need a single shared session covering the whole site.
There are three things the new site needs the session for:
- To confirm whether the current session is valid.
- To fetch personalized content.
- To authorize read and write actions.
The complexity involved in sharing the session will vary depending on the site.
Both sites will be on the same HTTP origin (e.g., https://example.com), so both sites will be able to access and use the client-side credentials, i.e., the cookies. However, the presence of the cookie on the client-side does not ensure its validity. That needs to be confirmed by the server.
If the legacy site has authentication APIs, we can likely reuse these. If there are no APIs, we will need to create them. In a scenario where only basic user information is required, this could be as simple as a single
GET /whoami endpoint that returns that information or a
401 Unauthorised if the cookie does not belong to a valid session.
If the new site requires more personalized content, additional APIs will need to be provided.
Third-party tags / scripts
Most large sites have a plethora of additional tags and scripts from third-party tools for analytics, ad tracking, site verification, etc., in both the
End users are rarely aware of these, but we’ll need to make sure these are also in place on the new site’s pages to avoid creating blind spots within our tooling.
Leading on nicely from third-party scripts, there’s cookie consent. Cookie consent popups are annoying enough once, so we need to ensure we’re not putting users through this pain twice.
With the legacy and new site on the same domain, the new site should be able to read the cookie consent status without too much difficulty and then make sure the new pages are dropping cookies accordingly. If the legacy site uses Google Tag Manager, this should be relatively straightforward.
Assuming the site is public, we need to include the new site’s pages in the sitemap. While both sites are running side by side, the easiest approach here is to turn the sitemap.xml into an index that includes the sitemap from each, with each site responsible for creating a sitemap of the pages it’s serving.
Probably the easiest item on the list. The new site will need the same favicons and
<meta> tags as the legacy site.
By far the least important, but if we want to leave no stone unturned, we’ll also want to replicate the 404, 500, and any other custom error pages.
Why it’s worth the effort
You’re probably thinking that sounds like a lot of work, and it is, but when a site is large enough that it’s going to take a long time to re-platform, I’d argue that the multiple advantages of an incremental approach outweigh the drawbacks.
So what are the advantages?
Delivering value, sooner
By releasing each section of the site as we complete it, we deliver customer and business value earlier. No more waiting for the rest of the site to be complete while finished features sit there on the shelf. Development effort returns on its investment sooner.
Large re-platform projects require significant investment. With a ‘big bang’ approach, that investment sits latent as we rush to complete the project before adding even more features. As the costs build, so does the pressure from internal stakeholders. By deploying the completed sections as we go, we deliver value from that investment and release that pressure.
Getting the software into users’ hands earlier shortens the feedback loop, allowing us to validate our assumptions, learn faster, and adjust our course accordingly. A shorter feedback cycle reduces the risk from a product perspective, but we also reduce the risk on the technical side.
Replacing a site all in one go is stressful. Is the routing configured correctly? Will the auto-scaling work? Is the CDN caching correctly? There’s a myriad of things that can go wrong.
Launching the site one section at a time has two advantages. First, we can focus our attention on the infrastructure requirements for a subset of the functionality rather than the whole site. Second, we can build confidence and experience with the new site infrastructure by starting with lower-risk sections before tackling the business-critical areas.
Decommission legacy, sooner
If multiple systems deliver our legacy site, some of those are likely more problematic to maintain than others. If that’s the case, we can prioritize the sections of the site that would allow us to decommission those difficult systems sooner, switching off that infrastructure and saving those headaches earlier than we’d be able to with a ‘big bang’ approach.
‘Banking’ completed progress
Finally, when a critical new feature emerges for a section we’ve already released, we can build that functionality once, not twice—avoiding frustrating and expensive throwaway investment in the legacy site and without causing any delay to the delivery of the new site features that are already complete.
This doesn’t completely ‘fix’ the finish line, but it does significantly slow its acceleration, which allows us to finish the whole project sooner.
Is an incremental approach right for you?
If you’ve made it this far, it’ll be clear that an incremental approach to re-platforming a site is not suitable for every project.
If your site is relatively small or has reached maturity and doesn’t change often, then you’re likely going to be better off with the traditional ‘big bang’ rebuild.
If, however, you have a large site under active development, then re-platforming with an incremental approach may well reduce risks, reduce costs, & deliver customer value sooner.
An attractive trio, if ever I’ve heard one.
Are you considering a re-platform to Jamstack? Discuss it on the Kontent Discord.