Uniting the team with Jamstack - Trys Mudford - Conference Talk
Hi there. I'm tris. I'm a front-end developer at clear left where we help design leaders, get the most from their products and teams. Through work as an agency. And through our events. I'm going to talk today about how we went from a blank sheet of paper, to a multi-site. Headless cms, and a hyper-performant. Accessible, site. In just a number of days. I'll also touch on how, developers, can communicate, better with stakeholders. And the content, team. And use a web project, as an agent for change in an organization. Like all good stories, ours starts with a meeting. Thanks to kovid. Our portfolio. Of physical events had to be postponed. But like with this conference, an opportunity, arose. Clearleft, decided, to organize, our first, virtual, conference. Sofa conf. An ambitious. Five-day. Online, affordable, event, covering topics such as service design. Product strategy, and research. We had about eight weeks to bring it all together. It was 9am, and we gathered online, to kick off the project. With no more than a name, we began discussing. What we'd need to pull it off. Firstly. We need a website. Event websites, are a bit of a speciality. For us. Having organized, events for the past 15, years, we've built more than our fair share of them. But lately. Most new sites have been created, as annual additions, on top of established, platforms, the 2019. The 2020. Edition. This project however was different. It was a totally new prospect, with no foundations. Or starting, points or leg ups. Or, no baggage, or constraints, depending on how you look at it. It's rare, to have a project, where all bets are off and you have total, freedom. When they come along. Grab them. Developers, tend to be known as the no brigade. The ones that come to a meeting and pour cold water on the ideas of others saying, it's too complicated, or it will take too long. Come at a project meeting with an attitude, of experimentation. Enthusiasm. And excitement. Listen out for those moments where, you as a developer. Can add real value. The big issue we had for sofa conf was time. It was one of those, if we could launch this like, yesterday. That would be great to sort of meetings. We discussed, just building a hard-coded. Site in classic, html. Just to get out the door quickly, and then retrofitting. A cms. Later on. And that is a decent option if you're really strapped for time. But, strangely. I find it's often easier, to get time for a new build, than it is to get time to pay back technical debt. Once something's, launched. Unless it's causing, major problems, it tends to just get forgotten, about. Now our standard, stack for an event site is craft cms. A php. Server rendered, content management system. But it has big downsides. With the cms, and front end tightly coupled together. We end up blocking, the content team, until we've done our job building the whole site. Which often leads to a frantic, few days for them just before launch. We had a long-term, plan to create a centralized, headless cms, that would speed up development. And remove this blocker for our colleagues. But, finding time for it in the company, just wasn't really a priority. As i said, unless it's broken. Things tend to just get left alone. But as a front-end development, team, we didn't abandon that plan. We had a vision for this project. And when the opportunity, arose, we took it. Why. Because making the lives of your colleagues, easier, is a massive and often overlooked, incentive. We work on a global, web where we have no real idea if we're hitting the mark with the things that we create. How cool is it that we can remove the pain points from our peers, with an immediate, feedback, loop. And we're primarily, a front-end development, team at clear left so, why would we care about building a headless cms to begin with. Well as counter-intuitive. As working on a back end project was. In the long term, building a more complex cms, once. Freed us front enders up to work on the things we actually love doing. So despite the slightly ridiculous, time frames and the sheer amount of work building, sofa conf, and this generic, event system, was going to take, this opportunity, was just too good to miss, but, which stack to which, stack to choose. Tech stack choice, impacts the business. You need to be confident, that a decision, isn't being based on the shiny shiny. But on objective, truths that make sense for your organization. Changing, everything, can be a huge risk to a business. And you might be in that situation, where, suggesting, a wholesale, shift to a new stack. Is going to be met with stubborn retorts, like i know that feeling, i spent. Six years in a wordpress, only design studio. We were comfortable, and pretty effective, at building, bespoke, wordpress, themes, but it meant we were totally, blinded, to other better options.
Along With other obvious wins like increased performance. Less downtime. Cheaper hosting. Changing a stack, also has the ability, to unite, a team. Change is your secret, fuel, people want to be part of change, teams gather around ideas, that will change things. As a developer, taking time out to attend this this conference, i have no doubt that you want to try the latest, and the greatest technologies. And hopefully use them responsibly. So, i have some tips for bringing the rest of the organization. Along with you. Number one. Try out the tech first. Side projects or internal projects, are a brilliant place, to try out new tech, before putting into production, with a paying client, or your own company. Use them as a way of dipping your toe into the water. Seeing what works and more importantly, what doesn't. Side projects, give you confidence, to step up, and put forward a bolder solution, when it matters. Number two. Prototype. Jumping, straight into a new build is risky. So use prototypes, as a way of breaking down the problem, before you have to commit to it. Write, throwaway, code, that answers any of those like gut check fears you might have. It doesn't have to be a full, to end solution, either. Just enough, to get you to a point of being confident, that you can deliver, on the whole thing. Number three. Do your research. Unfortunately. Gathering requirements, for the web is a whole separate talk but i've written a blog post on the subject should you wish to find out more. To summarize. I start by gathering the whole team, designers. Stakeholders. Marketers, developers. And we work out on non-functional. Requirements, i.e. How the system, should work, and then our functional requirements. What the system should do. Then i'll gather a long list of stack options. And then mark them up with a weighted, ranking, to ensure that all our requirements, are going to be met. Now, break down those top results, from the ranking. Further with pros and cons, discuss the risks, as much as the benefits. And this should all feed into the beginning of a conversation. With the rest of the team. And number four. Change, one thing at a time. The scientific, method of control. Pays dividends, if you've got wary stakeholders. Changing, one thing, minimizes, risk, and can hold the key to unlocking the go ahead on a project. That doesn't necessarily, mean, only changing one thing. But changing one thing that affects, your stakeholders. Take a new cms, for example. Making the jump from one platform to another is a big step. Not only is there like a mass migration, of content, a full rebuild, new infrastructure. There's now a whole bunch of training that has to happen, to get the rest of the company, up to speed with the new system. For sofa conf, we could have even, could have either chosen a cloud cms, designed to be consumed in a headless way. Or kept the cms, the same as it is currently. And then added a headless endpoint. The first changes, everything. The second, exercise, is control. Now these tips are all a way of increasing, your confidence, with a platform, before you pitch it to others.
This Isn't so you can go into a meeting like brashly, lay out your master plan. But to give you the doubting developer. The quiet confidence. That your solution, has solid foundations, and it's worth considering. The net result for soficom. We went for craft cms, as our headless platform. It's familiar to the team so there was no retraining, required, and it fulfilled, all the headless, requirements, that we set out before profiling, all the options. Now when we pick the front-end stack for soficonf. The principle, of least power guided our thoughts. Choose the least powerful language, suitable. For a given purpose. Solid, accessible, html. Should be the base of any web stack. And if everything fails, and at some points it will. Your users will still get the core content. And with that in mind a single page application, was off the table, and it left us with three routes. Number one a, traditional, server render. Two a modern server-side, render. And three, a jam stack approach. Server rendering, means managing, a live web server, which requires, time, skills, and resources. And as nice as next and nox jsr, to develop in, they can be quite expensive, and a bit of a pain to host still. But more importantly. A live web server, also means a live api, which is another point of failure, and jam stack, removes, that. Jam stack, is an approach, or a methodology, for building websites. Where you aim to pre-render. As much of the site up front, and serve it via a content delivery network, or cdn. This removes, the need to manage web servers, that render on the fly. Allowing you to scale quicker, and at a lower cost while delivering, an accessible. Content, first experience. The name jam stack comes from these three pillars. The j, javascript. Meaning the client-side, code that enhances, the experience. The eighth apis, meaning the distributed. Business logic for complex, interactions. And the m for markup. Meaning the pre-rendered, html, that gets sent down the wire from the cdn. Now two of those parts are mandatory. The only important factor is to serve html. Through a cdn. It means a wordpress, site, a no js site, or a single page application, are not jam spectrum. But as well as that original definition, of jam stack, i think there's another way to frame it. The j for javascript. Meaning developers, you and i. The a for apis. Meaning the the business of the business interests the stakeholders. And the m4 markup meaning the content, team. Three parts of the web process. All connected together, through a single stack. See by design. I think jamstack, provides an opportunity, to bring the team, together, more closely than on a traditional, build. And i think a jam stack approach helps you think more systematically. A web page is fed by multiple data streams. In a traditional, cms, you'll make a database, query for the header, and then the content. The related, content the footer. And each query there comes with an. Inevitable, performance, here, it's generally minor but they do mount up and some queries can be quite expensive.
So To minimize, impact, we tend to use monoliths. With centralized, data. Connecting, to one database, is costly enough so why would you connect to multiple. But in a jam stack driven site, we don't have those limitations, in the same way because we're pre-rendering. Content can be fed from several places. Markdown, files, image repositories. Api, calls graphql. Queries. This means we can store, content, in its rightful, place. And those heavy database, queries i mentioned earlier. It's not a problem for jam stack, as the fetching happens at build time not at run time. You can scale down those big api, and content servers that currently have to serve every single request. And go for a cheap, server that only gets hit when the site is rebuilt. And if you need to convince your financial, stakeholders. This can be a powerful motivator. But as a user centered developer. The key differentiator. Of jam stack over other methodologies. Is the user, over, developer, attitude. With jamstack. We take on the performance, hit, so our users don't have to. That longer build time that it has, isn't there for a mistake, it's it's there for a reason. If it's minutes for us, but we're saving, seconds, for thousands, of our customers. I think it's a price worth paying, i think it makes economic, sense, but it's also the right thing to do. And in the monolith, world, there's a bit of a glass ceiling for creating a high performing, website. Surprise, surprise. Time and money tend to be the limiting factors. And if you're a freelancer. Or working in a small agency. Shared hosting is often all that's attainable, and affordable. But jamstack. Puts, global performance. Into the hands of the masses. It's in reach for all those developers, like i was who don't have vast budgets or time for performance, optimization. When you've just got to ship that next website. Now back to the story. Writing, technical specifications. Seems like a job for a developer, right. Well, kinda. Sure deciding. Database, entities, and components. Might be a technical, job, but it's also a great opportunity, to bring in the experience, of the rest of your team for a better result. This is one of the personal highlights of this project for me. I spent a couple of hours, mapping out the system with my colleague sophia. The events coordinator, who would ultimately, be the one who was using the system. With her, wealth of events knowledge and my ruthless, determinism. To make things as generic, as possible. We landed on a list of models, and fields. She was able to share what caused her pain with the previous cns's, that have been built for her, and i was able to put forward fixes. Without her input i'd no doubt have created a bunch of future headaches for her, and what a joy to be able to alleviate, those at the start of a project. We designed, the cms, there and then, and were able to share the entities, and the endpoints. With the designer, to let them know what data they had to play with. Now once planning was complete. My first goal was to deploy the cms, as soon as possible. We all know that good web development, takes some time, and there can be an unfortunate, but not always, unfounded, attitude, in our companies, that, developers, always deliver late.
So My aim is to get the spotlight, off me reasonably, early. The sooner i can deploy, the content editing experience, the better, but only if it works. The worst thing i can do is deliver something that's. Faulty, or needs patching. So i've also found that developers. Enjoy, that, big reveal, moment where we show off our finished, creation to the rest of the company. And we get that huge rush of dopamine, when all those wows come in. But really under the surface. I think it kids us to feel like we're more in control, of the deadline, than on a more iterative, project. Like we hold all the cards until the very end of the project. But it always, tends to be followed by a list of bugs or snagging, items, souring the end of the project as we then rush to get it over the line. Aiming for an anti-climactic. Go live, is actually a really sensible, approach. Nothing went wrong, doesn't sound all that exciting, but it makes business sense and it's far less stressful for you as a developer. And with a deploy, early mindset. You can adapt, your code and design, as the content arrives, by pointing your local dev environment. To the staging, content, area. Rather than baking that content, api, endpoint. Into the application, directly. Expose, it as an environment, variable, so it can be injected, externally. Dot m files, or package.json. Scripts, are great for this, and a good example, of an approach i call just scalable, enough. We can get fixated, on scalability. In our projects, particularly, when we see conference, talks about how the big tech companies do x or y, it leads us to totally, over engineer, our own code. Plan for appropriate. Scale. Optimizing, the things that will actually cause you pain in the future. Now taking into consideration. Our earlier research. Concluding that a jam stack approach was going to be right. And taking into, consideration, the clear left front-end team skill. Hugo. 110. And gatsby. All look like good contenders. Unfortunately, hugo, as nice as it is, can't ingest, an api, to create pages, on the back of it, and gatsby, ships with just too much javascript. Unnecessary. For rendering, a content driven website like this. And that point about creating, pages, from an api. Is the key differentiator. Of 11t. From a lot of static site generators. As well as ingesting, markdown, really well. 11t, allows you to pull in api data sources, and then render pages, off the back of them. So let's go through how we'd how we'd do that how we'd create a set of speaker pages for the conference. This was one of those tech spikes that we carried out early on. We have an api endpoint in craft, that returns, all the speakers, like so, an array, of speaker objects holding their basic information. And we can achieve this with the element, api, in craft, which allows us to return, json, rather than html. Here we set out our endpoint. We query the person post type. We filter down to only return, speakers. And then we return their basic information. Note that we decided to have people, that can be speakers, rather than just speakers. Events, also have mcs. And workshop, organizers. That need to be on the website too, had i had not had i not had that planning session earlier with my colleague. That wouldn't have been accounted, for. And now for the front end. 11t. Allows us to put content, fetching scripts in the underscore, data folder, and it will call them every time it rebuilds the website. Each script uses a utility, function that, wraps around the package, node fetch, and allows us to bake in some sensible defaults, for the api calls we're going to make, as well as expose, those important, parts for overwriting.
With Environment, variables. See those lines setting out our api, variable. Those are where we first ask if there's an environment, variable, called api. And if not. We fall back to the sensible, default. This means we can run against our local api, without, any environment, file. We can then create a dot m file, setting the variable, api. To point to the staging api. And finally, for the live server. We can inject. An environment, variable at build time, to point to the live api. So through this we've avoided putting secrets, into our repository. But we've also opened up the possibility, for testing more thoroughly, and this is what i call appropriate, scaling. Now we can call our utility, function. We can pass in the endpoint, and return the data back to 11.. And this is an asynchronous, function so, use it as a place to call multiple, endpoints, prepare your data before it arrives in your view layer. And this is server side javascript, so you can pull in all those heavy load ash or moment libraries, you want here it's not going to impact the user at all, because it all happens at build time. Finally, 11d, exposes. This response, as a global, variable, called speakers. And using the dash, pages.nunchuck. Format. 11t, will loop through all the array of speakers, and then create a page for each one. Now onto deploying the sites. We already have a lamp deployment, setup at clear left so, putting craft on there made the most sense. But this was a global, virtual, conference, so a global hosting, solution for the front end was preferred. And netlify, was the natural choice. Netlify, runs the build command, npx, 11t. Rendering, the sites and pulling in the latest content, every time we push to the main branch in github. And there lies a little problem. The site only deploys, when new coders are added. Not new content. How do we trigger a build when content is written. Also, with a traditional, cms. When you hit publish, the changes go live immediately. And with the jam stack site there's that short build time delay. Now we know that's the boost performance, for the user. But how do you sell that to your colleagues, who just want things to go live quickly. Well that traditional, go live as soon as you hit publish thing can be flipped around, to be seen as much as a bug as it is a feature. Conferences. Often go hand in hand with big announcements. Here are the speakers, here's the schedule for the week. And sometimes you want to stage a number of changes, and then deploy them in one go. And that is something that jamstack, can help with and it provides a great way, to explain, away that go live delay. So we need a way of letting, content editors, trigger a build when they're ready to do so. And netfly, has this nifty feature, called, build hooks. And they let you run a build, whenever you send a post request, to a unique url, that they give you. One option to hook this up would be to create a small web page on a private url, you could put a big red launch button on it and every time the button is pushed it sends a post request off to notify, it would work. Another option, the one we went for, sounds a bit more fancy, but ended up being achievable, without a single line of code. And it's a bit more integrated, into our day-to-day, tooling of our company, it's, slack. Where netlify, has inbound webhooks, to trigger a build, slack has outgoing, web hooks for sending those sorts of commands. And we're going to marry the two together. Within, slack's, online settings area, you can create a new web hook. Set the channel it works against. The url, that it posts to that one from the netify. And then the trigger words that caller, call it, and for us that was launch sofa conf. The content team were so excited, to run this magic command in slack, and see their changes go live. They're not traditionally, in charge of deployments, so, letting them behind the magician's, curtain, and triggering build processes, was actually, really cool, and a great way to unite the team a bit more. And with very little effort on our own part other than just building sensibly.
And Choosing responsible, technologies. We had a maxed out lighthouse, score, as i said earlier, global performance, is available, for everyone, with jamstack. This is the fastest, conference, site we've ever built so our users will be happy. The cms, was totally, tailored to the events, and we're consistent, platform going forward, so they were happy with the events team. It was built in record, time and it's going to speed up future builds so all of our stakeholders, were really happy. And finally. It was built with modern web tools, and so the front-end team i was happy. We maxed out our internal scores as well. We got the site live in a number of days, we sold out of early bird tickets within two hours, and it was a huge team success, with genuine, collaboration. Brought together with a jam stack approach. I hope you found that a useful story with some, handy tips in there for how you can gather requirements, more effectively. Choose appropriate, technology. And bring your organization. Along for this exciting, jam stack ride. Thank you so much for listening. I've got a few minutes now for any questions, if you'd like to type them in the chat window, and if not just have a great time at the rest of your conference. Thanks so much.
2020-10-04 09:26
