Tag: Netlify

Building Serverless GraphQL API in Node with Express and Netlify

I’ve always wanted to build an API, but was scared away by just how complicated things looked. I’d read a lot of tutorials that start with “first, install this library and this library and this library” without explaining why that was important. I’m kind of a Luddite when it comes to these things.

Well, I recently rolled up my sleeves and got my hands dirty. I wanted to build and deploy a simple read-only API, and goshdarnit, I wasn’t going to let some scary dependency lists and fancy cutting-edge services stop me¹.

What I discovered is that underneath many of the tutorials and projects out there is a small, easy-to-understand set of tools and techniques. In less than an hour and with only 30 lines of code, I believe anyone can write and deploy their very own read-only API. You don’t have to be a senior full-stack engineer — a basic grasp of JavaScript and some experience with npm is all you need.

At the end of this article you’ll be able to deploy your very own API without the headache of managing a server. I’ll list out each dependency and explain why we’re incorporating it. I’ll also give you an intro to some of the newer concepts involved, and provide links to resources to go deeper.

Let’s get started!

A rundown of the API concepts

There are a couple of common ways to work with APIs. But let’s begin by (super briefly) explaining what an API is all about: reading and updating data.

Over the past 20 years, some standard ways to build APIs have emerged. REST (short for REpresentational State Transfer) is one of the most common. To use a REST API, you make a call to a server through a URL — say api.example.com/rest/books — and expect to get a list of books back in a format like JSON or XML. To get a single book, we’d go back to the server at a URL — like api.example.com/rest/books/123 — and expect the data for book #123. Adding a new book or updating a specific book’s data means more trips to the server at similar, purpose-defined URLs.

That’s the basic idea of two concepts we’ll be looking at here: GraphQL and Serverless.

GraphQL

Applications that do a lot of getting and updating of data make a lot of API calls. Complicated software, like Twitter, might make hundreds of calls to get the data for a single page. Collecting the right data from a handful of URLs and formatting it can be a real headache. In 2012, Facebook developers starting looking for new ways to get and update data more efficiently.

Their key insight was that for the most part, data in complicated applications has relationships to other data. A user has followers, who are each users themselves, who each have their own followers, and those followers have tweets, which have replies from other users. Drawing the relationships between data results in a graph and that graph can help a server do a lot of clever work formatting and sending (or updating) data, and saving front-end developers time and frustration. Graph Query Language, aka GraphQL, was born.

GraphQL is different from the REST API approach in its use of URLs and queries. To get a list of books from our API using GraphQL, we don’t need to go to a specific URL (like our api.example.com/graphql/books example). Instead, we call up the API at the top level — which would be api.example.com/graphql in our example — and tell it what kind of information we want back with a JSON object:

{   books {     id     title     author   } }

The server sees that request, formats our data, and sends it back in another JSON object:

{   "books" : [     {       "id" : 123       "title" : "The Greatest CSS Tricks Vol. I"       "author" : "Chris Coyier"     }, {       // ...     }   ] }

Sebastian Scholl compares GraphQL to REST using a fictional cocktail party that makes the distinction super clear. The bottom line: GraphQL allows us to request the exact data we want while REST gives us a dump of everything at the URL.

Concept 2: Serverless

Whenever I see the word “serverless,” I think of Chris Watterston’s famous sticker.

Similarly, there is no such thing as a truly “serverless” application. Chris Coyier nice sums it up his “Serverless” post:

What serverless is trying to mean, it seems to me, is a new way to manage and pay for servers. You don’t buy individual servers. You don’t manage them. You don’t scale them. You don’t balance them. You aren’t really responsible for them. You just pay for what you use.

The serverless approach makes it easier to build and deploy back-end applications. It’s especially easy for folks like me who don’t have a background in back-end development. Rather than spend my time learning how to provision and maintain a server, I often hand the hard work off to someone (or even perhaps something) else.

It’s worth checking out the CSS-Tricks guide to all things serverless. On the Ideas page, there’s even a link to a tutorial on building a serverless API!

Picking our tools

If you browse through that serverless guide you’ll see there’s no shortage of tools and resources to help us on our way to building an API. But exactly which ones we use requires some initial thought and planning. I’m going to cover two specific tools that we’ll use for our read-only API.

Tool 1: NodeJS and Express

Again, I don’t have much experience with back-end web development. But one of the few things I have encountered is Node.js. Many of you are probably aware of it and what it does, but it’s essentially JavaScript that runs on a server instead of a web browser. Node.js is perfect for someone coming from the front-end development side of things because we can work directly in JavaScript — warts and all — without having to reach for some back-end language.

Express is one of the most popular frameworks for Node.js. Back before React was king (How Do You Do, Fellow Kids?), Express was the go-to for building web applications. It does all sorts of handy thing like routing, templating, and error handling.

I’ll be honest: frameworks like Express intimidate me. But for a simple API, Express is extremely easy to use and understand. There’s an official GraphQL helper for Express, and a plug-and-play library for making a serverless application called serverless-http. Neat, right?!

Tool 2: Netlify functions

The idea of running an application without maintaining a server sounds too good to be true. But check this out: not only can you accomplish this feat of modern sorcery, you can do it for free. Mind blowing.

Netlify offers a free plan with serverless functions that will give you up to 125,000 API calls in a month. Amazon offers a similar service called Lambda. We’ll stick with Netlify for this tutorial.

Netlify includes Netlify Dev which is a CLI for Netlify’s platform. Essentially, it lets us run a simulation of our in a fully-featured production environment, all within the safety of our local machine. We can use it to build and test our serverless functions without needing to deploy them.

At this point, I think it’s worth noting that not everyone agrees that running Express in a serverless function is a good idea. As Paul Johnston explains, if you’re building your functions for scale, it’s best to break each piece of functionality out into its own single-purpose function. Using Express the way I have means that every time a request goes to the API, the whole Express server has to be booted up from scratch — not very efficient. Deploy to production at your own risk.

Let’s get building!

Now that we have out tools in place, we can kick off the project. Let’s start by creating a new folder, navigating to fit in terminal, then running npm init  on it. Once npm creates a package.json file, we can install the dependencies we need. Those dependencies are:

  1. Express
  2. GraphQL and express-graphql. These allow us to receive and respond to GraphQL requests.
  3. Bodyparser. This is a small layer that translates the requests we get to and from JSON, which is what GraphQL expects.
  4. Serverless-http. This serves as a wrapper for Express that makes sure our application can be used on a serverless platform, like Netlify.

That’s it! We can install them all in a single command:

npm i express express-graphql graphql body-parser serverless-http

We also need to install Netlify Dev as a global dependency so we can use it as a CLI:

npm i -g netlify-dev

File structure

There’s a few files that are required for our API to work correctly. The first is netlify.toml which should be created at the project’s root directory. This is a configuration file to tell Netlify how to handle our project. Here’s what we need in the file to define our startup command, our build command and where our serverless functions are located:

[build] 
   # This command builds the site   command = "npm run build" 
   # This is the directory that will be deployed   publish = "build" 
   # This is where our functions are located   functions = "functions"

That functions line is super important; it tells Netlify where we’ll be putting our API code.

Next, let’s create that /functions folder at the project’s root, and create a new file inside it called api.js.  Open it up and add the following lines to the top so our dependencies are available to use and are included in the build:

const express = require("express"); const bodyParser = require("body-parser"); const expressGraphQL = require("express-graphql"); const serverless = require("serverless-http");

Setting up Express only takes a few lines of code. First, we’ll initial Express and wrap it in the serverless-http serverless function:

const app = express(); module.exports.handler = serverless(app);

These lines initialize Express, and wrap it in the serverless-http function. module.exports.handler lets Netlify know that our serverless function is the Express function.

Now let’s configure Express itself:

app.use(bodyParser.json()); app.use(   "/",   expressGraphQL({     graphiql: true   }) );

These two declarations tell Express what middleware we’re running. Middleware is what we want to happen between the request and response. In our case, we want to parse JSON using bodyparser, and handle it with express-graphql. The graphiql:true configuration for express-graphql will give us a nice user interface and playground for testing.

Defining the GraphQL schema

In order to understand requests and format responses, GraphQL needs to know what our data looks like. If you’ve worked with databases then you know that this kind of data blueprint is called a schema. GraphQL combines this well-defined schema with types — that is, definitions of different kinds of data — to work its magic.

The very first thing our schema needs is called a root query. This will handle any data requests coming in to our API. It’s called a “root” query because it’s accessed at the root of our API— say, api.example.com/graphql.

For this demonstration, we’ll build a hello world example; the root query should result in a response of “Hello world.”

So, our GraphQL API will need a schema (composed of types) for the root query. GraphQL provides some ready-built types, including a schema, a generic object², and a string.

Let’s get those by adding this below the imports:

const {   GraphQLSchema,   GraphQLObjectType,   GraphQLString } = require("graphql");

Then we’ll define our schema like this:

const schema = new GraphQLSchema({   query: new GraphQLObjectType({     name: 'HelloWorld',     fields: () => ({ /* we'll put our response here */ })   }) })

The first element in the object, with the key query, tells GraphQL how to handle a root query. Its value is a GraphQL object with the following configuration:

  • name – A reference used for documentation purposes
  • fields – Defines the data that our server will respond with. It might seem strange to have a function that just returns an object here, but this allows us to use variables and functions defined elsewhere in our file without needing to define them first³.
const schema = new GraphQLSchema({   query: new GraphQLObjectType({     name: "HelloWorld",     fields: () => ({       message: {         type: GraphQLString,         resolve: () => "Hello World",       },     }),   }), });

The fields function returns an object and our schema only has a single message field so far. The message we want to respond with is a string, so we specify its type as a GraphQLString. The resolve function is run by our server to generate the response we want. In this case, we’re only  returning “Hello World” but in a more complicated application, we’d probably use this function to go to our database and retrieve some data.

That’s our schema! We need to tell our Express server about it, so let’s open up api.js and make sure the Express configuration is updated to this:

app.use(   "/",   expressGraphQL({     schema: schema,     graphiql: true   }) );

Running the server locally

Believe it or not, we’re ready to start the server! Run netlify dev in Terminal from the project’s root folder. Netlify Dev will read the netlify.toml configuration, bundle up your api.js function, and make it available locally from there. If everything goes according to plan, you’ll see a message like “Server now ready on http://localhost:8888.” 

If you go to localhost:8888 like I did the first time, you might be a little disappointed to get a 404 error.

But fear not! Netlify is running the function, only in a different directory than you might expect, which is /.netlify/functions. So, if you go to localhost:8888/.netlify/functions/api, you should see the GraphiQL interface as expected. Success!

Now, that’s more like it!

The screen we get is the GraphiQL playground and we can use it to test out the API. First, clear out the comments in the left pane and replace them with the following:

{   message }

This might seem a little… naked… but you just wrote a GraphQL query! What we’re saying is that we’d like to see the message field we defined in api.js. Click the “Run” button, and on the righth, you’ll see the following:

{   "data": {     "message": "Hello World"   } }

I don’t know about you, but I did a little fist pump when I did this the first time. We built an API!

Bonus: Redirecting requests

One of my hang-ups while learning about Netlify’s serverless functions is that they run on the /.netlify/functions path. It wasn’t ideal to type or remember it and I nearly bailed for another solution. But it turns out you can easily redirect requests when running and deploying on Netlfiy. All it takes is creating a file in the project’s root directory called _redirects (no extension necessary) with the following line in it:

/api /.netlify/functions/api 200!

This tells Netlify that any traffic that goes to yoursite.com/api should be sent to /.netlify/functions/api. The 200! bit instructs the server to send back a status code of 200 (meaning everything’s OK).

Deploying the API

To deploy the project, we need to connect the source code to Netlfiy. I host mine in a GitHub repo, which allows for continuous deployment.

After connecting the repository to Netlfiy, the rest is automatic: the code is processed and deployed as a serverless function! You can log into the Netlify dashboard to see the logs from any function.

Conclusion

Just like that, we are able to create a serverless API using GraphQL with a few lines of JavaScript and some light configuration. And hey, we can even deploy — for free. 

The possibilities are endless. Maybe you want to create your own personal knowledge base, or a tool to serve up design tokens. Maybe you want to try your hand at making your own PokéAPI. Or, maybe you’re interesting in working with GraphQL.

Regardless of what you make, it’s these sorts of technologies that are getting more and more accessible every day. It’s exciting to be able to work with some of the most modern tools and techniques without needing a deep technical back-end knowledge.

If you’d like to see at the complete source code for this project, it’s available on GitHub.

Some of the code in this tutorial was adapted from Web Dev Simplified’s “Learn GraphQL in 40 minutes” article. It’s a great resource to go one step deeper into GraphQL. However, it’s also focused on a more traditional server-full Express.


  1. If you’d like to see the full result of my explorations, I’ve written a companion piece called “A design API in practice” on my website.
  2. The reasons you need a special GraphQL object, instead of a regular ol’ vanilla JavaScript object in curly braces, is a little beyond the scope of this tutorial. Just keep in mind that GraphQL is a finely-tuned machine that uses these specialized types to be fast and resilient.
  3. Scope and hoisting are some of the more confusing topics in JavaScript. MDN has a good primer that’s worth checking out.

The post Building Serverless GraphQL API in Node with Express and Netlify appeared first on CSS-Tricks.

CSS-Tricks

, , , , ,

Making My Netlify Build Run Sass

Let’s say you wanted to build a site with Eleventy as the generator. Popular choice these days! Eleventy doesn’t have some particularly blessed way of preprocessing your CSS, if that’s something you want to do. There are a variety of ways to do it and perhaps that freedom is part of the spirit of Eleventy.

I’ve seen people set up Gulp for this, which is cool, I still use and like Gulp for some stuff. I’ve seen someone use templating to return preprocessed CSS, which seems weird, but hey, whatever works. I’ve even seen someone extend the Eleventy config itself to run the processing.

So far, the thing that has made the most sense to me is to use npm scripts do the Sass processing. Do the CSS first, then the HTML, with npm-run-all. So, you’d set up something like this in your package.json:

  "scripts": {     "build": "npm-run-all build:css build:html",     "build:css": "node-sass src/site/_includes/css/main.scss > src/site/css/main.css",     "build:html": "eleventy",     "watch": "npm-run-all --parallel watch:css watch:html",     "watch:css": "node-sass --watch src/site/_includes/css/main.scss > src/site/css/main.css",     "watch:html": "eleventy --serve --port=8181",     "start": "npm run watch"   },

I think that’s fairly nice. Since Eleventy doesn’t have a blessed CSS processing route anyway, it feels OK to have it de-coupled from Eleventy processing.

But I see Netlify has come along nicely with their build plugins. As Sarah put it:

What the Build Plugin does is give you access to key points in time during that process, for instance, onPreBuildonPostBuildonSuccess, and so forth. You can execute some logic at those specific points in time

There is something really intuitive and nice about that structure. A lot of build plugins are created by the community or Netlify themselves. You just click them on via the UI or reference them in your config. But Sass isn’t a build-in project (as I write), which I would assume is because people are a pretty opinionated about what/where/how their CSS is processed that it makes sense to just let people do it themselves. So let’s do that.

In our project, we’d create a directory for our plugins, and then a folder for this particular plugin we want to write:

project-root/   src/   whatever/   plugins/     sass/       index.js       manifest.yml

That index.js file is where we write our code, and we’ll specifically want to use the onPreBuild hook here, because we’d want our Sass to be done preprocessing before the build process runs Eleventy and Eleventy moves things around.

module.exports = {   onPreBuild: async ({ utils: { run } }) => {     await run.command(       "node-sass src/site/_includes/css/main.scss src/site/css/main.css"     );   }, };

Here’s a looksie into all the relevant files together:

Now, if I netlify build from the command line, it will run the same build process that Netlify itself does, and it will hook into my plugin and run it!

One little thing I noticed is that I was trying to have my config be the (newer) netlify.yml format, but the plugins didn’t work, and I had to re-do the config as netlify.toml.

So we de-coupled ourselves from Eleventy with this particular processing, and coupled ourselves to Netlify. Just something to be aware of. I’m down with that as this way of configuring a build is so nice and I see so much potential in it.

I prefer the more explicit and broken up configuration of this style. Just look at how much cleaner the package.json gets:

Removed a bunch of lines from the scripts area of a package.json file, like the specific build:css and build:html commands

I still have this idea…

…of building a site that is a dog-fooded example of all the stuff you could/should do during a build process. I’ve started the site here, (and repo), but it’s not doing too much yet. I think it would be cool to wire up everything on that list (and more?) via Build Plugins.

If you wanna contribute, feel free to let me know. Maybe email me or open an issue to talk about what you’d want to do. You’re free to do a Pull Request too, but PRs without any prior communication are a little tricky sometimes as it’s harder to ensure our visions are aligned before you put in a bunch of effort.

The post Making My Netlify Build Run Sass appeared first on CSS-Tricks.

CSS-Tricks

, , ,
[Top]

A/B Testing Instant.Page With Netlify and Speedcurve

Instant.Page does one special thing to make sites faster: it preloads the next page when it’s pretty sure you’re going to click a link (either by hovering over 65ms or mousedown on desktop, or touchstart on mobile), so when you do complete the click (probably a few hundred milliseconds later), it loads that much faster.

It’s one thing to understand that approach, buy into it, integrate it, and consider it a perf win. I have it installed here!

It’s another thing to actually get the data on your own site. Leave it to Tim Kadlec to get clever and A/B test it. Tim was able to do a 50/50 A/B split with performance-neutral Netlify split testing. Half loaded Instant.Page, the other half didn’t. And the same halves told SpeedCurve which half they were in, so performance charts could be built to compare.

Tim says it mostly looks good, but his site probably isn’t the best test:

It’s also worth noting that even if the results do look good, just because it does or doesn’t make an impact on my site doesn’t mean it won’t have a different impact elsewhere. My site has a short session length, typically, and very lightweight pages: putting this on a larger commercial site would inevitably yield much different results.

I’d love to see someone do this on a beefier site. I’m in the how could it not be faster?! camp, but with zero data.

Direct Link to ArticlePermalink

The post A/B Testing Instant.Page With Netlify and Speedcurve appeared first on CSS-Tricks.

CSS-Tricks

, , ,
[Top]

Get Programmatic Control of your Builds with Netlify Build Plugins

Today at Jamstack_Conf, Netlify announced Build Plugins. What it does is allow you to have particular hooks for events within your build, like when the build starts or ends. What’s nice about them is that they’re just a plain ‘ol JavaScript object, so you can insert some logic or kick off a library just the way you typically would within your application.

A “Build” is when you give your site to Netlify either via GitHub/GitLab/etc., or by literally just dropping the directory into the interface, Netlify will process all the assets, download and install packages, and generate a static version of the site to deploy to CDNs all around the world.

What the Build Plugin does is give you access to key points in time during that process, for instance, onPreBuild, onPostBuild, onSuccess, and so forth. You can execute some logic at those specific points in time, like this:

module.exports = {   onPreBuild: () => {     console.log('Hello world from onPreBuild event!')   }, }

You don’t only have to build them yourself, either! You can use build plugins that have been made by the community. There are very interesting ones, such as a11y, Cypress for testing, Inline Critical CSS, and my personal favorite, Subfont, which optimizes fonts for you in a really incredible way (you can watch a video about that).

Enable them through the dashboard through a few button clicks:

If you’d like to learn more, check out the announcement post here! Happy building!

The post Get Programmatic Control of your Builds with Netlify Build Plugins appeared first on CSS-Tricks.

CSS-Tricks

, , , , ,
[Top]

Enable Gatsby Incremental Builds on Netlify

The concept of an “incremental build” is that, when using some kind of generator that builds all the files that make for a website, rather than rebuilding 100% of those files every single time, it only changes the files that need to be changed since the last build. Seems like an obviously good idea, but in practice I’m sure it’s extremely tricky. How do you know what exactly which files will change and which won’t before building?

I don’t have the answer to that, but Gatsby has it figured out. Faster local builds is half the joy, the other half is that deployment also becomes faster, as the files that need to move around are far fewer.

I’d say incremental builds are a pretty damn big deal. I like seeing these hurdles get cleared Jamstack-land. I’m linking to the Netlify blog post here as getting it going on Netlify requires you to enable their “build plugins” feature which is also a real ahead-of-the-game feature, allowing you to run code during different parts of CI/CD with a really clean syntax.

Direct Link to ArticlePermalink

The post Enable Gatsby Incremental Builds on Netlify appeared first on CSS-Tricks.

CSS-Tricks

, , , ,
[Top]

Make Yourself a Little API With Netlify Functions

Here’s an example of a nice little use case for cloud functions. Glitch has this great package of friendly words. Say you wanted to randomly generate “happy-elephant” or “walking-tree”, and you need to do that on your website in JavaScript. Well, this package is pretty big (~200 KB), necessarily so, because it has big dictionaries of words in it. You wouldn’t want to ship that to your client-side JavaScript when you don’t have to.

Cloud functions are cool, and we can use them to give ourselves a little API for this package instead. That way the size doesn’t matter that much, it’s up on a server. Netlify makes this about as easy as it can be.

Here’s a repo that makes it all possible. It’s barely any code!

A functions folder with a Node file in it.

At the root of our project: /functions/random.js

This file will require the friendly-words package and export a single function. Essentially it grabs two random words, plops them together, and returns it.

const friendlyWords = require("friendly-words");  exports.handler = function(event, context, callback) {   const { predicates, objects } = friendlyWords;   const numberOfPredicates = predicates.length;   const numbersOfObjects = objects.length;    const randomPredicate =     predicates[Math.floor(Math.random() * numberOfPredicates)];   const randomObject = objects[Math.floor(Math.random() * numbersOfObjects)];    const output = `$ {randomPredicate}-$ {randomObject}`;    callback(null, {     headers: {       "Access-Control-Allow-Origin": "*"     },     statusCode: 200,     body: output   }); };

Deploy it to Netlify

We can configure Netlify to tell it we have this function in a netlify.toml file (just so we don’t even have to bother with the UI).

[build]   command = "#"   functions = "functions/"

But if I wanted to just tell Netlify this in Settings, I can:

Once it’s deployed, I gave it a nice site name, and then that cloud function will be available at a URL. You can even see it in the browser:

https://friendly-words.netlify.com/.netlify/functions/random

Now I don’t have to ship that package in my client-side JavaScript — I can just hit this URL to get what I want.

CORS

If I was hitting this URL from my own website also at friendly-words.netlify.com I wouldn’t have to worry about CORS, but if I need to use it from any other website, I do. Notice the Access-Control-Allow-Origin stuff in the Node JavaScript above. That takes care of that.

Demo

To use our little API, we can fetch from it. That’s it!


Does this pique your interest? Netlify has a ton of examples of using functions.


While I was doing this I came across Paul Kinlan’s article that does pretty much exactly the same thing, but his has some extra functionality as part of the API you might wanna check out.

The post Make Yourself a Little API With Netlify Functions appeared first on CSS-Tricks.

CSS-Tricks

, , ,
[Top]

Netlify High-Fives

We’ve got Netlify as a sponsor around here again this year, which is just fantastic. Big fan. Our own Sarah Drasner is Head of DX (Developer Experience) over there, if you hadn’t heard. And if you haven’t heard of Netlify, well, you’re in for a treat. It’s a web host, but for your jamstack sites, which means it’s static hosting, encouraging you to pre-build as much of your site as you can, then use JavaScript and APIs to do whatever else you need to. Heck, they’ll help you build serverless functions and auth.

Here’s a couple of Netlify-related things swirling around in my life.

  • I added open authoring to our conference site. So now, anybody can go to the admin area, auth with GitHub, and submit a conference. No coding required. Dream come true, if you ask me. The same thing is live on the serverless site.
  • I enjoyed Bryan Robinson’s take on jamstack in 2020. It’s about the connection between services and the power that brings.
  • It’s interesting how even not-particularly jamstack-y software like WordPress can totally live a jamstack life, when you combine it with something like Gatsby.
  • I have a new microsite idea cooking. I really wanna build a site that showcases all the things you can (and probably should) be doing with your build process. It will explain them and provide resources, but the whole site will dogfood itself and do all those things. Stuff like:
    1. Process all it’s code, keeping compiled code out of the repo
    2. Build a sitemap
    3. Optimize all the images
    4. Check for broken links
    5. Run accessibility tests
    6. Check the performance budget
    7. Run unit test
    8. Run end-to-end tests
    9. Run visual regression tests
    10. Trigger notifications

Wouldn’t that last one be cool?! We’d do it all with build plugins, at least that’s how it works in my mind. If you have a strong desire to contribute, lemme know — maybe we can make it a community effort.

The post Netlify High-Fives appeared first on CSS-Tricks.

CSS-Tricks

,
[Top]

Netlify CMS Open Authoring

I like the term “Git-backed CMS.” That term works for an emerging style of CMS that looks and behaves much like any other CMS, with a fascinating twist: it doesn’t actually store any data for you. These CMSs are connected to a Git repo where the data lives in flat files (e.g. Markdown). You teach the CMS where those files are and how they are structured. Then, as you use the CMS to create, edit, and delete things, those changes happen has commits (or pull/merge requests) are made against that repo. So cool.

For example, CloudCannon can do it specifically for hosted Jekyll sites.

But more in the Indie Web / JAMstack spirit, there are players like Forestry and the one I have the most experience with: Netlify CMS.

Lemme do a series of screenshots with captions to make the point very clear.

The site in question is our Serverless site. It happens to be Gatsby, but the important part is that that the content comes from Markdown files in a Git repo.
Here’s an example Markdown file (with Frontmatter) in the repo. I like Markdown fine, but I’d prefer to work with content in a GUI CMS honestly. The reason I went this way is so the data is in a repo, meaning I can take content-based pull requests.
I really do get content-based pull requests. That’s the magic right there. That’s exactly what I want.
Netlify CMS is basically two files. An index.html that loads up a SPA interface that literally does everything. And a configuration file to teach it about your content.
With Netlify CMS in place, I have my GUI CMS happy place. Any changes in here turn up as commits on the repo.

OK OK OK. What’s this “Open Authoring” thing?

As I write, it’s a beta feature.

Here’s the main thing: I can use Netlify CMS for my site. My team can also use it, because I can invite them specifically to the repo. But you, random person on the internet, cannot. If you wrote to me and told me you wanted to be a volunteer content manager on the site, then maybe, OK, I’ll invite you to the repo. (You being a member of the repo will allow you to auth into Netlify CMS, assuming you are using the GitHub back end, which is the only connection Open Authoring works with right now.)

But that’s a bummer that random internet people can’t submit pull requests on content via Netlify CMS. That would be way easier than the manual process of forking the repo and all that jazz — although to be fair, click the little pencil icon while looking at a Markdown file on GitHub and editing it makes the process pretty simple by opening a pull request automatically (but it doesn’t help you add new content or upload images or anything).

This is where Open Authoring comes in. In my Netlify CMS config I can basically flip it on with one line of config. They explain it well:

you can use Netlify CMS to accept contributions from GitHub users without giving them access to your repository. When they make changes in the CMS, the CMS forks your repository for them behind the scenes, and all the changes are made to the fork. When the contributor is ready to submit their changes, they can set their draft as ready for review in the CMS. This triggers a pull request to your repository, which you can merge using the GitHub UI.

Emphasis mine.

Wanna see the real beauty of this? Now we can put “Edit this” buttons on all the content, and if you click it, you’ll head straight into Netlify CMS to do the editing. It works if you are me, my team member, or you, random person from the internet.

That’s what I’ve always wanted. It makes the site into a wiki! But there is enough public accountability (they have to use a real GitHub account) that I wouldn’t worry about much spam or obnoxious behavior.

The post Netlify CMS Open Authoring appeared first on CSS-Tricks.

CSS-Tricks

, ,
[Top]

Netlify Build Plugins Announcement

Netlify just dropped a new thing: Build Plugins. (It’s in beta, so you have to request access for now.) Here’s my crack at explaining it, which is heavily informed from David Well’s announcement video.

You might think of Netlify as that service that makes it easy to sling up some static files from a repo and have a production site super fast. You aren’t wrong. But let’s step back and look at that. Netlify thinks about itself as a platform in three tiers:

  1. Netlify Build
  2. Netlify Dev
  3. Netlify Edge

Most of the stuff that Netlify does falls into those buckets. Connecting your Git repo and letting Netlify build and deploy the site? That’s Build. Using Netlify’s CLI to spin up the local dev environment and do stuff like test your local functions? That’s Dev. The beefed-up CDN that actually runs our production sites? That’s Edge. See the product page for that breakdown.

So even if you’re just slapping up some files that come out of a static site generator, you’re still likely taking advantage of all these layers. Build is taking care of the Git connection and possibly running a npm run build or something. You might run netlify dev locally to run your local dev server. And the live site is handled by Edge.

With this new Build Plugins release, Netlify is opening up access to how Build works. No longer is it just “connect to repo and run this command when the build runs.” There is actually a whole lifecycle of things that happen during a build. This is how David described that lifecycle:

  1. Build Starts
  2. Cache is fetched
  3. Dependencies are installed
  4. Build commands are run
  5. Serverless Functions are built
  6. Cache is saved
  7. Deployment
  8. Post processing

What if you could hook into those lifecycle events and run your own code alongside them? That’s the whole idea with Build Plugins. In fact, those lifecycle events are literally event hooks. Sarah Drasner listed them out with their official names in her intro blog post:

  • init: when the build starts
  • getCache: fetch the last build’s cache
  • install: when the project’s dependencies are installing
  • preBuild: runs directly before building the functions and running the build commands
  • functionsBuild: runs when the serverless functions are building, if they exist on the site
  • build: when the build commands are executing
  • package: package it to be deployed
  • preDeploy: runs before the built package is deployed
  • saveCache: save cached assets
  • finally: build finished, site deployed 🚀

To use these hooks and run your own code during the build, you write a plugin (in Node JavaScript) and chuck it in a plugins folder at like ./plugins/myPlugin/index.js

function netlifyPlugin(conf) {   return {     // Hook into lifecycle     finally: () => {       console.log("Finished!")     }   } }  module.exports = netlifyPlugin

…and adjust your Netlify config (file) to point to it. You’re best off reading Sarah’s post for the whole low-down and example.

OK. What’s the point?

This is the crucial part, right? Kind of the only thing that matters. Having control is great and all, but it only matters if it’s actually useful. So now that we can hook into parts of the build process on the platform itself, what can we make it do that makes our lives and sites better?

Here’s some ideas I’ve gathered so far.

Sitemaps

David demoed having the build process build a sitemap. Sitemaps are great (for SEO), but I definitely don’t need to be wasting time building them locally very often and they don’t really need to be in my repo. Let the platform do it and put the file live as “a build artifact.” You can do this for everything (e.g. my local build process needs to compile CSS and such, so I can actually work locally), but if production needs files that local doesn’t, it’s a good fit.

Notifications

Sarah demoed a plugin that hits a Twilio API to send a text message when a build completes. I do this same kind of thing having Buddy send a Slack message when this site’s deployment is done. You can imagine how team communication can be facilitated by programmatic messaging like this.

Performance monitoring

Build time is a great time to get performance metrics. Netlify says they are working on a plugin to track your Lighthouse score between deployments. Why not run your SpeedCurve CLI thing or Build Tracker CLI there to see if you’ve broken your performance budget?

Optimizations

Why not use the build time to run all your image optimizations? Image Optim has an API you could hit. SVGO works on the command line and Netlify says they are working on that plugin already. I’d think some of this you’d want to run in your local build process (e.g. drop image in folder, Gulp is watching, image gets optimized) but remember you can run netlify dev locally which will run your build steps locally, and you could also organize your Gulp such that the code that does image optimization can build part of a watch process or called explicitly during a build.

Images are a fantastic target for optimzation, but just about any resource can be optimized in some way!

Bailing out a problematic builds

If your build process fails, Netlify already won’t deploy it. Clearly useful. But now you could trigger that failure yourself. What if that performance monitoring didn’t just report on what is happening, but literally killed the build if a budget wasn’t met? All you have to do is throw an error or process.exit, I hear.

Even more baller, how about fail a build on an accessibility regression? Netlify is working on an Axe plugin for audits.

Clearly you could bail if your unit tests (e.g. Jest) fail, or your end-to-end tests (e.g. Cypress) fail, meaning you could watch for 404’s and all sorts of user-facing problems and prevent problematic deploys at all.

Use that build

Netlify is clearly all-in on this JAMstack concept. Some of it is pretty obvious. Chuck some static files on a killer CDN and the site has a wonderfully fast foundation. Some of it is less obvious. If you need server-powered code still, you still have it in the form of cloud functions, which are probably more powerful than most people realize. Some of it requires you to think about your site in a new way, like the fact that pre-building markup is not an all-or-nothing choice. You can build as much as you can, and leave client-side work to do things that are more practical for the client-side to do (e.g. personalized information). If you start thinking of your build process as this powerful and flexible tool to offload as much work as possible to, that’s a great place to start.

The post Netlify Build Plugins Announcement appeared first on CSS-Tricks.

CSS-Tricks

, , ,
[Top]