The Collab Lab is a U.S. nonprofit that provides remote, collaborative project practice for early-career developers. We focus on teaching how professional software teams work by working through a structured project over the course of 8 weeks under the guidance of mentors who are professionals in the field. Collab Lab is volunteer-driven and free for participants. More information about the program is available on our website.
GraphCMS is a hosted system for managing content. It is what’s called a “headless” CMS, meaning it is not concerned with the presentation of the content, just the structure of and relationships among the various bits.
As the name implies, GraphCMS was built from the ground up on GraphQL. GraphQL is a developer-friendly alternative to REST as a way of structuring and serving APIs. How to work with GraphQL itself is outside the scope of this article, but know that GraphCMS fully integrates GraphQL playgrounds, making it simple to experiment with queries until you get your endpoints serving just what you need.
A good thing about using 11ty is that the migration was painless, as I said above, our site was just HTML, CSS and JS files, the approach we took, was to keep the old site around and use 11ty to build it and then incrementally start creating new pages with templates and dynamic data. Here you can see the structure before and after for our migration:
You'll notice two things happened:
- We use
/buildas our output/build directory before and after the migration.
- We moved everything inside the
builddirectory to the
We can tell 11ty to treat the
pages directory as its input, and
build as its output in the
.eleventy.js config file. From then on, we treated the
pages directory as our working directory.
Now it was time to start DRYing things, so we created a layout file and several other templates (or “components” if you wish) that reduced the file sizes of our pages a lot and made things easier to reason about.
But that’s just half of the story. Now we wanted to make the site dynamic. We were tired of making manual updates to change the content of our site. This is where GraphCMS came in.
We wanted to give dynamic content a try in our Who We Are page as it’s the page that we update most often. It roughly looks like the following:
For what it's worth, we didn't migrate the whole page at once, we started out with the Developers Sub Section. The steps we followed to make this change were roughly as follows:
- Created a model in GraphCMS that represents the Developers
- Added content for that model in GraphCMS
- Explored the GraphQL API using GraphCMS API Playground
- Started consuming the data in 11ty.
This step was pretty straightforward, we just modeled the data we needed in our page, and that’s it. For instance, we added the participant's Firstname and Fullname among other data.
Again, this was straightforward. You just click the Content icon on the left hand side of the sidebar, and then start adding the data you need
One really useful thing that GraphCMS provides, is a playground that you can use to build your queries and try things without any limitation. Once you have the queries in place, you can move them to your development environment and start using them to get real data.
pages folder, we created a
graphql folder which acts as our data layer and it contains both, the requests to GraphCMS and the GraphQL Queries, our folder structure looks like this:
We started out by writing the query to get the teams. We don’t get the Developers directly as our Developers section is made of teams that contain developers.
Here’s the query to get the the teams, and then the collection of developers that participated in that team.
Then, we import that GraphQL Query and we call the GraphCMS endpoint using
graphql-request. For what is worth, you can use anything you want to call a GraphQL endpoint (e.g., Axios, Apollo, Urql), but I recommend
graphql-request as it gives you just what you need, nothing less, nothing more.
Up to this point, we have a function called
getTeams that will get all the teams ordered by
startDate and its respective developers ordered by
How you connect the data layer (
data folder) with the view layer (any
.html file) is to create a
[template-file].11tydata.js file with the same name as the
.html where we want to use the data. In our case, we have a
who-we-are.html file, which means that we have to create a
who-we-are.11tydata.js file to get dynamic data.
From there we can use the
teams object in
And that’s it — our Developers section is now fully powered by GraphCMS! 😎
Since we use Netlify to host our site, we use Zapier to schedule deployments everyday at a certain time. Our workflow to update our site now is this:
- Make a change in GraphCMS
- Trigger an automatic deployment at 12am PST
Unless we need to deploy any new feature or fix a bug, we no longer need to trigger a manual build! 🎉
For those times when we do need a manual build, we have installed the official Netlify/GraphCMS integration. This gives us the ability to kick off a build and deploy of the site at the click of a button from within the content editing interface.
GraphCMS is a great tool, easy and fun to use that has helped us greatly since now we’re able to iterate faster.
11ty is a fun tool to use, too! I like its simplicity and the fact that it goes back to the basics, HTML, CSS and JS. No need for anything fancy or with a steeper learning curve such as React or VUE.