DEV Community: Maxence Poutord

Apps, Tools, and Gear I Use (2021 edition)

Maxence Poutord — Thu, 11 Nov 2021 12:46:48 +0000

This page is somewhat inspired by Wes Bos' Uses page. Keep in mind that
I'm mostly doing Frontend development and I'm also a nomadic worker. In other words, I'm 100% remote and I travel. A lot.

Hardware

MacBook Pro M1 (13-inch)
No extra screen. I've found myself more focus with only one screen
Roost Laptop Stand
Keychron K3 Mechanical keyboard and a Magic keyboard 2 (when I travel)
Magic Trackpad 2 and a G403 HERO Mouse
Notepad where I write my daily MIT
OnePlus Nord (and an old Huawei as a backup)
Sony MDR 1000X. A noise-cancelling headphone with 2 modes: wired or wireless (bluetooth). I also have some Airpods.
Travel&daily bag is a Minaal Carry-on 2.0 (with packing cubes). I love it!

I travel too much to have a proper desk! ;)

IDE

VS Code is my favorite text editor so far.
The theme I use is Material Theme which I customized.
Full list of plugins that I Can't Live Without.

All of my config files (VS Code settings, bash aliases, git config...) are accessible on [my dotfiles GitHub repository (https://github.com/maxpou/dotfiles).

Browser

My main browser is Brave. I also use the following extensions:

uBlock Origin and Privacy Badger to preserve my privacy on the internets
Grammarly
React and Vue.js devtool extensions
Accessibility Insights and axe for Accessibility audits
LastPass for password management
Pocket (Save to Pocket)

Terminal & Command Line Apps

I mostly use my terminal in VSCode. Otherwise, I use iTerm. My terminal theme is
powerlevel10k.

This is the list of plugins/apps I use:

Zsh with Oh My Zsh. Oh My Zsh is a framework for managing zsh configuration.
Lighthouse (CLI) - Auditing, performance metrics, and best practices for Progressive Web Apps.
Hub - a wrapper for Git command (Git+Hub=GitHub).
gtop - an alternative to activity monitor.
Tree - to generate a tree (like the Tree Windows command).
Bat - the cat command on steroids.
n - a super handy tool for node version management.

I also use Vim from time to time.

Desktop Apps

I have a very minimalistic approach when it comes to my dock. If I don't use an app -at least- once
a day, I remove it from the dock.

I also use these applications:

Giphy Capture is my go-to screen recording app when I need to share something with my colleagues. I found it simple to use.
CrossOver - to run Windows App on Mac (it's a paid product).

Note: I now use Slack in my browser (so Grammarly can proofread my messages)

Blogging

My website (maxpou.fr) is made with Gatsby.js. I use these services:

Grammarly - Helps me to remove typos / proofread my posts
Google Docs - Helps me to remove typos / proofread my posts
Hemingway - "Hemingway App makes your writing bold and clear"
Squoosh - Image compression
Remove.bg - Remove background on png
Keynote (Apple) - To draw schemas
Plausible - For ethical analytics
GitHub - Where I host my code and run CI/CD pipelines

Gaming

I play mostly Age Of Empire 2 DE on my MacBook (thanks CrossOver)
For other games, I rely on Cloud Gaming platforms such as GeForce Now, Stadia and XCloud
Xbox Elite Controller Series 2 is my controller. A bit pricey, but very comfortable.

Lessons Learned by Maintaining a Large Vue.js Codebase

Maxence Poutord — Thu, 15 Apr 2021 00:00:00 +0000

I've been maintaining a massive Vue.js codebase for the last 3 years. Here are 9 lessons I've
learned along the way. Not really mistakes I've made but most likely things I'd do differently
today.

TL;DR:

No standards, no consistency

Close the door on bikeshedding

Respect your elders

"F*** the future. Program for today."

Dependencies: we should have been stricter

Don't use TODOs

Keep your audits

Mimic your users

Don't create your core components from scratch!

No standards, no consistency

I don't think it's possible to have consistency without any communication. If your app is
organised in 3 different feature teams you don't want to have 3 different ways of doing one thing.
Agree on standards then communicate. Communication is the key.

Don't be afraid to repeat yourself: "pedagogy is the art of repeating yourself".

Close the door on bikeshedding

It starts by linting your code. No one likes comments like "you forgot a semicolon" on pull
requests. Find a set of rules and follow it. Blindly. If you start to discuss it, you open a door
for bikeshedding.

I also recommend you to write a "Pull request: do and don't" so everybody knows what is and what's
not expected.

Respect your elders

Working with legacy can be frustrating. But it's not a reason to finger-point your elders. Try to
find the root cause (i.e. code was written by Backend, there was no communication at that time...).
Migrating towards greener pastures is a slow process. If there's no plan to get rid of the debt,
it's time to make one.

"F*** the future. Program for today."

We've made a lot of big technical decisions based on FUTURE. Guess what? Years after this future
never happened. I don't have a crystal ball so I can't tell what the future will look like. If it's
the same for you, don't make big decisions based on dreams and hopes.

Program for today!

Dependencies: we should have been stricter

Me opening the package.json

Every time I open the package.json file, I keep thinking the same thing: "we should have been
stricter". We have a list of 95 dependencies and 90 dev-dependencies.

Why?

I think the fear of being a gate blocker played a big part. A second factor was probably letting
the pull request merge without approval from a frontend developer. Having many dependencies increase
the risk of having a malicious package. Also, if we want to change the Vue.js version, we have to
ensure that each library support it.

`// TODO: refactor`

TODOs are the graveyard of important but not urgent tasks. The "I will fix it later" strategy
doesn't work. If you're not very proud of the code you wrote, it's fine. It happens to the best of
us ;) But please don't pollute the code with a TODO.

Keep your audits

We have made a lot of progress in terms of performances, accessibility, and code quality. In 3
years, I've made tons of audits with tools like Google Lighthouse or Axe. But I never kept a single
one. It's such a pity because if today someone asks me what the progress we've made over the last 6
months, I can't give any numbers.

By the way, it can also provide some metrics for your CV ;)

Mimic your users

If you work on your app locally, with a 1500€ laptop and a fiber-optic internet connection, you will
never experience a performance issue.

I can say the same thing if you're using a large screen. 2.5y ago, I went fully remote and I dropped
my fancy 26" curved screen. I realized that a few pages or our app were not readable on a 13".

Don't create your core components from scratch!

We started building our component system ~2.5y ago. A lot of components we created ended up being
surprisingly complex. When we couldn't refactor them, we created a new one (and deprecated the
other).

Today, we have ~30 deprecated components and some of them are used a hundred times.

Looking backwards, we wasted so much time creating the components (from scratch), testing, making
them accessible (a11y) and writing the documentation. If we started with an existing one, we could
have spent more time focusing on the business or the architectural part.

No one cares if the button component you're using doesn't have "the perfect border-radius"!

Thank you for taking the time to read this post. I hope you found it useful! If you liked it, please give it a ❤️ or a 🦄! Also, feel free to comment or ask questions in the section below or on Twitter @_maxpou :)

Originally published on maxpou.fr.

Bash tips for developers

Maxence Poutord — Wed, 17 Mar 2021 00:00:00 +0000

Like many developers, I use the terminal on a daily basis.

I actually use 2 different terminals: the one embedded in VScode and iTerm2 (I'm on macOS). Although this post contains the word bash, I don't use it directly. I use zsh with ohmyzsh. If you never heard about it before, it supercharges bash and adds more interactivity. It also gives me interesting feedbacks like the branch and working directory I am currently in.

By the way, if you like the theme I'm using, feel free to steal my dotfiles. Also, I won't be covering the Git part as I already did in this blog post.

Cheatsheet

How many ".js" files does this folder contains?

find . -name "*.js" | wc -l

# You can also exclude a folder (i.e. node_modules)
find . -name "*.js" -not -path " **/node_modules/**" | wc -l

How many lines of code in this folder?

find . -name '*.vue' | xargs wc -l

# You can also exclude a folder (i.e. node_modules)
find . -name '*.vue' -not -path " **/node_modules/**" | xargs wc -l

Find all occurrences

Example: list where "console.log" is used in the codebase.

grep -Ril "console.log" .

# You can also exclude folders (i.e. .cache and node_modules)
grep -Ril "console.log" . --exclude-dir={\*cache,node_modules\*}

How big is my folder?

Example: list where "console.log" is used in the codebase.

du -sh .

# same but excluding git folder
du -sh -I .git .

What about Vim?

I mostly use Vim for Git commits. It can also be handy when your IDE struggle to open 10 0000 lines long files. To pimp my vim™, I installed something called SpaceVim. It adds fancy things like a file explorer and the syntax color.

Aliases

RAM consumption

alias ram='ps aux | awk '"'"'{print $6/1024 " MB\t\t" $11}'"'"' | sort -rn | head -25'

# Usage
$ ram
507.039 MB /usr/local/bin/node
461.391 MB /Applications/Brave
358.879 MB /Applications/Visual
...

🏴‍☠️ Change your mac address

This one is not really tech-related. I mostly use this one in airports/coffee shops to renew mac address (and get illimited access).

function airport() {
  local mac=$(openssl rand -hex 6 | sed 's/\(..\)/\1:/g; s/.$//')
  sudo ifconfig en0 ether $mac
  sudo ifconfig en0 down
  sudo ifconfig en0 up
  echo "Your new physical address is $mac"
}

🙃 The Russian Roulette

alias russian-roulette='
  [$(( $RANDOM % 6 )) == 0] && rm -rf / || echo "You live"'

If you like to live on the edge... but please, be smart! And don't run commands you don't know the effects of!

Bonus #1: Tree

I use tree to display directories as trees. It very cool to write documentation.

$ tree content/pages

├── components
│ ├── button.js
│ └── checkbox.jpg
├── pages
│ ├── about.js
│ └── dashboard.js
├── index.js
└── README.md

Bonus #2: Gtop

Gtop is a system monitoring dashboard. Typing Gtop on my keyboard is usually quicker than opening the activity monitor (for some unknown reasons I always struggle to find it).

And you, what's your favourite bash tip?

Originally published on maxpou.fr.

Monorepo: is it worth jumping the bandwagon?

Maxence Poutord — Fri, 11 Dec 2020 00:00:00 +0000

The trend today is to split things and make them thinner. We witnessed the emergence of microservices, micro-frontends...

Against this trend, some companies and projects had decided to put multiple applications/libraries under the same git repository. We call this architectural concept a monorepo (or mono repository).

I've been using and maintaining a monorepo for 2 years now. Here are my thoughts about it.

Context: the monorepo I'm working on contains ~40 npm packages, mostly standalone vue.js apps. All those small apps are parts of a big application. We decided to split our big app into small ones because the main one had become hard to maintain. Also, we are ~15 developers working on this monorepo (not full-time).

Pros

🤝 Teamwork

Favour contribution :

When you already have the code, contributing is easier. You don't need to search for the repo, clone it and install it beforehand.

Better overview of the whole system :

You already have all the source code. So you don't need to find the repo url, clone it. A plain old ctrl + F is enough.

Favour large refactoring :

Let's say you want to change something in one package used everywhere else. You can update all the packages in one commit!

Remove unused code with confidence :

How many times you wanted to remove code but you didn't because you didn't know if code was used somewhere else? With monorepo, you don't need to go through all repo to see if this code is used or not. It's very handy.

Single source of truth :

The project I'm working on used to have a very weird name for the main branch. When we changed this name to another one, some repositories were updated, some were not (oversight). With a monorepo, you only have to find this information once.

👨‍👩‍👧 Dependencies

Less space on your hard drive :

If you're familiar with the JavaScript ecosystem, you're probably aware that the node_module folder can be insanely heavy. When we had ~30 apps/packages, it used to take 12Gb on our hard drive. Yes, 12Gb! We had dependencies like Vue.js installed 30 times. Fortunately, some tools (like yarn) symlink redundant dependencies when workspaces are enabled. Thanks to this functionality, we went from 12Gb to 1.7Gb.

Note: I know npm 7.0 now supports workspaces. However, it's still in the early stage. Important commands are not supported yet.

Cross-package hot-reload :

Some tools automatically symlink local dependencies together. Which means, if package-a is used in package-b, you can work on package-a and see the live result in package-b.

Adding a new package is simple :

For us, all our packages are under a packages folder. Adding a new package is very straightforward: no need to parameter the continuous integration/package manager credentials, set the repository permissions... everything is already there.

Cons

🛠 Git & code hosting platforms (GitLab/GitHub...)

Authorization :

When you set read/write permissions on GitLab/GitHub/etc., it's usually for the whole repo.

💡 Tip: You can also create a CODEOWNERS file to define specific ownership rule.

# .gitlab/CODEOWNERS
packages/app-1 @user1
packages/app-2 @user2

With the example above, if user2 opens a merge request to change app-1, user1 will have to approve it.

Git log may become unreadable :

If merge requests are merged "as is", with no squashing option (with 10-15 commits), the git log will quickly become unreadable, and so unusable.

💡 Tip: You can use conventional commit and put in parenthesis the name of the package. So if you want to retrieve one old commit, it becomes straightforward.

# will list all feature added in package-B
git log --all --grep="feat(package-B):"

# or:
git log --all path/to/package-b

Git log may become unusable :

If you have a lot of commits/living branches/tags, it means you will have a lot of git objects stored. git will probably have trouble getting the history of a specific file.

Forget your long-lived branches :

If the main branch is the only source of truth, you can't have a next branch. If you want to have some features only available for a specific environment, then I recommend you to use feature flags.

Repository may become oversized :

The .git folder on your monorepo root might reach a few Gb.

💡 Tip: Here are 2 different options if you want to save some space

# truncate the history
git clone --depth 1 <repo-url> 

# 1. clone an empty repo with no history 
# 2. pull the desired package
git clone \
  --depth 1 \
  --no-checkout \
  --filter=blob:none \
  <repo-url>
git checkout main -- packages/package-a

_Note: learn more about partial cloning._

🤖 Continuous Integration (CI)

When it's broken, everybody is!

If the main branch is marked red by your continuous integration, everybody is impacted. You cannot put this problem under the carpet. It needs to be addressed directly.

The Continuous Integration dilemma :

If codebases are mutualized, you have more code. And more code means more work for continuous integration (CI) for jobs like testing, linting, building...

When dealing with CI, time and reliability are the heart of the matter. On the one hand, you want it to be as fast as possible but, on the other hand, you want it to be reliable. I mean, when my CI gives me a green light, I'm more confident to merge my work.

It can be tempting to reduce the number of packages analysed to gain some time. But, continuous integration will lose interest because it will not be able to spot a "cross-repository" regression.

	Entire codebase	Selected package	Affected packages
Build/lint/test Speed	🐌 Slow	🚀 Fast	🚗 Medium
Spot cross-packages regression?	✅ Yes	❌ No	✅ Yes
Easy to set up?	😀 Yes	😀 Yes	😟 No

The 3rd option is, in my opinion, the most viable. But, you will have to do it manually. A 4th option could use filters. "important" labelled packages use the 1st strategy and the rest use the 2nd strategy.

💡 Tips:

If your CI pipeline is good enough and you have parallel tasks, don't forget to enable the fail-fast option.
I recommend you to add a specific label to short-circuit the CI. Like if you change a typo in the README, you don't need to run unnecessary commands. (i.e. If the pull request have a "NO_CI" label, the build will not be triggered)

🤝 Teamwork

Hidden changes :

Some repos are sometimes more "sensitive" than others. It's easy to add a small piece of code with a big impact. It can be problematic if it's done by mistake.

Amount of code can be intimidating :

The first time I "git pulled" the source code of Gatsby.js, I pulled the full history of ~90 packages. At first glance, I felt overwhelmed. Because it took me ages to clone the full repository (with all the history). And also, because the amount of code was massive!

If you work with 10% of a codebase, you probably don't care about the 90% remaining.

Conclusion

Overall, I think a monorepo can be a good thing.

In our case, it makes our life easier. All our packages are a part of the same big application and are written in the same language. Because they're a part of the same application, they "communicate between each other". Also, we're a human-sized team working on it.

And as always, feel free to reach out to me on Twitter (@_maxpou) or in the comment below! 😊

Originally published on maxpou.fr.

Tips for your GitHub Portfolio

Maxence Poutord — Fri, 16 Oct 2020 07:53:23 +0000

A few week ago 2 people asked me the same question on Twitter: "how do I make a better portfolio?"
Since, it's not the first time I have this question, I decided to answer in public™️.

Before I start, just want to highlight something. Having a GitHub profile is not and should never be mandatory. It's "a nice to have".

Quality over quantity

It's common to see GitHub profiles like this:

(repositories names were anonymised)

The person picked 6 repositories and pinned them. All the repo have 3 commits, no readme. This developper seems to experiment a lot of things but, nothing really stands out. If a recruiter asks you "what problem did you encounter and how did you solve it", the answer will be limited.

Don't get me wrong, there's nothing bad about experimenting new things! I also have a lot of hello world projects on my GitHub profile. However, those are not pinned on my profile. I only pin what I think it's relevant. I know recruiters don't have time to go through all my projects. That's why I have 5 when I'm writing those lines.

Instead of having 6 small projects, pick one. And polish it!

Learn in public

"I don't put it on GitHub unless it's perfect"

This quote comes from a senior dev I used to work with. I think it's a pity to think like that. In general, people who are afraid of making mistakes end up doing nothing. If you look at popular repositories on GitHub, most of them are far from perfect. And it's fine!

And also, if one day someone checks your project's git log and finds out that you forgot a bracket/semicolon, I don't think he will blame you for that. And if he does, it's good for you. Nobody wants to work with toxic people.

There's alway something to do!

I did a mentoring session once with a girl who wanted to retrain in IT. She showed me the small game she developed. But, she wanted to find a new project because she thought this project was "done".

A project is never done. There's always something to do... Remember the 1st advice: "Quality over quantity"!

Here are a few things you can do...

Add a README.md

The readme is the entry point of your project. The first thing people will see!
I think every code repository should have one. If you don't want people to get interest in your project you can add one and write "nothing to see here".

Your readme should answer those questions:

What is this project about? (1-2 sentences should be enough).
How to install it?
How to use it?
What does it look like? you can add a screenshot or a gif animation.

💡 Tip: You can take some inspiration in the Awesome README repository.

Do marketing

If you're building an app, advertise about it! I've an ex-colleague who's building a minimalist text editor. Every now and then, he publishes links on social media (Twitter, LinkedIn...) about his product and the new features he added. He also added his product on ProductHunt/Reddit. These platforms are great to gather feedback!

💡 Tip: There is also smaller communities in WhatsApp, Telegram or Discord (i.e. Party Corgi).

Add more features

On a green field project, finding more features should not be the hardest thing to find. If you did a bit of marketing on it or if you asked for feedback to your friends/family, you should have a list of ideas to add.

At some point, you might face the situation where you have to rethink the way you wrote your app. It's a good point for you because it means you overcome the "Hello world" stage. Interesting problems usually arrive when your app is growing.

And also...

Manage your todo list with tickets/issues. If you have a few tickets, you can group them into different categories: "bug", "enhancement"... If people spot a bug or have a feature request, they will probably open an "issue" on your repository! Also, one small tip: fix all bugs before starting any new feature!
Write tests! Lot of dev recruiters like to see tests when they review code. The project you're working on can be a good opportunity to write some!
Add continuous integration (CI). Every time you add code a robot will check if tests are passing and if you don't have dead code/oversights/... You can use tools like TravisCI, GitHub Actions...
Automate the deployment. Many tools allow you to deploy your app on the web once you git push to the master branch. You can check Netlify, GitHub/GitLab Pages, Vercel...
Make your app accessible (a11y), so people with disabilities can use your app.
Make it mobile friendly (responsive web design) and if you feel comfortable, why not creating a Progressive Web App (PWA)?
Monetize it? If you think you're solving a problem that other people have and if you, you should think about monetization. This project might pay you your coffee... or more!

Now it's your turn. Show me your kick-ass GitHub Profile!

Feel free to reach out to me on Twitter (@_maxpou) or in the comment below! 😎

Originally published on maxpou.fr.

Vue.js Performance Improvement with Memoization

Maxence Poutord — Tue, 01 Sep 2020 00:00:00 +0000

A few weeks ago, memoization helped me to fix a performance issue in my Vue.js application. The result looks like a "Vue.js computed property with parameters", although it's not possible!

The problem

The problem appeared in this big timeline component.

To make it short:

1 line = 1 week of events for one person;
events may overlap (Bob has one on Monday morning).

To position an event on the grid (left, width, top, height/lineHeight), I have to call a function to compute if this event overlaps with another one. This function was called many times and sometimes with the same parameters.

This component used to work nicely on my local environment™️.

But, with more events/day (≃ more squares) and more users (≃ more rows), it was a different story. The component was taking ~4 to ~6 seconds to show up. I added a console.count() and I realized that my function was called +700 times! 🙈

My first call was to use computed(), a cached property (based on their reactive dependencies).Unfortunately, they're not working with parameters. In other words, you cannot do that:

export default {
  data: () => ({
    events: [/* ... */]
  }),
  computed: {
    // ❌ NOT WORKING!
    eventPosition(event) {
      // ...
    }
  }
}

I had to find something else.

Memoization to the rescue!

(If you're already aware of what memoization is, you can directly jump to the next part)

Memoization is a functional programming concept. The idea is to use the function's internal cache to store parameters. The first time a function is called, we compute the value then we store in a cache the output. If this function is called a 2nd time with the same parameter, it will return the value from the cache

The fibonacci function is a good example of how memoization works because this implementation uses recursion. In this example, a function can be called multiple times with the same argument.

// without memoization
function fibonacci(n) {
  return (n <= 1) ? 1 : fibonacci(n - 1) + fibonacci(n - 2)
}

And with memoization, the same function will be written like this:

// with memoization
function fibonacci(n) {
  // 1
  if (typeof fibonacci.cache === 'undefined') {
    fibonacci.cache = []
  }

  // 2
  if (!fibonacci.cache[n]) {
    fibonacci.cache[n] = (n <= 1) ? 1 : fibonacci(n - 1) + fibonacci(n - 2)
  }

  // 3
  return fibonacci.cache[n]
}

I splitted this function in 3 steps:

the first time the function is executed, we define an empty cache;
if the value we're trying to compute is not in the cache, we compute it and add it to the cache;
we return the cached value.

If you add a console.count(n) in the second if(), you will see that with memoization, fibonacci(12) will compute the value of fibonacci(4) only one time instead of 34!

🧐 How's that possible?

Memoization is possible because, in JavaScript, functions are prototypes of Object.

const myCoolFunction = () => true
typeof myCoolFunction. __proto__ // "function"
typeof myCoolFunction. __proto__. __proto__ // "object"

As you can see, with memoization, we trade the code's readability for performance.

Memoization in Vue.js

Now we have seen how memoization works, let's see how to apply this technique in a Vue.js component.For that, we have to put the function into a Vue's methods. Then, it's pretty much the same as what we saw before.

// MyComponent.vue
export default {
  data: () => ({
    events: [/* ... */]
  }),
  methods: {
    positionEvent(event) {
      if (typeof this.positionEvent.cache === 'undefined') {
        this.positionEvent.cache = []
      }

      if (!this.positionEvent.cache[event.id]) {
        const somethingToCache = heavyFunction(event)
        // 🔼 add your function here
        this.positionEvent.cache[event.id] = somethingToCache
      }

      return this.positionEvent.cache[event.id]
    }
  }
}

💡 Tips :

don't forget to add this before your method's name.
feel free to adapt the cache key with your needs!

Is it worth the trouble?

In this very particular case: yes. My component is using a time-consuming function multiple times with the same parameters.

The component rendering went from ~4s to ~0.3s. It's 10 times quicker!!

However, I don't see memoization as a golden hammer. To be honest, it's the first time I use memoization in years of web development.

And that's it for today!

Thanks for reading this article 🤘. I hope you found it useful! If you liked it, please give it a ❤️ or a 🦄!

You can also follow me on Twitter (@_maxpou) 💙

Originally published on maxpou.fr.

Vue.js Testing Made it Easy (with Testing Library)

Maxence Poutord — Thu, 02 Jul 2020 00:00:00 +0000

Today, I want to talk about testing in the Vue.js ecosystem. Between my previous job and my current one, I've been searching for too long a way to test Vue.js applications. I always ended up with something too verbose or overcomplicated.

1.5 year ago, my colleague John introduced me to a very cool library: Vue Testing Library. In a nutshell, it provides a solution to test Vue.js applications... but from a user point of view. Their motto? This one:

The more your tests resemble the way your software is used, the more confidence they can give you.

－ Kent C. Dodds, author of Testing Library

We were already using the official library: vue-test-utils. It provides good results for unit testing components. But, we were not completely convinced by the integration tests. In addition, I don't think unit testing components bring much value. We decided to give a try.

After a year of using it, a colleague he threw this question on the Frontend chat:

(actually the only 👎 is due to a misunderstanding)

Why do we all like it? Because it provides an easy and straightforward way to test our Vue.js Application.

Ok, enough talking. Let's jump to the code :)

Let's get it started!

For this article, I'll take a small app I created.

👉 A demo is available here: vue-testing-library.netlify.app

👉 Code is here: github.com/maxpou/vue-testing-library-sample

The application features are quite basic:

fetch products from the Star Wars API and print it to the screen;
filter products by name when user type something in the textbox;
add product in the basket;
~~buy products.~~ Sorry. I'm Max, not Elon Musk. I can't sell starships 😁

This application is heavily based on vue-cli (including jest+vue-test-utils). Actually, Vue Testing Library acts as a wrapper for vue-test-utils. You can add the library like this:

npm install --save-dev @testing-library/vue @testing-library/jest-dom

Jest-dom is not mandatory. But I recommend you to install it as it provides some very handy matchers for Jest.

Our first test

The first thing I want to test is the presence of starships on the screen!

// tests/unit/catalog.spec.js
import { render, screen } from '@testing-library/vue'

it('should show products name, detail and price', () => {
  render(App)

  screen.getByText('Executor')
  screen.getByText('Kuat Drive Yards, Fondor Shipyards')
  screen.getByText('$1,143,350,000.00')
})

You can now run npm test.

💥 Boom! It's done!

render(App): this is where we instantiate the component.
screen.getByText('Executor'): we search for the "Executor" occurrence in the mounted component. If this value is not found, an error will be thrown. This value must be unique!

Also, you probably realised that you don't need to do any specific configuration!

Note: the API calls are mocked with Jest.

Interacting with the page (click, keypress...)

Now I want to test a user interaction. The spaceship filtering is a good candidate.
Let's test the following scenario: if the user types "wing", we should only see "X-wing" and "Y-wing".

it('should filter products when user type on the textbox', async () => {
  await render(App)
  await fireEvent.change(screen.getByLabelText('Filter results'), { target: { value: 'wing' } })

  expect(screen.queryByText('Death Star')).not.toBeInTheDocument()
  expect(screen.getByText('X-wing')).toBeInTheDocument()
  expect(screen.getByText('Y-wing')).toBeInTheDocument()
})

fireEvent()

To write text in an input text, we use fireEvent.change(selector, options). If we wanted to "click" on something, we would use instead fireEvent.click(). Keep in mind, fireEvent returns a promise, don't forget the await statement before.

queryByText() vs. getByText()

When you want to test a missing text, queryByText is the prefered way.
Remember, getByText throws an error when the text is not present!

I mentioned before, I use Jest-dom. To extend Jest's expect() function, you need to register it on the config files (like this).

Testing the router (with vue-router)

Usually, Vue.js components are not aware of the router. We have to provide the routes to the render function.

We could define the routes on every test... but I don't like to write the same code multiple times. Instead, I recommend you to overload Testing Library's render() function with our defined routes.

// tests/render.js
import { render as r } from '@testing-library/vue'
import { routes } from '../src/router'

export function render (ui) {
  return r(ui, { routes })
}

If I want to test something with a page transition, my test will look like the previous tests.

import { render } from '../render'

it('basket should be empty', async () => {
  await render(App)
  await fireEvent.click(screen.getByText('Basket'))

  await screen.findByText('Your basket is empty!')
})

You probably noticed the findByText(). I could not use getByText() because new page rendering is asynchronous.
findByXXX is good when you want to find something that is not accessible straight away.

Testing the store (with Vuex)

This part is a little bit trickier than the router part.

To work properly, a Vuex store needs to be registered somewhere.

The painless way I found to test components with a store, was to split it into 2 separate functions. Your tests will use getDefaultStore() and your app will use the Vuex instance (2nd export).

// src/store/index.js
export function getDefaultStore () {
  return {
    getters: { /* ... */ },
    modules: { /* ... */ }
  }
}

export default new Vuex.Store(getDefaultStore())

After that, you can override Testing Library's render() function with your custom stuff.

// tests/render.js
export function render (ui) {
  const store = getDefaultStore()

  // reset/override default store here
  store.modules.basket.state.items = []
  store.modules.catalog.state.starships = []
  store.modules.catalog.state.currentPage = 0
  store.modules.catalog.state.fullyLoaded = false

  return r(ui, { store })
}

You might wonder why I'm cleaning the store with multiple store.modules.xxxx? Well, I want my test to be fully isolated. It's not an easy job since Vuex is based on mutations. Without these lines, you may have problems where test #3 depends on test #2.

Once it's done, you don't need to do anything specific. Vuex test should look like any other test,

it('should add items to basket', async () => {
  await render(App)

  await fireEvent.click(screen.getByLabelText('Add Millennium Falcon'))
  await fireEvent.click(screen.getByLabelText('Add Imperial shuttle'))
  await fireEvent.click(screen.getByLabelText('Add Imperial shuttle'))

  expect(screen.getByRole('navigation')).toHaveTextContent('Basket (3)')
  await fireEvent.click(screen.getByText('Basket (3)'))
})

See! It doesn't look like I'm testing a store 🙂

One render function to rule them all!

Let's sum up. We created a custom wrapper for the vue-router and another one for Vuex. I could post a render function like this:

// test/render.js
export function render (ui) {
  const store = getDefaultStore()
  // store overrides...

  return r(ui, { routes, store })
}

...but, it's a little bit too "hello world" for me. I guess you also use some cool Vue.js related libraries (VueI18n, VeeValidate...)?
Here's good news for you. This is the wrapper I use for ~90% of my tests:

export function render(ui, { store: storeOverrides = {} } = {}) {
  return r(
    ui,
    {
      routes,
      store: { ...getDefaultStore(), ...storeOverrides },
    },
    (vue, store, router) => {
      vue.use(VueI18n);
      vue.use(VeeValidate);
      const i18n = new VueI18n({ locale: 'en', messages: { en: messages }, silentTranslationWarn: true })
      return { i18n, router };
    }
  )
}

The storeOverrides parameter allows you to override a part of the store for a specific test (i.e. testing functionality with a different user).

The quest for the perfect query

In the beginning, finding the perfect query to use can be hazardous. In this blog post, we already saw a few.
If you're lost, don't worry. getByText() and queryByText() cover the most common usages. Once you're comfortable with them, feel free to check these resources.

testing-library.com/docs/guide-which-query: the official documentation;
testing-playground.com: you can copy/paste your HTML and they will tell you which query is the most appropriate.

Also, when you hesitate, think about your users. How do they interact with your app?
For a login feature, do you want them to:

fill their credentials in a textbox with a class="form form-password"?
fill their credentials in a textbox labeled "password"?

You see? 😉

Think users. If you pick the 2nd, you will kill two birds with one stone. You will test the login feature plus your component accessibility!

💡 Tip: eslint-plugin-testing-library is a great addition! It can spot some misused queries.

Debugging

Vue Testing Library doesn't let you access to component's internals. It's voluntary.
The idea behind this decision is to prevent developers from testing implementation detail.

Here's what you can do:

add some console.log() in the lifecycle component (mounted, updated...);
use the debug() function provided by the library.

  it('should test something but it\'s not working', async () => {
    await render(App)

    screen.debug()
    // screen.getByText('broken assertion')
  })

Then, when you npm test, component DOM will be printed in the console (with a nice syntax color).

🙋🏽‍♀️ Help, debug() give me a truncated output!

You can override the debug max size like this.

DEBUG_PRINT_LIMIT=100000 npm test

And that's it for today!

Thank you for reading. Feel free to comment or ask questions in the section below or on Twitter (@_maxpou).

Happy testing 🙂

Originally published on maxpou.fr.

Code Coverage: The Great Illusion

Maxence Poutord — Thu, 07 May 2020 00:00:00 +0000

The company I'm working for recently set a code coverage rule requirement. Although I believe tests improve the software quality and help developers to write code with confidence, I'm strongly against this coverage rules. I believe this metric should never be used as a target. But first, let's understand how code coverage works under the hood.

This article is intended for web application testing. Not for a library (open source or not).

How Code Coverage is generated

Let's take the following code:

function foo (a) {
  if (a) {
  // do something with 'a'.
  } else {
  // do something else.
  }
}

will be rewriten as:

function foo(a) {
  cov_2mofekog2n.f[0]++;
  cov_2mofekog2n.s[0]++;
  if (a) {
    // do something with 'a'.
    cov_2mofekog2n.b[0][0]++;
  } else {
    // do something else.
    cov_2mofekog2n.b[0][1]++;
  }
}

A global counter object cov_2mofekog2n is created for this file. This object's have key that stand for:

f: function;
s: statement. Note: the else belongs to the if statement. That's why we have only one statement here.
b: branch. Note that branch 0 have 2 counter (because if and else are 2 different branches)

As Benjamin Coe mentioned, this way of measuring the coverage changed had now. Code coverage is now computed on Node V8's side. But, the idea of a global counter remains the same.

Now we have seen how this metric is computed, let's see why we shouldn't use it as a target.

Reason #1: Covered code !== tested code

We can take the previous code example and add the following test.

// foo.test.js
import foo from './foo.js'

describe('Foo.js', () => {
  it('should do something', () => {
    foo(true)
    foo(false)
  });
});

Now, if you run npm run test -- --coverage, you will get... 100% code coverage. In other words: You don't need any assertion to cover code.

The example itself might sound ridiculous because dev usually don't write empty functions or tests like that. Ok.

Let's take a more realistic example.

// shop.spec.js
describe('Shop', () => {
  it('should render the component', () => {
    const wrapper = mount(<Shop />, { products })
    expect(wrapper.text()).toMatch(/Our products/)
  });
});

With a test like this, it's super easy to get high coverage. However, this test doesn't test anything related on how the product itself is rendered.

Code coverage doesn't give any indication of what is actually tested.

Reason #2: Dev focus on coverage instead of confidence

If I continue with the shop example. We still have one test that tests almost nothing (but covers a lot!).
When I get the code coverage report, it says that one scenario is not tested: when one product is available.

getPageTitle() {
  return this.products.length === 1
    ? 'Our product'
    : 'Our products'
}

According to you, what is the next step now?

Add a test to cover this untested function? (with a low impact)
or reinforce tests on parts that are already covered but not tested? (with a high impact)

If you are in a company with a xx% code coverage requirement, you will be more inclined to "cover" code to bump the score.

We were supposed to write tests for confidence. Confidence to ship code that works as expected. And we ends up writing tests for metrics. A nonsense!

Also, if you have a xx% code coverage policy, it means you're expecting the same level of test across the whole application. Do you think that a hidden settings page and a main feature deserves the same attention?

Reason #3: High code coverage !== high quality of tests

"When a measure becomes a target, it ceases to be a good measure"

－ Goodhart's law

In one of my previous experiences, I was granted as a tech lead. I thought it could be a good idea to set a 100% code coverage policy. I thought it was something good to enforce the code quality. I was pretty proud to have a 100%cc and keep it over the time. And one day I got disillusioned when I went through the code base.

Some dev didn't write code for confidence but to make the CI build green. As we saw before, if you understand how code coverage works, it's super easy to trump this metric.

Here are a few example of low quality tests:

a dev couldn't test an if statement. So he updated the code to trump the coverage and get the 100%.

  function myFunction(something, unitTest = false) {
    // code

    if (weirdAndHardToTestCondition || unitTest) {
      // code
    }

    return whatever;
  }

implementation detail a.k.a. tests that result with false positives and false negatives. You have a lot of them when you search for react/vue components on GitHub;
reducing code legibility when code cannot be tested. Less lines of code === less uncovered percentage. You can also write more verbose code on the covered part to gain even more percent.

  // given generatePdf() is hard to test...
  const filename = `${user.name}-${user.lastname}.pdf`
  const data = formatData(user.data)
  const PDF = generatePdf(filename, data)

  // now become
  const PDF = generatePdf(`${user.name}-${user.lastname}.pdf`, formatData(user.data))

and the cherry on top: a developper extended the testing framework to test private methods. That spicy one was in PHP (with the reflection method).

Not all code need to be tested

Before giving my talk about Frontend Testing, I asked developers why they don't test. Without any surprises, most of them told me: "we don't have time to test". When I asked my maker friends, I heard the same song.

Writing tests cost time. Therefore money.

Sometimes the amount of time invested on writing tests does not pay off. Because of the time consuming aspect or because devs are flooded by too many tests.

That's more or less what Kent C. Dodds explains in his famous post Write tests. Not too many. Mostly integration.

Wrapping up: should we throw out the baby with the bathwater?

Of course not :)

Sometimes, but not always, Code Coverage can help to highlight untested parts of an application. But it's just a metric. So please, use it as a metric, as a tool to help you to take the right decision. Not the opposite!

Thanks for reading this article 🤘. I hope you found it useful! If you liked it, please give it a ❤️ or a 🦄! Feel free to comment or ask questions in the section below or on Twitter (@_maxpou).

Originally published on maxpou.fr.

10 Tips for Working From Home

Maxence Poutord — Sun, 15 Mar 2020 00:00:00 +0000

Because of the Coronavirus, a lot of people are going to experiment with the “home office”. Working From Home can be great but it can also be terrible if you don’t follow the right habits from the start.

I’m working 100% remotely since October 2018. Here are my tips to avoid the most common pitfalls and make it a success :)

Workspace

1. 🛌 NEVER work from your bed.

I know how comfy and warm a bed can be. This is not a reason to work from it. If you start to establish a mental association between your sleep and your work, the quality of your sleep will decrease. Also, you’ll start to think more and more about work when you are in your bed.

For the reasons mentioned above, also avoid working from your bedroom. Instead, you can use a spare room. If you don’t have one, you can create an "office corner" in the kitchen.

2. 🪑 Find the best workspace

Working from the couch or a long/armchair can be ok for a meeting or a 1,5h working session. It’s not viable for more. Otherwise, you will end up with RSI/back pain/etc. The strict minimum to have a decent working session is a table, a chair and some natural light. I also found myself better with a laptop stand + external keyboard&trackpad. Also, don’t neglect the decoration. Add plants!

If you want some inspiration, here's my setup.

Note: if the virus spread were not a thing, I’d recommend you to find some cafe to work from. Having a group of people to work with once a week is also super cool.

3. 📲 Reduce distractions

When no one is watching you, it might be tempting to waste your time on your phone, social media...

Here are some counterspells:

put your phone in silent mode (or Do Not Disturb mode);
install a blocker and disallow social media from 9 am to 5 pm;
schedule deep work sessions and turn off slack. When I was in Asia (7-8H ahead of my coworkers), I used to do 90% of my day job in the morning. If you wonder how, the answer is simple: nobody was connected. This tool can be good for communication but it’s a productivity annihilator.

Note: your boss might expect you to keep the same level of productivity while working remotely. To be brief: it’s impossible. You’re going to introduce a wholesale change in the way you and your teamwork, your productivity will be impacted. Plus some people also have to manage kids, anxiety...

Work

4. ✋ Know when to stop

Sometimes we have close to zero output of our workday. As a software engineer, I often work all day on a bug and solution results in a one-line fix. You feel a bit guilty but it's ok to do so. Because in an office, people see you working.

It does not have to be different when you're working remotely. You don't have to work more just because you think you should have done more. Have some rest, you will do better tomorrow! 💪

When you work in an office, you see people leaving the office in the evening and you don't really see them when you're remote. If you can unplug, you can set an alarm.

5. 🗣 Overcommunicate and be transparent on your activities

Between what I think, what I want to say, what I believe I say, what I say, what you want to hear, what you believe to hear, what you hear, what you want to understand, what you think you understand, what you understand...They are ten possibilities that we might have some problem communicating. But let's try anyway...

— Bernard Werber

If you work remotely, the chances of having a tunnel effect are increased. When I'm working on big features, I always share screenshot/video capture (super easy with Giphy Capture).

People can blame you if you don't communicate. But if you overcommunicate, no one will.

6. 📽 Turn on your webcam during meetings

Enabling the camera removes a lot of stupid problems like: "is he serious or is he joking?". Also, it makes the conversation more human. What I mean is it can also reduce the feeling of isolation that is present in many remote workers. You may have people by your side, but not everyone have. Maybe your face is the only face your colleague will see today. Think about it.

Just make sure you don't have a bottle of beer next to you. If you're live on the TV, put the kid away ;)

7. ☑️ Have a checklist of things to do

Balancing time is hard. You can write down your MITs (Most Important Things). It's a mix between a daily log and a todo list.

MIT helped me a lot to organise my workday and also tell my manager what I've done over the last week. I've to admit that I haven't used it for a long time.

If you find it hard to manage your priorities, you can use the Eisenhower Matrix. It's my go-to tool when it comes to priorities.

Life

8. 🍛 Get a proper lunch break

What I mean here is: don't eat in front of your work.

Even if you're home, don't hesitate to physically move during your break. Like changing rooms, going on the sofa... the idea is to create distance between you and your work. So you know you're on a break. Not 50% working / 50% resting.

Also, don't hesitate to take a five-minute break to step away from your laptop. You will come back happier and more productive.

9. 🍃 Take care of yourself

This one might sound stupid but some people slowly forget some basics things in life like having a shower, eating healthy, doing exercise...

We're not (yet) in a post-apocalyptic world. Life can't be resumed to sleep-work-eat-work-netflix-sleep. Repeat.

10. ⏰ Establish a routine

Home office removes time to commute. You don’t owe this time to your boss. No, it’s yours! Take leverage of this gain for yourself. Establishing a routine is a good way to slowly start and end your day. There are thousands of things to do! Cooking, reading, walking the dog, yoga, meditation...

Here's mine:

07:15am wake up (after 8h sleep)
07:35am catch-up on Twitter + Mail/Telegram/WhatsApp groups
07:45am do some push-up + get ready
08:00am prepare breakfast (avo toast/fruit salads 👨‍🍳) + drink my coffee + watch video/read a blog post
08:30am start working

When I need more sleep, I start later. I never start working without having some time for me first.

Create your routing with your needs. It doesn't have to be outstanding. Make it simple and be consistent.

And you, what's your best advice for working from home?

Originally published on maxpou.fr.

10 Tips For Writing Better Tests

Maxence Poutord — Tue, 04 Feb 2020 00:00:00 +0000

#1 - Think documentation

Your company wiki can be outdated. Tests can't.

Everybody wants good and well-written documentation. Unfortunately, it's hard to keep it up to date.I believe tests can replace, somehow, a part of the documentation. Tests provide a good description of how your application should behave.

Let me show you an example I could write:

// Shop.spec.js
it('should show list of product', () => { /* ... */ })
it('should hide non-available products', () => { /* ... */ })
it('should display a discount label when available', () => { /* ... */ })
it('should paginate when > 10 products', () => { /* ... */ })

Just by reading the name of the name of the file and the 4 descriptions, I already know what is this functionality and some business rules.

Also, if the "should hide non-available products" test breaks, I know exactly where to start my investigations.

#2 - Isolate your tests

To better organise your test file, you can group related assertions under the same test (= the same it()/test()). Try to keep your reasonably small. Smaller tests are easier to understand and easier to maintain.

Sometimes, we need to test a full process. Like a payment flow where you have a few different steps (i.e. payment info > user address > confirmation).

If you hesitate between creating one big test vs one test per step, where "step 2" depends on "step 1", go for the first option. It's OK to have some longer tests.

Sharing a state between tests is a bad idea. They're hard to debug and soon or later, you will face weird issues caused by side effects. Always keep your tests isolated. Tests should not depend on each other.

#3 - Keep it flat

I tend not to write any condition (if/else/...) in my tests. If your test has an if condition, maybe you are testing 2 different things. Which means, your test may have too many responsibilities.

Remember the S of SOLID (S = Single-responsibility Principle). If it makes the coffee, toast your bread and fetch the forecast... there might be something wrong.

#4 - Only mock what you can't control

Every time we mock, we diverge from the real world scenario.

For this reason, you should avoid them as much as possible. But, sometimes we have no other option but to use it. Here are the only exceptions:

for external API calls (HTTP GET/POST/...);
for browsers API (local/session storage, navigator...);
... and time-based stuff (date, random methods...).

Talking about time, if you're testing a timer, don't block the pipeline for the x seconds required by the timer. Mock the clock!

#5 - Avoid assertion in loops (forEach/...)

A common error is to test a list in a loop.

Example: I want to test a page that loads 30 items.

import fakeDataProducts from '../fixtures'

it('should shows list of product', async () => {
  const wrapper = await render(ProductList)
  fakeDataProducts.products.forEach(product => {
    expect(wrapper.find(product.name))
      .toBeInTheDocument()
  })
})

What's wrong here?

Too many assertions : multiple assertions can potentially slow down the execution of the test suite.
Non-valuable tests : asserting the presence of one item can be a good idea. But, testing the presence of each item doesn't seem to add much value.

Exception : When each element of the array represents a different use case.

#6 - Test your app in the same way as a user will use it

The more your tests resemble the way your software is used, the more confidence they can give you.

— Kent C. Dodds

Let say you want to login on your favourite social network. You fill your username and your password. And after that: do you search in the DOM for the button with id="login-form-btn"? or do you click on the button called "Log In"? Why do you test differently?

If the keyword "Log In" is already present on the page, you can query your item with accessibility attribute (i.e. aria-label, ...). In this way, you will enforce your component accessibility.

#7 - Favour integration tests

You probably read Martin Fowler's blog talking about the Testing Pyramid. In a nutshell, this blog said: write a lot of unit tests (fast and cheap), some integration tests and a few end-to-end tests (slow and expensive).

But, this post was written in 2012. 8 years ago! I believe we play a different game today with different rules too.

Unit testing a Redux/Vuex store gives me zero confidence. I've done it in the past. Many times... but, the number of bugs haven't changed. Why? Because bugs and regressions are generally not in small pieces of code.We found them at a higher level.

(Unit vs. Integration tests)

Integration tests are more expensive than unit tests. But, it's worth the trouble.

#8 - Avoid implementation detail

Let's say you want to test a "like button". You might be tempted to do something like this:

const wrapper = mount(<LikeButton />)
wrapper.find('Like').simulate('click')
expect(wrapper.state().liked).toBe(true)

What's wrong here?

False positives: (aka false alarm) It looks like an error but it's not. Let say, you want to refactor the component. By refactoring, I mean changing the implementation, not in the behaviour or the contract (props, events...). Otherwise, it's not a refactor. If you rename liked to isLiked, the test will fail. And it should not. We write tests to fail when something goes wrong. Nobody cares about a variable name! But, it's a different story when it comes to behaviour. Only test what matters!
False negatives: (test pass but it shouldn't) Instead of verifying the output, we check the internals. We can't be sure the output still works as expected.This scenario can happen because we did not test the app in the same way as your final user will. In other words, our users and other devs who are going to use this component don't really care about the magic inside the component.

To avoid implementation detail, treat your component as a black box: only test the inputs and the outputs.

The same test, without implementation detail could be:

const spy = jest.fn()
const wrapper = mount(<LikeButton onClick={spy}/>)
wrapper.find('Like').simulate('click')

expect(wrapper.prop('aria-label').toEqual('liked')
expect(spy.mock.calls[0][0]).toBe(true)

#9 - Always green

I remember when I joined a company a few years ago. On Day One, I couldn't start the application. After investigations, it turns out someone had forgotten a ; in a SQL file and pushed it to master. The application was broken because of a god damn semicolon. With basic tooling, those kinds of problems should never happen.

If you ask a dev to run the run manually the test before opening a pull request, it's not gonna work. Humans are fallible. Plus, this is a dumb job. Better delegate this job to a robot, they are cheap and never lie. Automated jobs will ensure your tests are always green.

Because I don't even trust myself, all of my side projects have CI enabled by default. The only way for me to merge my own code is to open a pull request and get a green build.

#10 - Write tests for confidence, not for metrics

"When a measure becomes a target, it ceases to be a good measure"

－ Goodhart's law

I see a lot of people writing Coverage-Driven Test™️. Because their manager asked to, or because they want to show off with a "100% code coverage" on the GitHub repository.

In my opinion, this is a really bad idea. And for a few reasons:

Code covered does not necessarily mean code tested;
High code coverage gives the illusion of quality. But, you can have a high percentage with irrelevant tests that does nothing except bumping the score (cf. implementation detail);
Dev doesn't write tests for being confident but to satisfy a metric.

This last point is very important. By taking the problem on the wrong side, we forgot why we write tests.We should all write tests for confidence. Confidence for shipping code that works as described and also confidence that the behaviour will remain unchanged 6 months later when you or a colleague will work on this part of the application.

Not all code needs tests. Expecting the same amount of test in your App hidden settings and in the payment page is absolute nonsense. Writing tests is an investment. If tests don't provide any visible ROI (Return On Investment), skip them. Except, if you're working on a library (open source or not).

And you, what's your golden rule for testing?

Originally published on maxpou.fr.

How to generate social share images with Gatsby

Maxence Poutord — Thu, 23 Jan 2020 00:00:00 +0000

TL;DR: Generating share images can be done in 3 steps:

create a preview page;

screenshot it (with pupetter);

add the image in the page's metatags.

When you spend hours writing a blog post, you want it to stand out, not to be lost in a feed. That's why having a social share image attached to your blog post is crucial. People are drawn to visual content. Our brains respond very quick to images in comparison to plain text.

The idea behind this post is to show you how to generate preview images like this for your Gatsby.js website.

Social share images are used by social media (Twitter/Facebook/LinkedIn...) and also some conversational applications (Slack/Telegram/WhatsApp/...).

Before we start, keep in mind that Gatsby is static website generator. We can't generate image "on the fly" as we do with other languages (i.e. PHP...).

Step 1: create the preview page

The preview page is meant to be screenshotted and only screenshotted!

Your blog post page should be generated with something like createPage(). So, we are going to duplicate this statement to create the preview page.

// gatsby-node.js
posts.forEach((post, index, posts) => {
  // create the blog post page
  createPage({
    path: post.node.frontmatter.slug,
    component: require.resolve('./src/templates/blog-post.js'),
    context: {
      slug: post.node.frontmatter.slug
    },
  })

  // create the blogpost page preview
  createPage({
    path: `${post.node.frontmatter.slug}/image_tw`,
    component: require.resolve('./src/templates/blog-post-share-image.js'),
    context: {
      slug: post.node.frontmatter.slug,
    },
  })
})

💡 How to disable this page in production?

I guess you don't want to see this page is production right?If you wrap the createPage in the following "if condition". So, the page will be only accessible with gatsby develop command.

if (process.env.gatsby_executing_command.includes('develop')) {
  createPage({
    // ... 
  })
}

Then, we need to create the blog-post-share-image.js. In the GraphQL query, fetch fields you want to use (post title, time to read...). And render everything in a rectangle (i.e. 440 x 220 pixels).

If you want, here's the template I use for maxpou.fr. Now, use your HTML/CSS skill to make the nicest preview 💪.

After that, the preview should be accessible at http://localhost:8000/your-article-slug/image_share.

Step 2: screenshot the preview

To take a screenshot, I use pupetter. Here's a part of the script I am using to take a screenshot:

// scripts/generatePostPreviewImages.js
// full script available here:
// https://github.com/maxpou/gatsby-starter-morning-dew/blob/master/scripts/generatePostPreviewImages.js

// #!/usr/bin/env node
const puppeteer = require('puppeteer')

const takeScreenshot = async (url, destination) => {
  const browser = await puppeteer.launch()
  const page = await browser.newPage()
  await page.goto(url)
  await page.screenshot({
    path: destination,
    clip: {
      x: 0, 
      y: 0,
      width: 440,
      height: 220,
    },
  })

  await browser.close()
}

const main = async () => {
  const files = getArticleFiles()

  for (let i = 0; i < files.length; i++) {
    const file = files[i]
    const destinationFile = join(file.directory, `${file.slug}-share.png`)

    // (existsSync check if the file already exist)
    if (!existsSync(destinationFile)) {
      await takeScreenshot(
        `${baseUrl}${file.slug}/image_share`,
        destinationFile
      )
      console.log(`Created ${destinationFile}`)
    }
  }
}

main()

...and in the package.json, make the script available as a command.

{
  "scripts": {
    /* ... */
    "generatePostPreviewImages": "./scripts/generatePostPreviewImages.js"
  },
}

We are now ready to create the picture! To generate the preview image, open 2 terminals:

Terminal 1: npm run gatsby develop;
Terminal 2: npm run generatePostPreviewImages.

You should have generated some preview images (1 per blog post). The script above put the image directly in the blog post folder.

Step 3: integrate the picture in the DOM

The social image is now generated. Before you add it in the HTML's body, don't forget to link the image with the blog post.

# ./my-blog-post.md
--------
title: "How to generate social share images with Gatsby"
slug: generate-social-image-share-with-gatsby
cover: ./cover.png
# links preview image
imageShare: ./git-under-the-hood-share.png
--------

Your blog post content

When you render your blog post, you can add the image generated in an SEO component.

class BlogPostTemplate extends React.Component {
  render() {
    const post = this.props.data.post

    return (
      <Layout>
        <SEO
          imageShare={post.frontmatter.imageShare.publicURL}
          /* other: title, description, url... */
        />

        <Wrapper>
          <Article post={post} />
        </Wrapper>

      </Layout>
    )
  }
}

The SEO component purpose is to manage all the meta-information located in the page's <head>.If you don't have this component, you can get some inspiration from the Gatsby-starter-blog. Also, feel free to copy/paste the code I wrote for my website.

At the end, you should have something similar in your HTML's body:

<!-- Open Graph meta tags -->
<meta property="og:url" content="https://www.maxpou.fr/super-cool-blog">
<meta property="og:type" content="article">
<meta property="og:title" content="My super-cool blog post | maxpou.fr">
<meta property="og:description" content="This is my very cool blog post description!">
<meta property="og:image" content="https://www.maxpou.fr/path/to/image/generated.png">

<!-- Twitter Card Tags -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:creator" content="_maxpou">
<meta name="twitter:title" content="My super-cool blog post | gatsby-starter-morning-dew">
<meta name="twitter:description" content="This is my very cool blog post description!">
<meta name="twitter:image" content="https://www.maxpou.fr/path/to/image/generated.png">

and... tadaa it should works 🎉

Conclusion

If you want to check your metatags, you can use Twitter cards Validator. To test the Open Graph tags, I usually send a message to myself on Slack.

That's it for today! I hope this post will help you to generate your social images share. I copied all examples from my Gatsby starter/theme: gatsby-starter-morning-dew.

Thank you for taking the time to read this post. I hope you found it useful! If you liked it, please give it a ❤️ or a 🦄! Feel free to comment or ask questions in the section below or on Twitter (@_maxpou) :)

Originally published on maxpou.fr.

Git: Cheat Sheet (advanced)

Maxence Poutord — Mon, 02 Dec 2019 10:00:02 +0000

If you find git confusing, I created this little cheat sheet! Please, note that I voluntary skipped the basic commands like git commit, git pull/push... This cheat sheet is intended for an "advanced" usage of git.

🧭 Navigation - Go to the previous branch

git checkout -

🔍 Get the history

# Log in one line
git log --oneline

# Retrieve all commits by message
# Here all commit that contain 'homepage'
git log --all --grep='homepage'

# Retrieve all commit by author
git log --author="Maxence"

🙈Ooops #1: I reseted an unwanted commit. How to rollback?

# Get everything you did
git reflog

# then reset to the desired commit (i.e. HEAD@{4})
git reset HEAD@{4}
# ...or...
git reset --hard <commit-sha1>

For more detail about this command, I wrote this post.

What's happens when you `git commit`

Maxence Poutord ・ Oct 16 '19

#git #tutorial #beginners

🤦‍♀️Ooops #2: I mixed-up with my local repo. How to clean it?

git fetch origin
git checkout master
git reset --hard origin/master
# You're now up-to-date with master!

🕵🏻‍♂️Difference between my branch and `master`

git diff master..my-branch

✔ Custom commits

# Edit last commit
git commit --amend -m "A better message"

# Add something to the last commit without writing message again
git add . && git commit --amend --no-edit

# empty commit - can be useful to re-trigger CI build...
git commit --allow-empty -m "chore: re-trigger build"

If you don't know what to put in your commit messages, I wrote a post about conventional commits.

♻️ Squash commits

Let say I want to rebase the last 3 commits:

git rebase -i HEAD~3
Leave the first "pick" and replace the rest by "squash" (or "s")
Tidy up the commit message and save (:wq in vi).

🎯Fixup

Let say I want to add something in the commit fed14a4c

git add .

git commit --fixup HEAD~1
# or replace HEAD~1 by the commit hash (fed14a4c)

git rebase -i HEAD~3 --autosquash
# save&quit the file (:wq in VI)

🕹Execute command on each commit when rebasing

For massives features, you might end up with a branch with a few commits inside. And then tests are failing and you want to identify the "guilty commit". You can use rebase --exec to execute a command on each commit of the history.

# Will run "npm test" command on the last 3 commit ❤️
git rebase HEAD~3 --exec "npm run test"

🦋Stash

Because it's not all about git stash and git stash pop ;)

# save all tracked files
git stash save "your message"

# list your stashes
git stash list

# retrieve stash and delete
git stash apply stash@{1}
git stash drop stash@{1}
# ... or in 1 command
git stash pop stash@{1}

🗑 Clean

# remove branches that no longer exist on remote
git fetch -p

# remove all branch that contains "greenkeeper"
git fetch -p && git branch --remote | fgrep greenkeeper | sed 's/^.\{9\}//' | xargs git push origin --delete

🐙 GitHub = `Git` + `Hub`

I use Hub as a wrapper for git. To enable it you've to set hub as an alias for git (alias git='hub').

# Open browser and go to the repository url (GitHub only)
git browse

Other commands are available here.

🦄 Bonus: my favourite git aliases

alias g='git'
alias glog='git log --oneline --decorate --graph'
alias gst='git status'
alias gp='git push'
alias ga='git add'
alias gc='git commit -v'

# 🤘
alias yolo='git push --force'

# useful for daily stand-up
git-standup() {
    AUTHOR=${AUTHOR:="`git config user.name`"}

    since=yesterday
    if [[ $(date +%u) == 1 ]] ; then
        since="2 days ago"
    fi

    git log --all --since "$since" --oneline --author="$AUTHOR"
}

And you, what's your favourite git command?

Originally published on maxpou.fr.