DEV Community: Philippe Bernard

How to setup the favicon of a React app

Philippe Bernard — Wed, 04 Dec 2024 16:47:12 +0000

Adding a favicon to a React app shouldn't be that complicated. After all, React is probably the most popular frontend framework. Therefore, the Internet doesn't lack of articles which explain to do just this.

But this one is special. It comes with a triple promise:

Easy: You won't have to create icons by yourself. You won't even have to open an image editor or resize any image.
Quick: Done in less than 5 minutes.
Perfect: Your logo will be gorgeous everywhere: browser tag, smartphone home screen, search engine result pages.

All you need is a React-dedicated favicon generator

Spoiler: we are going to use an online tool: a favicon generator for React.
More precisely, for React apps created with create-react-app.

Wait, there are a lot of favicon generators. Why would we need a new one?
Because this one is going to save us a lot of time and efforts. Part of RealFaviconGenerator,
the generator designed for React creates the favicon assets (a bunch of icons and
HTML markups), but also the instructions to add them to our React app project.

Just like we said: easily, quickly and perfectly.

If you just want to get the job done, you can jump in right away and forget about this tutorial.

Step by step

Got your logo, preferably in SVG format? Let's go to the React favicon generator page and submit it.

We're now in front of an editor. It's time for our logo to shine! We can round corners of our icon
to make it less sharp, or apply a background color to suppress transparency and add more contrast.

We do this platform per platform: desktop navigators and Google result pages, iOS, and finally Android.

Perfect!

After that, we click "Next" to get the instructions to follow to add the favicon to our app:

First, let's download our icons. They were all resized, cropped and edited for us.

Quick!

The major takeaway is that the instructions are designed for a React app created with create-react-app.
For example, the markups should be added to the main HTML template, in /public/index.html.
We don't even have to read some doc or anything.

Easy!

Conclusion

No one cares of being called a "favicon expert". But handling this task like a pro really makes a difference.
You can spend an hour or more collecting data from various sources, edit the icons manually,
search for more tutos to find out how to put all this in a React app. There is neither joy nor glory going through this.

Don't waste time for such a mundane task. Use a favicon generator for React.

How to properly add a favicon in Next.js

Philippe Bernard — Sat, 19 Oct 2024 12:15:30 +0000

Next.js comes with a good favicon support. Drop a file named favicon.ico in the src/app folder and
boom! We have a favicon, declared in all of our pages. The sames goes for icon.png, apple-icon.png
and others.

So far so good.

But this is only half of the story. Now that we know how to add favicons to our Next.js app,
we need to figure out what to add.

Alright, we need an icon.png. But which size should it be? Do we really need it by the way?

SVG favicon is the (not so) new thing. But is it supported by all browsers?

The apple-touch.png icon is obviously for iOS. What about Android?

And Google result pages? Now that Google shows favicon in the results in its SEPR, we want to do this one right.

We could do our own research. But come one, we're talking about favicon. No one is going to congratulate
us for spending hours creating a favicon. Certainly not our boss or customer.

No time to waste: use RealFaviconGenerator

TL; DR We're going to use RealFaviconGenerator's Next.js favicon generator
to get the job done in a matter of minutes.

The first step is to go to the page dedicated to favicon for Next.js.

We upload our logo, preferably in SVG format. Do we then get our favicon? Not so fast! We first need to make
sure it looks great on all plateforms. The favicon editor offers a few options to adapt our icon to
different contexts, like adding a background:

Same kind of edition for the iPhone and iPad. Did you know that iOS applies a black background to transparent
touch icons?

And finally Android:

One more click and we get our favicon files, along with step-by-step instructions for a Next.js app. No need to browse Next.js doc to learn the conventions related to icons, it's all here!

The last step is checking that the favicon was correctly configured. Simply run:

npx realfavicon check 3000

RealFavicon controls the favicon of the local app and redirect us to a report. Is everything correct? 😁

Next.js conventions - Why are they gone?

RealFaviconGenerator doesn't take advantage of the Next.js conventions regarding favicon. This is because Next.js takes only some of the necessary files into account. For example, Next.js doesn't handle icons declared in the Web manifest, forcing us to store them in the
public directory, far from the other favicon files, in src/app.

We don't need to care anyway. Next.js conventions are useful when they free us from writing code. But RealFaviconGenerator does just that, too. Better keep things tidy than dispatching related files here and there in our code base.

Conclusion

No matter how good the favicon support provided by Next.js is, it is missing some essentials parts: the ability to tailor icons platform per platform, and the knowledge of the icons and markups we need to make it work everywhere. With RealFaviconGenerator, we're all set.

Create a CLI script in your NextJS project

Philippe Bernard — Sat, 03 Dec 2022 18:33:26 +0000

You put everything you need in your NextJS project: pages, code, tests, stories... Some of these components come out of the box, like pages. You can add the others easily with Jest, Storybook... you name it.

Sometimes you wish you would also have some scripts you can call from the command line. From such a script, you could reuse the app code you already wrote and also take advantage of the app environment. For example, the Prisma schema and database connection.

There are no scripts folder in a NextJS app by default, so let's build it! We are going to use tsx, which will handle everything for us.

From your NextJS app, install tsx:

yarn add -D tsx

Create scripts/my-script.ts:

console.log("Hello, NextJS+CLI");

Alright, this is just another Hello World script. But here you can use import to access your existing NextJS code from src or other directories. Your app environment is available too.

Declare your script in package.json:

...
"scripts": {
  ...
  "my-script": "tsx scripts/my-scripts.ts"
}

Et voilà! Your script is ready to shine:

yarn my-script

That was fairly easy thanks to tsx!

Write automated tutorials to stand out from the crowd

Philippe Bernard — Wed, 06 Jul 2022 12:20:00 +0000

Hey fellow technical blogger 👋

Writing successful content is hard, isn't it? When I write successful, I don't mean great. Our articles are already useful, carefully crafted and awesome. By successful, I mean views. Reactions. Shares on social network.

Unless we already enjoy a large audience, that's the hard part.

In this article, we're going to see why it is so hard to stand out, whatever the quality of the content. And yes, I'm going to show you something new. Something that hasn't been used in any tech article before and has the potential of getting the attention we need.

A few options, no ideal solution

Let's face it. Independently of their quality or usefulness, we want our posts to reach as many people as possible, whatever it is a matter of fulfillment, fame or money.

Big pond

An obvious approach is to write about a popular topic. React must be the hottest frontend framework around, so if we write "The Ultimate React Tutorial", we'll get a ton of traffic, right? Problem: we're not the first to have this shiny genius idea. If we google "react tutorial" (typically what we expect our potential readers to search for), the first results are from the ReactJS official website itself. This is quite a challenging final boss to beat.

We can hardly compete with such an authority regarding React, not counting the other great and numerous similar resources around. Although we might enjoy a nice traffic burst just after the publication, there is little chance that our article will enjoy a lasting popularity.

In other words, we are a very small fish in a big pond.

Little pond

If huge topics are too big for us, we can niche down. What about "Using React's useEffect with TypeScript" ? Although useEffect can be used just the same with TypeScript and vanilla JavaScript, people might be interested in explicitly TypeScript-ready content. Good news! Google cannot find anything with "react", "useEffect" and "typescript" in the title. We could rank first for "react useEffect typescript"!

The dirty little secret of niches is that they must be big enough to be interesting. If we compare "react tutorial" (red) and "react useEffect typescript" (blue) on Google Trends:

Now we're a big fish in a little pond. Too little.

Pond in the making

We could spot the next big thing before it becomes cool. Instead of writing a tutorial about React, what if we write one about the next JS framework that will replace it in a few years?

First, this is a bold bet. It is hard to predict which technologies are here to stay or fade away. It is even harder to guess which ones will outsmart them. Our article could remain a cry in the void.

And although our post could become really popular someday, at first, it will only get the attention of early adopters. This is an awesome position actually, but the figures won't match our expectation at first.

The real benefit will come a few months or years later, when tons of devs will search for "xyzjs tutorial" and our content will rank first. Google and friends like long lasting pages, so this strategy definitely makes sense.

But that's a long and risky way to go.

Be different... but how?

We know the basic recipe. Just be different. However, this strategy fails with the next question: how?

How can we stand out of the crowd?

A few years ago, video tutorials were something new. There are now a lot of excellent and popular YouTube tech channels. Expect fierce competition. The same goes for podcasts.

Could we use humor? Drawings? Something special? If you have such a talent, go for it! I personally can't follow you there 🥲

Automated tutorials with nstal

We can write an automated tutorial with nstal.

A what?!

A tutorial mixes educational content and instructions. It tells the reader what to do and why. The "why" part is essential. But the "what" part? Well, it depends.

When an article asks us to install this package and create this file, it is sometimes just boring. When we already took the time to understand a snippet, copying and pasting the said snippet is just an extra step. Automating it makes sense. nstal lets us write such a tutorial.

How does it look like?

Classic at first

An nstal article is written with MDX, which is a mix between Markdown and JSX. It's called an "nstaller".

At first, an nstaller is just regular content. For example, while setting up Tailwind in a NextJS project, we are asked to create tailwind.config.js:

Pretty mundane, isn't it?

Magic enabled

However, an nstaller starts with an invite to run nstal as a CLI:

Ignore it and we have our regular static article. But what if we run it?

We are... connected. Okay. But the real change is the content itself. Now the tailwind.config.js step is runnable:

If we click "Run", the file is actually created and the step reflects the change:

Wanna try it yourself? Take a few minutes to setup Tailwind in a NextJS project!

How nstal can boost our content

Tutorial automation is cool but how does it help us as tech bloggers? In two different ways.

Short term effect: Attention

As geeks, we are fond of fresh stuff. The next gadget, the next iPhone, the next Elon's announcement, you name it.

nstallers are new. Until now, nobody has ever followed a tutorial while casually clicking "Run" to get the job done. For this reason, publishing an nstaller will get us attention.

Don't get me wrong: I'm not pretending our readers will love it.

It is actually very likely than some of them will consider it as counter-productive. "Going through the tutorial helps me understand" they'll say. And they'll be totally right. And that's fine.

Other readers will don't know what to think about it. When something is very different from anything we experienced so far, it is sometimes hard to decide of whether we like it or not.

Finally, some of our readers will enjoy it and that's so cool.

But the most important point here is that many readers will notice the novelty. They will react to the article. Congratulate us, tell us we should stay with the classic tutorial format, ask us how we've made it, like it, share it on social media, etc.

Seriously. During the next few months, writing nstallers instead or regular articles will probably get us more attention, traffic and fame just because of the new format. As simple as this.

Long term effect: SEO

The short term effect plays well with another field that has the potential of generating a ton of traffic over the years: search engine optimization.

The hard part of SEO is link building. In other words, links from other sites (hopefully popular sites) that point to our content. Writing a good title, description and content is not that difficult. Convincing people to link to us is hard. Very hard.

This is exactly what attention brings us. At some point some tech sites will write about "an automated React tutorial" with a link to our article. Google will notice it. After a few weeks or months of growing popularity, Google will start thinking our content deserves to be featured. This is how we get to the Google's first page for a competitive search.

nstal is expected to help our SEO in another way, but I won't dwell on it just yet. Yup, I'm totally teasing you here 😅

Conclusion

nstal is a new project. It's so fresh I advice you to wait before you publish your first nstaller.

But if you're serious about blogging and don't want to miss what could be the next big wave, here is what you can do to get ready:

Browse the project and try the demo
Discover nstal and write your first nstaller
Subscribes to the newsletter to know how the project evolves and when it becomes ready for production
Contribute to the project

nstal could be the beginning of a great adventure. Stay tuned!

Never install anything manually again

Philippe Bernard — Wed, 22 Jun 2022 07:15:57 +0000

Let's create a web app. Add Typescript support. Configure ESLint. And Tailwind. Don't forget Prettier. We'll also use Prisma for the database.

Configuring a tool is always the same story. It usually begins with "Once upon a time, run npm install someproject". Then we create someproject.config.js, or maybe it is .someproject. We also update a existing file of our app, probably app.js or something. Finally we do npm run start to make sure it works and we commit.

Basically, those instructions have two purposes:

Get the job done. Pretty obvious.
Help us understand what's going on. That's important. After all, these changes will be part of our codebase so we need to have at least a basic understanding of what we just did.

While the second point is well addressed, the first one can be improved. Here is how.

How to install Tailwind with NextJS

Tailwind CSS setup with NextJS is simple and classic. It involves six steps. Three are commands to run, the other three are files to edit.

In a nutshell:

In one hand, I appreciate to roughly understand what I'm doing. For example, what I need to add to global.css and why. In the other hand, I don't try to learn or memorize anything. The next time I need to install Tailwind, I'll follow these steps again.

Same, just faster

At some point, we need to add the following lines to our tailwind.config.js:

  content: [
    "./pages/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
  ],

Good to know. This is how our .jsx files will be part of the processing loop. But editing tailwind.config.js manually? I'm not particularly interested.

This is where nstal comes into play.

nstal is a new open source project to write install procedures, called nstallers, and automate them. At the beginning, an nstaller is just a regular web page. For example:

Not very different of the official Tailwind website, is it?

Except for this strange notice at the top of the page:

Run the command above in a shell and suddenly the instructions morph:

Click the "Run" button and nstal really fills tailwind.config.js with the expected content, in a split second.

A demo is worth a thousand words, especially when it is mostly clicking buttons. Check the Tailwind + NextJS nstaller.

Anatomy of an nstaller

Nowadays many technical articles are written in Markdown (like the one you're reading). An nstaller is written in MDX. In other words, Markdown + JSX.

Here is how to write the previous instruction:

import { CreateFile } from '@nstaldev/react-core'
import tailwindConfig from './tailwind.config.js.txt'

## Configure your template paths

Add the paths to all of your template files in your `tailwind.config.js` file.

<CreateFile
  path='tailwind.config.js'
  content={tailwindConfig}
/>

Wanna give is a try? Write your first nstaller!

Conclusion

Web install procedures haven't changed since, well, the beginning of the Web. Maybe it's time for an upgrade. We can offer a better experience to developers tired of clicking the "copy" button and pasting in their codebase.

The goal of nstal is to change the deal, for tech readers and writers. Interested? Let's connect!

Tech blogging: a new way to write tutorials

Philippe Bernard — Mon, 30 May 2022 09:22:49 +0000

Software development is moving so fast. As a web developer, the only thing that remained more or less stable during the last 20 years is HTML. Seriously. Even CSS was not widely used when I started.

Languages, tools, practices... Everything changed, for the better.

But in this ocean of ever-changing areas, there is one field that stayed the same: tutorials.

Two decades of innovation in three bullets

A tutorial is a set of instructions. We usually follow a tutorial to learn something while actually doing it. Since the beginning of the web, tutorials have been regular text.

New and noteworthy:

Starter repositories: thanks to platforms such as GitHub, it is easy to provide a codebase readers can start from.
Online code editors for instant experiments: a tutorial can offer a sandbox to play with (Code Sandbox, CodePen...), so readers don't have to type anything.
Video tutorials: a tutorial doesn't have to be text anymore. It can be a YouTube video.

These are three great ways to enhance the tutorial consumer experience. Although I probably forget some, the list is quite small.

What a tutorial is and what to do about it

Tutorials serve two purposes:

Learn something
Do something

These two aspects don't have to be 50/50.

Sometimes, we want to master a new technology. We're not interested in principles or mere statements. We really want to be able to use it. A tutorial is often the right level of details, because it carries the promise that all the steps are there. By reading and following them carefully, we'll know exactly how to do the thing.

In other situations, we are here to get the job done. For example, we are using the ABC framework and need to setup the XYZ add-on. We are looking for precise instructions we can follow while understanding what we're doing.

Or we can feel like a tutorial is the right way to learn. A mix between passive and active learning.

When reading a tutorial, it is usually simple to skip the "learning" part. Most "actions" are easy to spot because they use a particular font to ask us to edit a-particular-file. Or they involve a bunch of code lines we can't miss.

Therefore, we can can go straight to the "doing" parts when this is what we want. That's important. With so many information and tasks to deal with, speed is a valuable option.

But what about the actions?

Sometimes, we value the manual procedure. Switch to our code editor to modify a file. Run a command. Commit. This is a way to improve our learning.

But other times, we don't really care. We value the time spent more than the learning boost the manual handling provides. When a tutorial asks us to add three lines at the end of a file, we would like to tell it: could you do it for me?

Introducing nstal

I've started to create nstal, which you can use to write nstallers. An nstaller looks like and feels like a regular tutorial, but its actions can be run automatically. The goal of this project is to enhance the tech blogging experience.

Just a regular tutorial...

At first, an nstaller is a regular web page. This means we can use nstallers the way we use the web. Browse. Search. Bookmark. You name it.

An nstaller is classic content by default: at the beginning, this is just a tutorial. We can consume it like any other content.

For example, an nstaller can contain:

... until you run `npx nstal`

However, at the top of the nstaller, there is an instruction:

We are asked to run npx nstal from an empty directory.

We can ignore this request and read yet-another tutorial. So far so good.

If we run nstal, the nstaller UI changes:

The Run button does exactly what the label suggests. Click it and the couple of commands are run in the directory where we ran nstal. No copy/paste, no need to leave our browser. It will be the same for the next step. And the next. And the next.

There's a demo you can try right away.

Benefits

As a reader

For the reader, the obvious benefit is speed. In theory, an nstaller can be used in seconds, since all of its steps can be automated.

But the change is more profound. The actual benefit is the options it offers regarding time/automation. With an nstaller, we can:

Read the tutorial carefully in order to learn something, but have all the steps executed for us because we think copy/paste code isn't that useful.
Have all the steps executed at once, as fast as possible, because we just want to get it done and move to the next task. This is typically what we want when going through the on-boarding process of a tool or a component we want to setup.
Run some of the steps automatically and some manually, when we think we should not follow the tutorial word by word.
...

As an author

For a tech blogger, the benefit is value-added content and novelty. It's hard to compete in this crowded area, where everything has already been written by talented and well-established people and companies. nstal could pave the way for a new kind of content, with a first-mover advantage that haven't been seen since the early beginnings of tech blogging.

nstal is a set of React components that can be used with MDX. In other words, we can still write Markdown and use nstal components only when we need them. The learning curve is quite flat.

Because nstal doesn't require any server code, it fits static websites. No need to rebuild our existing blog from scratch.

What's next

The projects has just started. The code is not even open sourced yet. But you can already try it by following the very first nstaller ever.

Follow me on HN or Twitter to get the latest news!

Automated Twitter banner to show your #100DaysOfCode progress

Philippe Bernard — Mon, 22 Nov 2021 08:54:20 +0000

Its name is pretty clear: the #100DaysOfCode challenge is about coding at least one hour per day, everyday, for 100 days. It's a great way to push yourself to act. Especially if you are a seasoned procrastinator like me 😅

In addition to coding, the challenge comes with a few extra rules. Among them, you are supposed to fork a repository and use it to log your daily activity in a markdown file.

It's cool and useful, but there is little chance that it will be noticed. After all, this repository has been forked 10K+ times, and Twitter is cluttered with #100DaysOfCode hashtags.

To give me a good start, I decided to show my progress in my Twitter banner. Like this:

Disclaimer: I faked my progress to produce this screenshot. If you wanna know what my progress actually is, visit my Twitter profile 😁

How does that work? First, there is a banner template I created with Resoc. Then, I added a GitHub Action to my forked #100DaysOfCode repository. This action parses my log to get my progress, generates a banner image and upload it to Twitter.

In this article, I explain how you can build you own automated Twitter banner. When I say "your own", I really mean it. Your image will look exactly the way you want and embed the data you want. Would you like it to show your follower count? Something else? That will be up to you.

And now for the good news: as long as you brand the banner to make it yours, following this tutorial counts as your daily hour of coding! 🎉🚀🤣

Prepare the repository

Before we create any file, we need a repository. If you already follow the #100DaysOfCode challenge and have forked the official GitHub repository, you're all set! Otherwise, even if you don't do the challenge, get your copy to follow the tutorial.

Fork the #100DaysOfCode GitHub repository:

Get the URL of your new repository:

And clone it:

git checkout [Your repo URL]

The project is quite light. Actually, we will use only one file, log.md. This is the file we update on a daily basis with our progress:

# 100 Days Of Code - Log

### Day 0: February 30, 2016 (Example 1)
##### (delete me or comment me out)

**Today's Progress**: Fixed CSS, worked on canvas functionality for the app.

**Thoughts:** I really struggled with CSS, but, overall,
I feel like I am slowly getting better at it. Canvas is still new for me,
but I managed to figure out some basic functionality.

**Link to work:** [Calculator App](http://www.example.com)

...

So far so good.

Talking about repository, the tutorial repository is available, too. Have a look into it if something goes wrong as you follow the tutorial.

Your Twitter banner template

It's time to design the Twitter banner. We create a Resoc image template, made of HTML and CSS:

cd 100-days-of-code
npx itdk init -m twitter-banner resoc-twitter-banner

This command creates a new template based on the twitter-banner starter template, in a sub-directory called resoc-twitter-banner, and opens a new browser:

On the left, we have a default banner template. On the right, there is a form with a single parameter: the follower count. At the bottom, the editor shows us how we can generate actual images. Curious to see this in action? Try it! Type a follower count in the form, copy/paste the command line and run it.

This template is a good start but it's not what we want.

First, this template takes a single parameter: a follower count. Our banner should display our #100DaysOfCode progress. More precisely, it should show the day and the previous activity (legend: green dot for an active day, red dot for a missed day):

Edit resoc-twitter-banner/resoc.manifest.json and replace its content with:

{
  "imageSpecs": {
    "destination": "TwitterBanner"
  },
  "partials": {
    "content": "./content.html.mustache",
    "styles": "./styles.css.mustache"
  },
  "parameters": [
    {
      "name": "day",
      "type": "number",
      "demoValue": "2"
    },
    {
      "name": "activity",
      "type": "objectList",
      "demoValue": [
        { "status": "completed" },
        { "status": "missed" },
        { "status": "completed" }
      ]
    }
  ]
}

There are two entries in the parameters section. The first parameter is called day, is a number and has a demo value of 2. By the way, first day of the #100DaysOfCode challenge is Day 0, not Day 1. We are developers after all 😋. The second parameter is less obvious. Named activity, it lists the status of all days so far. completed means we coded for at least an hour, missed is for, well, rest days 😅. The demo value is plain JSON.

Now let's write HTML. Fill resoc-twitter-banner/content.html.mustache with:

<div class="wrapper">
  <h1 id="title">
    Working on Resoc while doing the #100DaysOfCode Challenge
  </h1>
  <div class="challenge-progress">
    <div class="caption">
      <span>
        #100DaysOfCode Challenge
      </span>
      <span>
        Day {{ day }}
      </span>
    </div>
    <div class="progress">
      {{#activity}}
        <div class="daily-activity {{ status }}"></div>
      {{/activity}}
    </div>
  </div>
</div>

In this file we see how to use the parameters: Day {{ day }} becomes Day 87 when the day parameter is set to... 87. The activity parameter is iterated to produce a bunch of div, one per day. Each div is assigned the daily status as a CSS class. This syntax is Mustache, a simple yet powerful templating system.

Last but not least, the CSS. Open resoc-twitter-banner/styles.css.mustache and populate it with:

@import url('https://fonts.googleapis.com/css2?family=Raleway&display=swap');

.wrapper {
  background: rgb(11,35,238);
  background: linear-gradient(70deg, rgba(11,35,238,1) 0%, rgba(246,52,12,1) 100%);
  color: white;
  font-family: 'Raleway';

  display: flex;
  flex-direction: column;
  padding: 2vh 3vw 2vh 3vw;
}

#title {
  flex: 1.62;
  font-size: 13vh;
  height: 100%;
  text-align: right;
  margin-left: 20vw;
  letter-spacing: 0.05em;
}

.challenge-progress {
  flex: 0.8;
  display: flex;
  flex-direction: column;
  margin-left: 30%;
  gap: 2vh;
}

.caption {
  font-size: 9vh;
  font-weight: bold;
  display: flex;
  justify-content: space-between;
}

.progress {
  background-color: white;
  border-radius: 1vh;
  height: 7vh;
  display: flex;
  align-items: center;
  padding-left: 0.2vw;
  padding-right: 0.2vw;
}

.daily-activity {
  display: inline-block;
  width: 0.8%;
  margin-left: 0.1%;
  margin-right: 0.1%;
  height: 6vh;
  border-radius: 1vh;
}

.completed {
  background-color: #2e7d32;
}

.missed {
  background-color: #c62828;
}

That's a few lines of CSS, but nothing fancy. Just regular web design. That's the great part: we reuse our know-how.

Go back to the template editor. Our changes have been reloaded while we were editing:

Great! Now we have a banner template we can turn into images.

Generate and update the banner

Now we are going to parse the challenge log file, generate the banner with the data we found and upload it to Twitter.

So far, this project has been quite static. It's time to add some code. Create a NPM project:

# Still in 100-days-of-code
npm init -y

At the root of the project, create update-twitter-banner.js:

const updateTwitterBanner = async() => {
  // Do something smart
}

try {
  await updateTwitterBanner();
  console.log("Done!");
}
catch(e) {
  console.log(e);
}

Also edit package.json to run this script (add type and update-twitter-banner):

   ...
  "type": "module",
  "scripts": {
    "update-twitter-banner": "node update-twitter-banner.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ...

Run the script just to make sure you are on track:

npm run update-twitter-banner

# prints: Done!

For clarity, the following sections will focus on code snippets, not the entire file. If you plan to copy/paste, don't worry: there is a full recap at the end.

Parsing the log file

The log file is a safe place: no one will edit it but us. Therefore we can assume its format will remain consistent. The rules:

Each day section starts with ### Day [the day number]: [the date].
When there is a day when we don't code, we don't create the corresponding section. In other words, I know I didn't code on day 82 because I can't find ### Day 82: anywhere in my log file.

Let's parse the file with these conventions in mind:

let currentDay = -1;
const activeDays = [];
const log = await fs.promises.readFile('log.md', { encoding: 'utf8' });
log.split('\n').forEach(line => {
  const m = line.match(/### Day (\d+):/);
  if (m) {
    const day = parseInt(m[1]);
    activeDays.push(day);
    if (day > currentDay) {
      currentDay = day;
    }
  }
});

const daysStatus = new Array(currentDay + 1).fill(false);
activeDays.forEach(day => {
  daysStatus[day] = true;
});

console.log(`At day ${currentDay}`);
console.log('Days I have been active', activeDays);
console.log('Status, day by day', daysStatus);

Generating the banner

For this part, we are going to cheat. Remember the Resoc template editor? In the bottom panel, JavaScript tab, we get the instructions to create an image from our script:

Let's do as instructed:

npm install @resoc/core @resoc/create-img

We cannot use the provided code as is because it is using the demo values. We adapt it to use the data we got from parsing:

const bannerFileName = 'new-banner.png';

await createImage(
  'resoc-twitter-banner/resoc.manifest.json',
  {
    day: currentDay.toString(),
    activity: daysStatus.map(status =>
      ({ status: status ? 'completed' : 'missed' }))
  },
  { width: 1800, height: 600 },
  bannerFileName
);

At this point, you might want to run the script and make sure new-banner.png is created and match your log file.

Replace the existing banner on Twitter

We update the Twitter banner with only one line of code! Problem: there are a lot to prepare for this command to work. No time to waste!

Secure credentials management with dotenv

We are about to obtain a few credentials from Twitter. An app secret, etc. This kind of data cannot be stored in our code. Seriously. These credentials will give access to your Twitter account and your #100DaysOfCode repo is public. So don't store them in your code!

Instead, configure dotenv:

npm install dotenv
touch .env
echo .env >> .gitignore # Important!

The .env file will contain the Twitter credentials. Because we added it to .gitignore, we won't commit it by mistake.

Make sure the environment variables we will declare in .env will be available in our code. At the top of update-twitter-banner.js, add:

import dotenv from 'dotenv';
dotenv.config();

Twitter App

To access our Twitter account, we need a Twitter App.

Make sure you are connected to Twitter. If you have multiple accounts, select the right one. Then, visit the Twitter Developer Platform and sign up:

Fill the sign up form:

Accept the terms, which you obviously read 🙄

Next, you are asked for an app name:

On the next page, you are presented your Twitter API credentials:

Save your credentials. Copy/paste the API key and key secret from the Twitter Dev Platform to your .env file:

TWITTER_API_KEY=[your API key]
TWITTER_API_SECRET=[your API key secret]

Once your keys are saved, go to your dashboard and edit the settings of your app:

For now our app has a read only permission. Because it will update our banner, we need to make it read and write. Edit the permissions:

Change the permission and save:

Now we are going to create another set of credentials so our app can access our Twitter account. From the dashboard, edit the keys of the app:

Generate an access token and secret:

A popup appears with additional credentials:

You know the procedure. Add two more lines to your .env file:

...
TWITTER_ACCESS_TOKEN=[your access token]
TWITTER_ACCESS_TOKEN_SECRET=[your access token secret]

There is one last step to prepare the Twitter app. By default, the app can use the Twitter API v2. Problem: the entry point we need is only available in v1.1, which require an elevated access.

From the dashboard, go to the Twitter API v2 (left sidebar), Elevated tab, and click Apply for Elevated:

Validate your basic information:

On the next screen, you are asked how you will use the the API. Here, the goal is to reassure Twitter: we won't do anything tricky with our app. For example, we won't steal user data, FB / Cambridge Analytica style. This is the message I used:

I request the elevated access only to use the account/update_profile_banner entry point on my own account.

I don't plan to use the API to access any other account.

Please let me know if you need additional information.

Use it as is or write your own:

Also uncheck all specifics and click Next:

Review your submission and click Next:

Agree to the terms again:

Congratulations! Well... almost:

That's the boring part: you have to wait for Twitter validation. For me it took less then 24 hours and I hope it won't be longer for you.

At this point, you can bookmark this article and come back to it again when you receive Twitter's approval.

A brief list of things you can do while waiting:

Comment this article: how was the process so far?
Share this article on Twitter — Maybe you've just completed your daily hour of coding!
Follow me on Twitter — I'm creating Resoc and document my journey.

Update the banner — at last

Twitter app approved? Great!

Install the Twitter client API:

npm install twitter-api-client

Thanks to this great client, the code is straightforward. In update-twitter-banner.js, at the end of updateTwitterBanner:

const twitterClient = new TwitterClient({
  apiKey: process.env.TWITTER_API_KEY,
  apiSecret: process.env.TWITTER_API_SECRET,
  accessToken: process.env.TWITTER_ACCESS_TOKEN,
  accessTokenSecret: process.env.TWITTER_ACCESS_TOKEN_SECRET,
});

const banner = await fs.promises.readFile(bannerFileName, { encoding: 'base64' });

await twitterClient.accountsAndUsers.accountUpdateProfileBanner({ banner });

As a summary, here is the full update-twitter-banner.js:

import dotenv from 'dotenv';
dotenv.config();

import fs from 'fs';
import { TwitterClient } from 'twitter-api-client';
import { createImage } from '@resoc/create-img';

const updateTwitterBanner = async() => {
  let currentDay = -1;
  const activeDays = [];
  const log = await fs.promises.readFile('log.md', { encoding: 'utf8' });
  log.split('\n').forEach(line => {
    const m = line.match(/### Day (\d+):/);
    if (m) {
      const day = parseInt(m[1]);
      activeDays.push(day);
      if (day > currentDay) {
        currentDay = day;
      }
    }
  });

  const daysStatus = new Array(currentDay + 1).fill(false);
  activeDays.forEach(day => {
    daysStatus[day] = true;
  });

  console.log(`At day ${currentDay}`);
  console.log('Days I have been active', activeDays);
  console.log('Status, day by day', daysStatus);

  const bannerFileName = 'new-banner.png';

  await createImage(
    'resoc-twitter-banner/resoc.manifest.json',
    {
      day: currentDay.toString(),
      activity: daysStatus.map(status => ({ status: status ? 'completed' : 'missed' }))
    },
    { width: 1800, height: 600 },
    bannerFileName
  );

  console.log("New banner generated");

  const twitterClient = new TwitterClient({
    apiKey: process.env.TWITTER_API_KEY,
    apiSecret: process.env.TWITTER_API_SECRET,
    accessToken: process.env.TWITTER_ACCESS_TOKEN,
    accessTokenSecret: process.env.TWITTER_ACCESS_TOKEN_SECRET,
  });

  const banner = await fs.promises.readFile(bannerFileName, { encoding: 'base64' });

  await twitterClient.accountsAndUsers.accountUpdateProfileBanner({ banner });

  console.log("Twitter banner updated");
}

try {
  await updateTwitterBanner();
  console.log("Done!");
}
catch(e) {
  console.log(e);
}

Update your Twitter banner! Run:

npm run update-twitter-banner

After a few seconds, your banner should be updated. Visit your Twitter account: how cool is it?

Twitter banner automation with GitHub Actions

We already push to Git once per day to log our #100DaysOfCode daily activity. So if we have GitHub regenerate our Twitter banner on push, we achieve full automation.

For this task, we use GitHub Actions. Actions are the core of GitHub's solution for CI/CD (Continuous Integration / Continuous Delivery).

Create a file named .github/workflows/update-twitter-banner.yml and fill it with:

name: Update Twitter Banner
on: [push]
jobs:
  Update-Twitter-Banner:
    runs-on: ubuntu-latest
    environment: twitter-credentials
    steps:
      - name: Check out repository code
        uses: actions/checkout@v2
      - name: Setup Node
        uses: actions/setup-node@v2
      - name: Install dependencies
        run: npm ci
      - name: Run the update script
        env:
          TWITTER_API_KEY: ${{ secrets.TWITTER_API_KEY }}
          TWITTER_API_SECRET: ${{ secrets.TWITTER_API_SECRET }}
          TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
          TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
        run: npm run update-twitter-banner

Although this syntax may not be familiar, this action is quite easy to read. It is triggered on push. It is run by an Ubuntu instance. It uses an environment named twitter-credentials that we are going to create in a moment. The rest: checkout our code, setup a Node environment, install the project dependencies and finally run update-twitter-banner with all the Twitter credentials as environment variables.

The last piece we need is the twitter-credentials environment. Remember the .env file we created but didn't commit to git? We must provide Twitter keys to GitHub in a way or another, and this is what this environment is for. Got to your project on GitHub, Settings tab, Environment in the sidebar and click New environment:

Type twitter-credentials as the environment name and click Configure environment:

In the next page, use the Add secret button at the bottom:

In the popup, set TWITTER_API_KEY as the secret name and the actual key as its value:

Repeat the process for TWITTER_API_SECRET, TWITTER_ACCESS_TOKEN and TWITTER_ACCESS_TOKEN_SECRET. When you're done, the environment secrets look like this:

GitHub Action ready!

Got back to your project. Add an entry to log.md to indicate you setup your dynamic Twitter banner. Commit everything and push.

On GitHub again, click the Actions tab. After a few seconds, your action is running:

Click the running instance to watch it run:

When it's completed, visit your Twitter profile. Your banner reflect today's progress. Victory!

Conclusion

Congratulations! You now have one of the coolest Twitter banners, no less!! I hope you enjoyed the process as much as I did. Experimenting with Resoc, the Twitter API and GitHub Actions have been a lot of fun to me.

Now, you have to show me what you did. Please, mention me so I can review what you created!

Oh, I'm creating Resoc, a set of open source tools and components to create and deploy image templates, the major target being automated social images. Wanna know how it goes? Follow me on Twitter!

React dev? Why and how you should use Storybook

Philippe Bernard — Fri, 05 Nov 2021 07:35:19 +0000

There are plenty of great tools in the React ecosystem. But only a few ones that are must-use. Storybook is one of them.

If you don't know Storybook, I have great news! The reasons to use Storybook are obvious and it's very easy to start with!

What is Storybook and why you need it

You install Storybook, write a story (more on this later), launch Storybook and you get this:

See the blue rectangle? This is one of your React components. The rest is a UI provided by Storybook.

Storybook provides a per-component sandbox so you can quickly use your components, one at a time.

How is this useful?

Direct access

There is always this component you are working on which is buried in your app. You need three clicks to reach it. The first times are okay, but at some point it begins to be boring and disrupt your flow.

With Storybook, you have a story which renders your component exactly the way you want it. Hot reloading included.

All states at once

How to show a component, but not just with one particular set of properties? With Storybook, this is just natural.

Sandbox for debugging

Sometime, you need to isolate a component to debug it and hack around. With Storybook, you can do this in seconds... When you don't have written the story already!

Document as you try your component

Stories are not write-and-trash code. Once your story is ready, you commit it and make it part of your code base. It becomes a great resource for you and your team.

There are several others reasons to love Storybook. The ones above are just my favorite, why Storybook is part of 100% of my React projects.

Getting started with Storybook

Quick! Install it!

cd your/react/project
npx sb init

Now it's ready to start:

npm run storybook

Storybook opens a new tab, showing its welcome screen:

During install, Storybook creates a few demo stories. Click the "Button" demo on the left:

The blue button with rounded corners is a demo component, but it could be one of yours. The Controls tab below lets you quickly play with the component. Cool!

Look at the existing demo stories in src/stories/Button.stories.jsx:

import React from 'react';

import { Button } from './Button';

// More on default export: https://storybook.js.org/docs/react/writing-stories/introduction#default-export
export default {
  title: 'Example/Button',
  component: Button,
  // More on argTypes: https://storybook.js.org/docs/react/api/argtypes
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

// More on component templates: https://storybook.js.org/docs/react/writing-stories/introduction#using-args
const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
// More on args: https://storybook.js.org/docs/react/writing-stories/args
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

In this file, half of the code is Storybook-related. You can either choose to understand and memorize it, or just copy/paste and adapt it when you start a new file. Fair enough. The other half is about your component. In this demo, size, primary and label, or the fact that you need four stories named Primary, Secondary, Large and Small are completely related with the demo button, not Storybook itself.

Create a file somewhere in src, name it after your component, eg. MyComp.stories.jsx, populate it with the content of src/stories/Button.stories.jsx and start telling your own stories!

Conclusion

There are many worthwhile React tools around. But Storybook is probably the only one I recommend whatever the project - as long as React is involved. I hope I convinced you to give it a try!

And if you actually write your first story, please let me know !

How do DEV cover images work anyway?

Philippe Bernard — Thu, 28 Oct 2021 07:25:09 +0000

There is something I don't get with DEV cover images.

I have prepared this image:

It is a 1200x630 image, as expected by Facebook and as supported by most social networks and messaging services. That's a 1.91 ratio. When I say "expected" and "supported", I mean that the image is displayed as is when my article is posted.

But DEV does not work that way.

As I type this post, I can see the cover image I already assigned to it:

The top and bottom of the image are cropped. This is really how DEV displays cover images, with a 2.38 ratio.

How are we supposed to prepare cover images for DEV? Sure, it works pretty well with photos which remain consistent as long as you crop as much on one side as on the other.

But many technical writers craft their own cover images. In this scenario, DEV makes it kind of a dilemma. The only solution I found was to add artificial padding.

This is the generic cover image I prepared for a previous article:

When I wanted to publish it to DEV, I had to rework it a bit.

DEV image is still 1200x630 / 1.91, with extra padding at the top and bottom, which DEV crops:

As a workaround, it should be possible to assign a specific Open Graph image in the Post Options. That would help people like me to craft perfect cover image for DEV and social networks.

Automated social images on Netlify - with Next.js and Resoc

Philippe Bernard — Mon, 27 Sep 2021 06:53:23 +0000

The social images illustrate a web page on social networks and messaging services. For example, when I share this previous article on Slack, I get:

The green and pink image is attached to the shared page via an og:image meta markup.

The social images are a great opportunity to get attention. More often than not, this opportunity is wasted, because creating those image is quite boring. Unless they are automatically generated for us.

In this tutorial, we are going to:

Create a basic Next.js app
Create an image template with HTML and CSS, with the Resoc image template development kit
Use this template to generate our social images, thanks to the Resoc social image Netlify build plugin
Deploy our app to Netlify

When sharing your app with your colleagues, they will see:

If you can't wait, try it now or browse the code 😁

Create the Next.js app

Let's create a new app and start it:

yarn create next-app
yarn dev

Before implementing the social images, we first fix a little something with meta management. In our fresh app, the title markup is hard coded in the homepage. This is okay in a simple example, but a real app will have this kind of recurrent markup moved to a single layout.

Replace the content of pages/_app.js with:

import '../styles/globals.css'
import Head from 'next/head'

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Head>
        <title>{pageProps.title}</title>
        <meta name="description" content={pageProps.description} />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp

Our app now expects two page props, title and description, which are injected in classic head markups.

We need to modify the homepage and pass these two variables. In pages/index.js, we define getStaticProps for this purpose. We also remove the demo content for clarity:

import styles from '../styles/Home.module.css'

export default function Home() {
  return (
    <div className={styles.container}>
      No need for content
    </div>
  )
}

export async function getStaticProps(context) {
  return {
    props: {
      title: 'Automated social images on Netlify',
      description: 'With Next.js and @resoc/netlify-plugin-social-image'
    }
  }
}

Visit the app again. From now on, title and description values come from the pages and _app prints the markups:

Done with the setup!

Create the image template

How should our social images look like? This is what we are going to work on, with the Resoc image template development kit. Quit yarn dev for a moment and run:

npx itdk init resoc-templates/default -m title-description

This command creates a new image template in resoc-templates/default and opens a viewer in a browser:

The model we used via -m title-description takes two parameters: a title and a description. Later, we will make Next.js inject the correct metadata in the template, and Netlify create the images for us. For now, we modify the template so it matches our app.

Our app is gonna be hot, so let's replace the logo in the template. Overwrite resoc-templates/default/logo.png with the image below:

In our browser, the viewer shows the update:

Now, change the background color. In resoc-templates/default/styles.css.mustache, replace the background definition of .wrapper with:

background: rgb(247,58,12);
background: linear-gradient(90deg, rgba(247,58,12,1) 0%, rgba(247,99,12,1) 100%);

Our template is definitely hotter!

That's all for the template. We could have been much more creative, for example by imitating GitHub social images. This is a Resoc template:

Generate social images

The idea behind image generation is pretty simple: take the title and description from a page, take the image template, mix, et voilà! The two technologies at work are Mustache, a template system used to inject parameter's values, and Puppeteer, a headless Chrome system to convert HTML to images. However, we won't have to deal with these packages directly.

Each image needs a couple of seconds to be generated. With our demo app, that's not an issue. But in a real world example with hundreds of pages, this is clearly a concern. In particular, we don't want this process to take place at build time. Imagine your build time multiplied by 10... Cool social images don't worth such a wait. The Resoc social image Netlify plugin adresses the issue by using a Netlify Function to create our images on demand, not at build time. Problem solved.

Here is the process we are going to implement below:

In our app, each page has a slug. No big deal: index.js is homepage (a particular case, since index.js is linked to /), news.js is news, blog/huge-announcement.js is blog-huge-announcement, etc.
Pages register their image template parameters. In our app, each page saves its title and description for later use.
The app layout declares the social image using the page's slug, eg. /social-images/homepage.jpg.
A Netlify Function uses the image template parameters declared by the pages to actually create the social images, on demand.

Install the packages:

yarn add -D @resoc/netlify-plugin-social-image @resoc/core @resoc/img-data

We need to configure the plugin. At the root of the project, create netlify.toml:

[[plugins]]
package = "@resoc/netlify-plugin-social-image"
  [plugins.inputs]
  templates_dir = "resoc-templates"
  slug_to_image_data_mapping_file = "resoc-image-data.json"
  open_graph_base_path = "/social-images"

If you use Netlify you must be familiar with this syntax. But we need to explain those parameters.

templates_dir is the directory which contains our Resoc templates. Later, we will indicate that we want to use our template named default. This will be resolved as resoc-templates/default, which is where we created our sole template.

slug_to_image_data_mapping_file contains the data used to generate the social images.

open_graph_base_path is the base path we will use in our og:image markup.

We update pages/index.js:

import styles from '../styles/Home.module.css'
import { storeImageData } from '@resoc/img-data'

export default function Home() {
  return (
    <div className={styles.container}>
      No need for content, really
    </div>
  )
}

const prepareStaticProps = async (title, description, imgSlug) => {
  await storeImageData(
    'resoc-image-data.json',
    imgSlug, {
      template: 'default',
      values: { title, description }
    }
  );

  return {
    props: {
      title,
      description,
      imgSlug
    }
  };
}

export async function getStaticProps(context) {
  return await prepareStaticProps(
    "Automated social images for Next.js on Netlify",
    "With getStaticProps and @resoc/netlify-plugin-social-image",
    "homepage"
  );
}

We added a helper called prepareStaticProps. Here, we call a function named storeImageData. We pass it the title and description as template parameters, the page slug, and the template to use (we have only one and it is in the default sub directory). These data are saved to resoc-image-data.json, the file we assigned to slug_to_image_data_mapping_file in netlify.toml.

Because prepareStaticProps returns the page props, getStaticProps only needs to call it and return it as is.

This is good enough in our one page app. In a real app, prepareStaticProps should be reusable.

We must also update pages/_app.js:

import '../styles/globals.css'
import Head from 'next/head'
import { FacebookOpenGraph } from '@resoc/core'

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Head>
        <title>{pageProps.title}</title>
        <meta name="description" content={pageProps.description} />

        <meta property="og:title" content={pageProps.title} />
        <meta property="og:description" content={pageProps.description} />
        <meta property="og:image" content={`/social-images/${pageProps.imgSlug}.jpg`} />
        <meta property="og:image:width" content={FacebookOpenGraph.width} />
        <meta property="og:image:height" content={FacebookOpenGraph.height} />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp

We added the Open Graph markups.

og:title and og:description are just a repetition of existing markups, Open Graph style.

To build the URL in og:image, we use the plugin parameter open_graph_base_path declared in netlify.toml and the page slug.

For completeness, we also declare the image width and height using FacebookOpenGraph.width and FacebookOpenGraph.height.

We're done!

To make sure our app is in good shape, restart it:

yarn dev

Visit the homepage and inspect the head markup to make sure the Open Graph markups are correct.

We also notice a new file, resoc-image-data.json. If was created by getStaticProps.

Deploy to Netlify

yarn create next-app already initialized a Git repository for us.

Before we commit, let's add resoc-image-data.json to .gitignore to make sure it won't be committed. This file is generated at build time, which will be Netlify's responsibility.

Now, commit everything:

git commit -a -m "Social image!"

Now register to Netlify or login. Add a new site:

Use the Wizard to select your repository, leave the default values as they are and click "Deploy site". After a couple of minutes, our app is built and deployed.

Get its URL:

If we visit this URL, there is not much to see. After all, this is not where our social image shine. Instead, submit it to the Facebook debugger:

Hurray! The social image of our homepage was generated!

Conclusion

Automated social images have been around for a while. But creating them required a lot of custom code and efforts. Some solutions have been proposed, often at the expense of much longer builds.

Using the Resoc image template dev kit and the Resoc social image Netlify build plugin, we were able to setup automated social images quickly, with just the right amount of code. We even have spear time to perfect the template and make our images even more awesome!

I hope you enjoyed this article. If you followed this tutorial, I would be glad to get your feedback!

Automated social images: play it like GitHub

Philippe Bernard — Fri, 17 Sep 2021 12:09:14 +0000

A few months ago, GitHub introduced customized social images. What does it mean? If I share React's GitHub repos homepage on Slack, I get:

You can see the URL, title, description... but what must get most of your attention is the gorgeous image featuring the project name, Facebook logo and project metrics.

This mechanism relies on Open Graph, a set of HTML markups supported by almost all social networks and messaging apps. In particular, Open Graph lets you declare an image, often called the "social image" of your page. This image is used to illustrate your page whenever it is shared in a LinkedIn post, WhatsApp message, etc.

Most social images are generic, mundane and meaningless. GitHub's are specific, cool and meaningful.

With the Resoc image template development kit, you can do just the same.
In this article, we see how we can replicate what GitHub did with Resoc.

Create the template

We start by creating a new template:

npx itdk init github-social-image

A few seconds later, our browser opens a new tab, showing our brand new template:

Let's take a moment to see what an image template is.

An image template can be turned into an image. More exactly, a template can be turned into a lot of different, yet similar, images. In one hand, a template defines the elements which remain identical from an image to another. In our initial template, the logo in the bottom left corner never change. In the other hand, some elements change from an image to another. Here, the title, main image, text color and background colors are parameters.

We can easily imagine this template used to illustrate blog posts. A post has a title and a featured image which could be injected to get a dedicated image. The background color could change depending on the post category.

This template is fine, but we are here to mimic GitHub.

Just like GitHub, step by step

GitHub built great, content-rich images. Our goal is to imitate them:

Easy comparison

To track and facilitate our progress, let's configure the viewer to show both our template and a sample image from GitHub. Kill the process you started with npx itdk a minute ago and run:

npx itdk view github-social-image/resoc.manifest.json -fm https://github.blog/wp-content/uploads/2021/06/framework-open-graph-images_fig-3-nasa-fprime.png

The Facebook preview now has a range input. Slide to see our template or reveal the image we want to reproduce:

For the moment, our template doesn't look quite like GitHub's.

Parameters

Before working on the appearance of the template, we first need to define what the template will expect as parameters.

Let's review GitHub's sample image. It describes a project:

Organization, name and description
Profile image
Metrics: number of contributors, issues, etc.
Technologies (the colored bar at the bottom)

We now edit the template manifest to declare these parameters. Open github-social-image/resoc.manifest.json. Its content is straightforward:

{
  "partials": {
    "content": "./content.html.mustache",
    "styles": "./styles.css.mustache"
  },
  "parameters": [
    {
      "name": "title",
      "type": "text",
      "demoValue": "A picture is worth a thousand words"
    },
    {
      "label": "Main image",
      "name": "mainImageUrl",
      "type": "imageUrl",
      "demoValue": "https://resoc.io/assets/img/demo/photos/pexels-photo-371589.jpeg"
    },
    {
      "name": "textColor",
      "type": "color",
      "demoValue": "#ffffff"
    },
    {
      "name": "backgroundColor",
      "type": "color",
      "demoValue": "#20552a"
    }
  ]
}

Each parameter has a name, type, demonstration value and an optional label.

Let's modify it and declare the parameters we need:

{
  "partials": {
    "content": "./content.html.mustache",
    "styles": "./styles.css.mustache"
  },
  "parameters": [
    {
      "name": "organization",
      "type": "text",
      "demoValue": "nasa"
    },
    {
      "name": "project",
      "type": "text",
      "demoValue": "fprime"
    },
    {
      "name": "description",
      "type": "text",
      "demoValue": "F' - A flight software and embedded systems framework"
    },
    {
      "label": "Image",
      "name": "imageUrl",
      "type": "imageUrl",
      "demoValue": "https://avatars.githubusercontent.com/u/848102"
    },
    {
      "name": "contributors",
      "type": "number",
      "demoValue": "83"
    },
    {
      "name": "issues",
      "type": "number",
      "demoValue": "55"
    },
    {
      "name": "discussions",
      "type": "number",
      "demoValue": "5"
    },
    {
      "name": "stars",
      "type": "number",
      "demoValue": "8042"
    },
    {
      "name": "forks",
      "type": "number",
      "demoValue": "948"
    },
    {
      "name": "technologies",
      "type": "objectList",
      "demoValue": [
        { "color": "#f34b7d", "proportion": "30.7" },
        { "color": "#e34c26", "proportion": "23.3" },
        { "color": "#cccccc", "proportion": "18.5" },
        { "color": "#3572a5", "proportion": "14.8" },
        { "color": "#3d6117", "proportion": "4.9" },
        { "color": "#da3434", "proportion": "2.6" },
        { "color": "#ededed", "proportion": "5.2" }
      ]
    }
  ]
}

That's a lot of text, but no big deal. Except for the last parameter, technologies, which we will discuss later.

In the template viewer, we can see our new parameters:

(Web)Design

Our most important task awaits us: design! Although it is going to take some time, there is nothing complicated about it: we are going to use HTML, CSS and a little bit of JavaScript.

The HTML is going to github-social-image/content.html.mustache. .mustache? Mustache is a template language used by Resoc to make parameters accessible from our HTML code. Thanks to this addition, we can write things like <h1>{{ title }}</h1>, where {{ title }} will later be replaced with the actual title.

Populate github-social-image/content.html.mustache with:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400&display=swap" rel="stylesheet">

<div class="wrapper">
  <main>
    <div class="project">
      <p class="title">
        {{ organization }}/<span class="project-name">{{ project }}</span>
      </p>
      <p class="description">
        {{ description }}
      </p>
    </div>
    <div class="pic">
      <img src="{{ imageUrl }}" />
    </div>
  </main>

  <div class="secondary">
    <div class="metrics">
      <div class="metric">
        <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/people-24.svg" />
        <div>
          <p class="metric-data">{{ contributors }}</p>
          <p class="metric-label">Contributors</p>
        </div>
      </div>

      <div class="metric">
        <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/issue-opened-24.svg" />
        <div>
          <p class="metric-data">{{ issues }}</p>
          <p class="metric-label">Issues</p>
        </div>
      </div>

      <div class="metric">
        <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/comment-discussion-24.svg" />
        <div>
          <p class="metric-data">{{ discussions }}</p>
          <p class="metric-label">Discussions</p>
        </div>
      </div>

      <div class="metric">
        <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/star-24.svg" />
        <div>
          <p class="metric-data">{{ stars }}</p>
          <p class="metric-label">Stars</p>
        </div>
      </div>

      <div class="metric">
        <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/repo-forked-24.svg" />
        <div>
          <p class="metric-data">{{ forks }}</p>
          <p class="metric-label">Forks</p>
        </div>
      </div>
    </div>
    <div class="github-logo">
      <img src="https://raw.githubusercontent.com/primer/octicons/main/icons/mark-github-16.svg" />
    </div>
  </div>

  <div class="techs">
    {{#technologies}}
      <div style="background-color: {{ color }}; flex: {{ proportion }}"></div>
    {{/technologies}}
  </div>
</div>

<script>
  var formatter = Intl.NumberFormat('en', { notation: 'compact' });
  var data = document.querySelectorAll(".metric-data");
  for (var i = 0; i < data.length; i++) {
    data[i].innerHTML = formatter.format(data[i].innerHTML);
  }
</script>

Again, that's quite verbose but nothing intimidating. The structure of the content is easy to read, with three main parts: the project data, the metrics and the technologies.

The metrics are a bit verbose because of repetition. We can certainly live with it.

Although short, the technologies are the most strange part. Remember the corresponding parameter from github-social-image/resoc.manifest.json? It says:

{
  "name": "technologies",
  "type": "objectList",
  "demoValue": [
    { "color": "#f34b7d", "proportion": "30.7" },
    { "color": "#e34c26", "proportion": "23.3" },
    { "color": "#cccccc", "proportion": "18.5" },
    { "color": "#3572a5", "proportion": "14.8" },
    { "color": "#3d6117", "proportion": "4.9" },
    { "color": "#da3434", "proportion": "2.6" },
    { "color": "#ededed", "proportion": "5.2" }
  ]
}

Its type is objectList and the demo value gives an overview of what is expected: a set of technologies made of color and proportion. The demo reflects the technologies used by nasa/fprime:

Back to github-social-image/content.html.mustache, we can use this parameter to iterate over the technologies:

<div class="techs">
  {{#technologies}}
    <div style="background-color: {{ color }}; flex: {{ proportion }}"></div>
  {{/technologies}}
</div>

Inside the #technologies block, color and proportion are available.

That's our template at this point:

It's ugly, but most of the content looks okay.

Time for styles! Open github-social-image/styles.css.mustache and paste:

.wrapper {
  display: flex;
  flex-direction: column;
  align-items: stretch;
  font-family: Roboto;
  background-color: white;
}

main {
  flex: 10;
  display: flex;
  align-items: top;

  padding-top: 14vh;
  padding-left: 13vh;
  padding-right: 13vh;
}

.project {
  flex: 3;
}

.title {
  margin-top: 0;
  font-size: 13.5vh;
  margin-bottom: 0;
}

.project-name {
  font-weight: bold;
}

.description {
  margin-top: 4.1vh;
  font-size: 5.4vh;
  color: #666;
  line-height: 8.7vh;
}

.pic img {
  max-width: 32vh;
  width: 100%;
  height: auto;
}

.secondary {
  flex: 5.5;

  display: flex;
  padding-left: 13vh;
  padding-right: 13vh;
  justify-content: space-between;
  align-items: center;
}

.metrics {
  display: flex;
  flex-direction: row;
  gap: 8vh;
}

.metric {
  display: flex;
  align-items: start;
  gap: 2.5vh;
  color: #71747f;
}

.metric img {
  margin-top: 1vh;
  height: 4.5vh;
  /* https://codepen.io/sosuke/pen/Pjoqqp + #71747f */
  filter: invert(46%) sepia(3%) saturate(1349%) hue-rotate(190deg) brightness(96%) contrast(85%);
}

.metric-data {
  margin: 0;
  font-size: 5vh;
  color: #2f363d;
}

.metric-label {
  margin: 0;
  margin-top: 1.5vh;
  font-size: 4vh;
}

.github-logo {
  test-align: right;
}

.github-logo img {
  height: 7.5vh;
  /* https://codepen.io/sosuke/pen/Pjoqqp + #8492af */
  filter: invert(66%) sepia(6%) saturate(1691%) hue-rotate(185deg) brightness(88%) contrast(80%);  
}

.techs {
  flex: 0.7;
  display: flex;
}

That's CSS as usual. And the result is quite good:

How similar is it to the orignal image?

GitHub is using font "Alliance", which is not free. We used the trusty Roboto instead. And most elements are not strictly identical. Well, that's good-enough for this exercise in my opinion.

From template to image

We have a great template. Now we want to turn it into images. How many?

A lot of, probably. 😅

Command line

We can generate images from the command line. The template viewer provides us a sample command line.

The example can be used as, just launch it where you run npx itdk. The rest is up to us. For example, we could tweak the command line to generate social images from a bash script.

JavaScript

If we want to create images from our code, we also have a working example to start from:

Again, this example should be adapted to fit our build process. For example, we could create social images for a NextJS app.

Conclusion

Automated, per-page social images are both cool and useful. All the components needed to build them have been around for years: HTML & CSS, Puppeteer and templating system. But so far, the developer experience has been quite poor. Too much setup, too much topic to experiment with, no tools...

Until now. The Resoc image template development kit fills this gap, from template creation to build process. What's next? Simplify the deployment even more.

Replace ImageMagick with HTML & CSS

Philippe Bernard — Mon, 13 Sep 2021 06:45:12 +0000

I read an article by Zach Leatherman about bulk og images generation. He explains how he used ImageMagick to generate a bunch of Open Graph images.

More precisely, he wrote a simple bash script with two calls to ImageMagick. The script converts this:

To this:

Even if ImageMagick is convenient, I think it's not the best tool for this particular task. Let's see why, and what to do about it.

Why not ImageMagick?

ImageMagick is an awesome tool. I used it a lot for RealFavicon and bulk jobs. However, I see a few issues here.

Not just a CLI tool: a new language

Usually, we use ImageMagick from the command line. Command line? You might think cd, ls or echo. But ImageMagick is not of that kind. It's more like sed or awk: as complex as it is powerful.

Look at Zach's code:

# resize image
convert "$i" -resize x530 -background $bgColor \
  -gravity center -extent 1200x630 "tmp/${i##*/}"
# add watermark
composite -gravity SouthEast -geometry +20+20 \
  "tmp/watermark.png" "tmp/${i##*/}" "${outputDir}${i##*/}"

convert, -resize, -gravity, -extent... This is new vocabulary we have to learn.

ImageMagick has a great documentation, with a lot of examples we can start from. Yet, be ready to go on an adventure.

Don't get me wrong: I'm sure Zach is fluent with ImageMagick and was able to write this script in a few minutes. However, I can't do this. I know ImageMagick just enough to use its doc effectively. In other words, I'm good at finding the right examples and copying them wisely. 😅

Inconvenient trial and error

When creating something visual with code, we can't expect to achieve the perfect design on the first try, whatever the technology. "Text should be a bit larger", "We won't need that much padding", and so on. So we need a convenient feedback loop.

ImageMagick is not ideal here.

Zach's script iterates over a lot of images. That's the point. But during the tuning phase, this is counterproductive. Basically, we need to hack in a way or another:

Replace *.png with rocket.png to select only one image.
Prepare the ImageMagick command lines from a terminal and copy/paste them to the script when we're ready.
...

ImageMagick doesn't scale well

This one it a bit out of scope here because we create rather simple images. But in general, ImageMagick is not convenient for complex compositions.

Either we need to produce several intermediate images, heading for the final image at each step. Zach creates one in his demo. Or we write a single super command which does everything. I'm sure Zach's commands could be merged.

In both cases, it's hard to write and maintain.

The HTML way

In this section, we are going to address these issues.

First, we use HTML and CSS. The reason is obvious: we already know them. No more ImageMagick multiverse.

We also use the Resoc image templating system. It will help us build a template, with reload-as-you-type feature for instant feedback loop.

Can't wait? You can check the demo repo.

Create the template

Let's go:

mkdir 1-million-devs
cd 1-million-devs
npx itdk init resoc-template

The last command creates a sample image template in resoc-template and opens it in the browser:

On the right panel, we see what the template expects as parameters. Our template will mimic Zach's script:

Path to the main image
Path to the watermark image
Background color

Let's edit 1-million-devs/resoc-template/resoc.manifest.json. We can adapt the existing content to define our own manifest:

{
  "partials": {
    "content": "./content.html.mustache",
    "styles": "./styles.css.mustache"
  },
  "parameters": [
    {
      "label": "Main image",
      "name": "mainImage",
      "type": "imageUrl",
      "demoValue": "rocket.png"
    },
    {
      "name": "logo",
      "type": "imageUrl",
      "demoValue": "netlify-logo.png"
    },
    {
      "name": "backgroundColor",
      "type": "color",
      "demoValue": "#00dc9e"
    }
  ]
}

Back to the browser, we can see that these new parameters were taken into account:

To get a working preview of the template, we needs a demo image and a logo. Save the rocket to 1-million-devs/resoc-template/rocket.png and Netlify logo to 1-million-devs/resoc-template/netlify-logo.png.

The previews of the left panel are quite broken at this point. It's time to create our own template.

Edit 1-million-devs/resoc-template/content.html.mustache:

<div class="wrapper">
  <img id="main-image" src="{{ mainImage }}" />
  <img id="logo" src="{{ logo }}" />
</div>

The content is straightforward, expect for the strange {{ mainImage }} and {{ logo }}. This is Mustache, the templating system Resoc uses to inject the final values.

Now for the CSS, fill 1-million-devs/resoc-template/styles.css.mustache with:

.wrapper {
  background-color: {{ backgroundColor }};
  display: flex;
  justify-content: center;
  align-items: center;
  position: relative;
}

#main-image {
  max-height: 84vh;
  max-width: 84vh;
}

#logo {
  position: absolute;
  right: 4vh;
  bottom: 4vh;
  height: 10vh;
}

Nothing fancy. Just a matter of centering the main image and put the logo to the bottom left. Background color is set by a parameter, via {{ backgroundColor }}. We use the vh unit to speak relatively to the view port height. As we plan to generate only 1200x630 images, we could have just used pixels.

Take a look at the preview in your browser:

Cool! You could think this was made with ImageMagick 😆

Use the template

We are now going to build the command line that will create the images. We don't need to start from scratch, though, because the template viewer already provides one below the previews:

Let's shamelessly steal Zach's bash script, replace the two ImageMagick invocations with Resoc's, and name this new script create-og-images.sh:

#!/bin/sh

echo "Uses Resoc"

images="input/*.png"
watermark="resoc-template/netlify-logo.png"
outputDir="output/"
bgColor="#00dc9e"

mkdir -p $outputDir

for i in $images
do
  create-img resoc-template/resoc.manifest.json \
    -o "${outputDir}${i##*/}" \
    --params \
      mainImage="$i" \
      logo="$watermark" \
      backgroundColor="$bgColor" \
    -w 1200 -h 630
done

We need to drop a few samples images in a new input directory.

create-img could be called with npx, but this is way too slow. Install it once for all and go create!

npm install -g create-img
./create-og-images.sh

A few seconds later, the script turned this:

To this:

Conclusion

ImageMagick is an amazing tool. It can perform effects which are beyond HTML and CSS capabilities. Regarding composition, the balance is reversed. Web technologies are more suitable and better known.

Yet, HTML is somehow not available from the command line. Puppeteer has been here for a while, but it is too raw to be used in this context.

I'm creating the Resoc image template dev kit to fill this gap. HTML and CSS are incredibly powerful and we know them so well. Just like JS entered the desktop world via Electron, HTML should join the command line universe.

And there are plenty of other usages for image templates, like static social image generation for NextJS.

DEV Community: Philippe Bernard

How to setup the favicon of a React app

All you need is a React-dedicated favicon generator

Step by step

Conclusion

How to properly add a favicon in Next.js

No time to waste: use RealFaviconGenerator

Next.js conventions - Why are they gone?

Conclusion

Create a CLI script in your NextJS project

Write automated tutorials to stand out from the crowd

A few options, no ideal solution

Big pond

Little pond

Pond in the making

Be different... but how?

Automated tutorials with nstal

A what?!

Classic at first

Magic enabled

How nstal can boost our content

Short term effect: Attention

Long term effect: SEO

Conclusion

Never install anything manually again

How to install Tailwind with NextJS

Same, just faster

Anatomy of an nstaller

Conclusion

Tech blogging: a new way to write tutorials

Two decades of innovation in three bullets

What a tutorial is and what to do about it

Introducing nstal

Just a regular tutorial...

... until you run npx nstal

Benefits

As a reader

As an author

What's next

Automated Twitter banner to show your #100DaysOfCode progress

Prepare the repository

Your Twitter banner template

Generate and update the banner

Parsing the log file

Generating the banner

Replace the existing banner on Twitter

Secure credentials management with dotenv

Twitter App

Update the banner — at last

Twitter banner automation with GitHub Actions

Conclusion

React dev? Why and how you should use Storybook

What is Storybook and why you need it

Direct access

All states at once

Sandbox for debugging

Document as you try your component

Getting started with Storybook

Conclusion

How do DEV cover images work anyway?

Automated social images on Netlify - with Next.js and Resoc

Create the Next.js app

Create the image template

Generate social images

Deploy to Netlify

Conclusion

Automated social images: play it like GitHub

Create the template

Just like GitHub, step by step

Easy comparison

Parameters

(Web)Design

From template to image

Command line

JavaScript

Conclusion

Replace ImageMagick with HTML & CSS

Why not ImageMagick?

Not just a CLI tool: a new language

Inconvenient trial and error

... until you run `npx nstal`