TL;DR [too long; didn't read] 🤯
The main thing you can take away from this article is that we recommend you always keep
@zengenti/contensis-react-base package up to date in your web app.
Today we're open sourcing our Contensis React Base package. Developed over several years of working on enterprise React apps, it's designed to cut the time and effort required to set up and build complex websites. Read on to learn more about what it's for, where it came from, how you can use it and how to contribute to the project.
This snowballs into a mind-bending myriad of development tools, project features, build tools, and bundler plug-ins to configure – all shrouded in unfamiliar jargon and an ever growing list of “npm packages” to understand and keep updated. You may have experimented with some code in another project, but found you spent more time fixing errors or struggling with syntax than actually writing your app. There are probably some things you wish you knew more about before embarking on a serious project.
On the other hand, if you’re an experienced React developer, your project may require a sophisticated arsenal of features that extend beyond rendering some JSX in a browser. Sourcing or maintaining your own project starter that contains everything you need is like keeping a fermented old yeast dough or making a classic spice paste – it’s great, but it is a lot of extra work and will eventually become stale unless it is continually maintained.
So, do you go with one of the well established “create-react-app”, “nodejs starter”, or “react boilerplate” routes, which are well supported and maintained, but can later prove restrictive or complicated to build up and scale out? Or do you go with a niche GitHub repo you’ve found that appears to have most of the application ecosystem that you need, but with zero following or support?
Time, effort, repeat.
Whichever path you take, all of this takes time. Lots of time – and perhaps a little obsessive tenacity – even for the most experienced developers, this process is arduous. In a constantly evolving blend of discrete concepts and methodologies, many developers would welcome opportunities to shortcut some of that time and energy-sapping “project setup”, while still keeping up-to-date and in line with security patches, new features and community best practices.
For us here at Zengenti, most of our customers are primarily focused on delivering websites using Contensis. We help our clients meet their organisational needs with content modelling and this content is later translated into component design. The information architecture – or menu structure to a heathen like me – is constructed separately from content in Contensis using Site View, and all of this data is available via the Contensis Delivery API. If you’re looking to achieve similar goals, this is how we build websites with Contensis.
The base package
It doesn’t sound that difficult to implement in your own app, but what happens when the application grows? What happens when we need to introduce things like:
- 10 different content types, each with different link depths and field limitations
- Handling parameterised routes for searching or activating different parts of a page
- Fetching node ancestors for breadcrumb data, siblings for side navigation, or an entire site tree to build site navigation
- Requiring authentication for certain content
- Hooking into a development CMS or read data from another CMS project
- Writing page cache invalidation headers or custom response handlers
As the requirements increase, so too does the amount of code we have to write, test, and maintain. More code inevitably means more complexity, and this becomes a barrier to easily making changes in the future.
Supporting all of those features requires us to invest time in helping ourselves by putting good development tools in place such as implementing adequate debugging facilities for both server and browser contexts, automated tests to prevent us deploying a bad build, automatic code linting to ensure consistent and readable code…I could go on.
You may need more than one application like this to serve your entire organisation, so you’ll have to copy this code into each application you write, duplicating all that technical debt for each copy that has been made.
The trouble with duplicated code like this is that it’s frozen in time – remaining exactly the same until someone copies and pastes an updated version of it, despite receiving numerous CMS upgrades in the interim. Or, more often, it gets tweaked over time and mutated to the point it can never be updated and must be painstakingly tweaked again and again forevermore.
We realised very early on that we needed to capture and package this code to prevent the exponential technical overhead that would be incurred with each copy of these “base” features we took to use elsewhere. We don’t need to reinvent the wheel with every application we write.
And that’s where the package formerly known as
zengenti-isomorphic-base was born. We trialled this internally for quite some time and, with some steering from our technology guild, it eventually evolved into what we now call Contensis React Base.
The aim of Contensis React Base is to provide the complex base features and boilerplate concepts so we can offer an easy and reusable way of hosting and rendering our isomorphic React applications. It provides the ability to scale them out to cover more areas of an organisation’s digital strategy or web estate, while incurring the minimum amount of technical debt. And, at the same time, gives us the ability to govern the code that underpins the core of our applications, make improvements and roll out updates so we can grow in parallel with Contensis and the wider community with the minimum of effort.
The package manages:
- the installation of production dependencies including React, react-router-dom, immutable, and react-redux
- a server-side Express application which serves an isomorphic web app
- a client-side sub-package that handles client-side rendering and hydration
- the creation of Redux store and global state management for core features
- automatic routing via RouteLoader component which will load entries based on a given URL
- automatically retrieving navigation data from the Node API to load the Site View into the state
- automatic cache key generation for any entries and nodes the core app handles, ensuring instant cache invalidation when content is updated
So it's now open source?
Many of our customers are developers themselves, and as a developer if you are trying to achieve something a little quirky, or follow an unfamiliar path, it can be frustrating if you feel you are working inside a black box. Or, as time goes on, you find yourself looking to exploit or expand certain areas of configuration to use functionality nobody else has needed before.
With all of that we would welcome input from our users who have found new or better ways of solving common problems and we would be pleased to review a pull request for a fix made to our source code, for example.
Notice how I have said “our” source code - if you’re reading on this far that also includes you!
We would like to officially announce Contensis React Base is officially available on GitHub, it is listed publicly and is the source of truth.
Feel free to clone or fork the repository, have a play and a poke about!
I’m just a normal developer
OK so you might not be that guy, Forky McCloner, a typical 2am open-source contributor.
If your project uses the
@zengenti/contensis-react-base package, we strongly urge you to keep this package up to date. We follow semantic versioning, so you can be sure it is safe to upgrade to the latest version. Major version updates will always include one breaking change and you should always check the release notes to understand if that change affects you. We'll keep the Contensis community updated with any such announcements.
If you are running on a beta version of the package, you should check to see if that beta version has been succeeded by a version with the
latest tag and install that.
We stage all of our changes in npm by publishing a new beta version with every commit to GitHub. Each change is automatically built and published to npm with a
prerelease tag through GitHub Actions CI, and you can install the last beta version in your project for testing new unreleased fixes and features by running:
npm i @zengenti/contensis-react-base@prerelease
If your project is running on a beta version and that has been superseded by a greater version number published with the
latest tag, you should get back onto the release path - a foolproof way to do this is to install it again:
npm i @zengenti/contensis-react-base@latest
@zengenti/contensis-react-base package up to date!
Contensis React Base on npmjs
Check the latest version, view the package README and see all published versions.
Contensis React Base on GitHub
View the source code and commit history and contribute by making a pull request.
Get in touch
Thanks for reading and consider joining our Contensis Slack community, where you can reach out if you have any specific questions or just to keep up to date with the latest community announcements and event invites.