Forem: Alexandre Valsamou-Stanislawski

Gatsby: how is it different from other site generators

Alexandre Valsamou-Stanislawski — Mon, 27 Jan 2020 14:28:48 +0000

Static website generators (SSG) are top-rated technologies to build websites. And the reasons are obvious: they offer flexible content edition, and the deployed sites have the best performance.

Now I'm using Gatsby, and things are different from other SSG. Beyond the buzzwords that are React and GraphQL, Gatsby switches the way I think about the website I build: from a content-oriented one to a programmatic one.

I initially wrote this content for the talk I gave at Paris.js #90, the video is here and the slides are there

What is a static website generator?

At its core, an SSG is a tool that transforms simplified markup into HTML: for each of the original files, you get a new HTML file. However, the simplified markup is only here to help you edit the content, and you write the shell hosting the content with a complete template language.

With Jekyll, you cannot configure the type of markup or the templating engine. With others, you can pick plugins depending on your preferences. With both approaches, you get the same kind of tool: a pipeline in which each step pushes transformed content to the next.

Static site generators are pipelines

So traditionally, SSGs use a push model. This model limits the possibilities of sources to the one foreseen by the SSG creators. And in practice, those sources are the markup files or, in the best case, any file.

The case of the documentation generation

When I was in charge of some JS open-source projects at Algolia, proper documentation was vital. When you make documentation for such projects, you realize it's hard to be exhaustive without JSDoc (or documentation.js), and it's hard to make a beautiful website without the tooling offered by SSGs. So the obvious is to try mixing both.

Because of the push model, you have to work around the way the SSG work:

in the case of Jekyll, you can generate markup files and then integrate them
in the case of an SSG built around plugins, like Metalsmith, you can write a plugin with the limitation of only working with virtual files (which is the fundamental brick for content in Metalsmith)

Both methods feel very hacky, and because of that, they are tough to maintain.

Gatsby does it differently.

You have guessed it already: Gatsby uses a pull model for the content. It is not the content that creates the pages; it's the code that pulls the content and creates the pages.

The content is available through GraphQL. Each content plugin provides an API that allows the code to query the content. The content can be plain files or markdown files. The more specific is the plugin, the more specialized is the API: when using the markdown plugin, the GraphQL API provides the content in rendered HTML and can generate the excerpts.

There is no limitation on the source either, so working with comments in the source file is not an issue. So much so, that there is a plugin for documentation.js(a JSDoc alternative).

The documentation example is unusual; other use cases leverage this API, and the headless CMSs are the perfect candidate. The GraphQL API is just a layer on top of the HTTP API those service offer. The use of such services decouples the architecture. It reduces the need for servers even more while providing superior user experience.

Last but not least, media assets benefit from the pull approach too. With the GraphQL API, you can query the images you need and retrieve a structure that contains all the URLs of the optimized alternatives of the source file.

One source, multiple images

Unified static and live templates

With SSGs before Gatsby, you would not write the HTML with the same templating engine when you move to the front-end. Juggling with templating systems is particularly tricky when writing a single page app (SPA) because writing two implementations lead to discrepancies. To the point that you would not traditionally use an SSG when writing an SPA.

React is the templating engine, and Gatsby acts as a server-side rendering framework: only one template per piece of HTML. It's the same code that runs at runtime and during the static generation. The reuse of templates eliminates the possibilities of bugs due to discrepancies completely.

Because of the component approach and the fixed data structures of GraphQL fragments, the plugins can provide a unified and user-friendly API to the developers.

React and GraphQL APIs merge together, and this limits the mental load

The combination of the two technologies hides the complexity, and it provides a seamless developer experience.

A change of perspective

The Gatsby team could have continued the work laid out by previous tools. At some point, they flipped the content access model. They might not have done that intentionally, but what stays is a different approach.

As a library writer and DX practitioner, the lesson to me is clear: sometimes, you need to change what is familiar to something else. If you change this at a fundamental level, like querying the content instead of pushing the content down the pipeline, you get ripples everywhere.

Thanks for the insights 😅, but is Gatsby right for me?

Changing the content paradigm from push to pull is a trade-off towards more flexibility, more power, and also more work for the developer. How much more work is hard to evaluate, here are some pointers:

The Gatsby architecture is intricate; this can be daunting even if you don't have to master it entirely.
With Gatsby, you use React and GraphQL, which you need to learn the fundamentals to get started.
If you need to make a single page app or a PWA, Gatsby is helpful. If you know Vue, you should consider the Vue flavor.

After considering the previous points, here are for me the selling points of Gatsby:

Best performance built-in (gatsby-image is just amazing)
Unified DX for the static generation and the live website
Super active community
Great documentation

Thanks for reading this post, it means a lot if you could share it. I'm wondering, have you tried Gatsby yet? Do you want to try? Why not?

If you've liked this post, maybe you'd like my other post about "Getting started with React today" or "How not to get swamped in your projects."

This post was first published on Noima.xyz blog.

Projects: how to avoid getting swamped

Alexandre Valsamou-Stanislawski — Tue, 14 Jan 2020 12:22:35 +0000

The other day I posted about getting started with React. I received a lot of positivity and good vibes from the DEV community (Thanks 🙇‍♂️). In the process, I also received some great suggestions, and one of them was to propose some starter project ideas. This suggestion threw me on the memory lane of projects I made to learn new technologies.

I did a review of some of the projects I made. Amongst the projects, some were complete failures; some I continue to use today. Along the way, I found some things that I might be of interest.

This article is a summary, with the goal of each project, how it went and, what we can learn from them.

Disclaimer Not every advice is for everyone: I’m a product-oriented person, and I can’t do tech for the sake of it; if it’s not your case, I’d love to hear about your point of view when you learn.

Before you go any further, here are the key learnings (TL;DR):

Be super clear about what you want to achieve: learning or making something
Set yourself a “done” goal
If you deeply understand what you’re building, it helps with the other parts of the project
If you have mastered the tech, it helps you focus on what you’re building

The Blog engine

The first project is one of my earliest, and a pretty failed one too. Back in the early 2000s, blogging was a thing, and being online was very attractive and yet not very accessible. Blogger launched in 99, and the initial release year of WordPress is 2003. So making a blog engine did not seem that bad of an idea.

When I started the project, I had a very vague idea of what I should do. To prevent you from going on the same path, here is what I expect of a minimal blog engine:

You must be able to write content
You must be able to publish content
The content must be visible on the website in a structured form, once published
You may have multiple writers
Only the writer(s) can write and publish content

This kind of project is a perfect fit when you want to learn a new backend technology. Here are some of the things you learn:

Database access
CRUD interfaces
Backend MVC
Authentication
Making UI’s

It’s no surprise that with such a list of things to learn that this project is the goto example for back-end frameworks, such as Rails or Django.

In my case, I ended up writing no content or so and with an unfinished product. I couldn't decide between the technical aspects of the project and my will to write content. Also, I didn’t know what it means to write anything; I didn’t have any idea of what an editorial line could be.

I did not learn explicitly from this experience then. But it gave me some hints for building my next projects.

Video games

It is tough to make a single list of requirements for a game. So here are some general objectives that could apply to any game:

You must have an understandable goal (survive)
You must be able to evaluate yourself (with points for example)
It must be fun (visual effects and sound are essential)

This kind of project is perfect for trying out UI libraries (React) or API (Canvas). Libraries do not have video games as their primary target, which makes this type of project exciting for potential performance issues. On the other hand, raw API’s tend to be very low-level, and there are no game primitives to help you, which is also very good for practicing abstraction.

Little shooter uses Canvas 2D API. I feel the game is a bit too hard, try it here

I picked a kind of video game I love (2D vertical shooters), and it helped me focus on learning the skills I wanted (Canvas 2D). The second time, it was even more manageable, and I could deepen the story I wanted to express even though I used other technologies (React and DOM).

Little shooter 2 is an improvement on the game side and also a complete rewrite, try it for yourself and tell me what you think in the comments.

Making a video game framework is an interesting exercise as well, even though you have to spend time on things that are not the game itself. The framework is a means to an end when making a video game, be careful. And also, I haven't finished any games with the framework I made; I guess that counts against the idea of making a framework.

A graphing tool

This one is very niche and yet one of my favorite personal projects. I was deep into making animations with Loop, and because I was on this purely functional trend, I was making super complex functions. To understand what I was doing, I decided to graph them.

In a few words, here is what you need for the simplest graphing tool:

You must be able to manage a set of functions
You must be able to check the functions visually
You should be able to use the mouse to navigate (drag, zoom in / out)

Doing so, I ended up writing a library and then a UI. I needed this tool to understand what I was doing; therefore, it was crystal clear to me what I wanted to implement. And because of that, the UI was evident, and picking up a new front-end framework was not an issue (BackboneJS).

The FunctionXplorer UI is pretty usable, in spite of its old age. Try it for yourself

Learning from the past projects

To get the best of a personal project, I find best to:

Set a clear objective for focus and self-evaluation
Restrict the scope (business knowledge, requirements or technology) to focus even more on your objective
Do something that you like to keep the motivation going

The good thing is that those hints apply very well on the business side too. As a professional, if you are aware of those elements, they make you more efficient and driven.

So what do you think? Do you have any meaningful personal project ideas? What did you learn when you built them?

This post was first published on Noima blog

Starting React today?

Alexandre Valsamou-Stanislawski — Tue, 10 Dec 2019 15:28:46 +0000

React is intimidating, daunting even. And yet it is very simple. That's a paradox, right? And it is pretty annoying for beginners, and for me as everyone takes me for a fool. So let's talk about why it feels so damn hard to learn, and how I would start again today.

TL;DR: react is not hard, the ecosystem is. And the ecosystem is like that because it has to answer the many questions React left unanswered. If you're starting today, start a small project with just React, feel the pain, restart the project, add a library, feel other problems, repeat :D

Why does React feel so hard to learn?

But first, what is React anyway? React is a JavaScript library for building user interfaces, UI for short. If you've tried to learn React, you might know that already 😃 What this library does is build HTML and allow you to "react" to user interactions. And that's it, it doesn't even come with a way to deal with data from any source.

Even though, it does "little" it does it very clearly. The library enforces the concept of component. The components can either "draw" HTML tags or other components. Of course, the sub components can do the same. Therefore we end up with a tree structure that builds our UI.

React does contain other concepts, but really that's the gist. And that's the issue. Because it only does the UI, it does not answer the needs for a fully fledged Single Page Application. And thus, the community began to address them which led to the creation of the React Ecosystem. Each piece of the ecosystem comes with its own limitations which led to other patterns and libraries, and so on and so forth...

With this plethora of libraries, best practices and patterns, how does one create solid basis for learning React?

Start like it's 2013 🤘

There is no better way to start learning a new tool than when it is rudimentary. Unfortunately for you, it's not the case anymore with React. But you can still emulate that with create-react-app 👍

# make sure you have node installed
npx create-react-app learning-iteration-1
cd learning-iteration-1
npm start

The recipe is quite straightforward:

pick a small project idea
use only react to build it
feel the pain, if there is no pain then switch project 🎉
start again and introduce a single library / pattern that will solve a pain point
repeat from 3.

Here are some challenges that you want to solve in your project:

synchronize two components that are not parent / children
load data from the web
make a big tree and have only few components update
leave your best idea in comments 😍

With this method, you will build up your knowledge rather than being overflowed by contradictory information. You will be able to forge your own mind on which solutions to adopt.

Hope you will find those suggestions useful 🙇‍♂️
And follow me if you want to read more react things 😃