DEV Community: Benjamin Petetot

Build your own Codelab with Google Codelab

Benjamin Petetot — Thu, 09 Jan 2020 16:54:19 +0000

Codelabs and workshops are a great way to learn new technologies or languages, but it's time-consuming to write and structure. They are very useful as documentation so if you don't want to read this post further, you can follow the codelab 😉.

Google has a great platform providing guided tutorials about their products or technologies.

Google Developer platform with over 500 codelabs

A codelab using google tool suite

Thanks to their experience, they provide a suite of tools for authoring and serving codelabs.

Write a codelab

There are two ways to write a codelab. Either directly in a Google Doc, where you can easily collaborate with multiple contributors, but you can't easily manage the source control. Either you can use a simple markdown file to write a complete codelab and push it in any git repository.

So first, you need to create a simple Markdown file, it will contain all the codelab content.

id: id-of-the-codelab
summary: The codelab description
authors: Your name

# Here the main title of the codelab
<!-- ------------------------ -->
## Step 1 heading here 
Duration: 1

### Here a sub heading
- How to foo.
- How to bar.

<!-- ------------------------ -->
## Step 2 heading here 
Duration: 5

Lot of features are available, you can:
- add code snippets
- use hyperlinks
- embed images

A simple example of the Markdown syntax

On the top of the file, some metadata describes the codelab (id, summary, category, authors, etc.). Markdown heading levels define the codelab structure and the different steps. You can find a complete Codelab Formatting Guide explaining the codelab structure with Markdown.

Lot of features are available, you can use all the power of Markdown by adding code snippets, hyperlinks or images.

Build a codelab

Google provides a CLI named claat tool (Codelabs as a Thing). It generates HTML files from a Markdown file or a Google doc. But it needs some prerequisites: Go and node have to be installed on your computer. To avoid this annoying install process, I made a light docker image to use claat.

First pull the image:

docker pull bpetetot/claat

Then execute claat on your markdown file:

docker container run -it -v $(pwd):/app bpetetot/claat export my-codelab.md

Now you have a full HTML static codelab, you can deploy it with your favorite hosting provider.

When you are working on the codelab, you can serve it on localhost:

docker container run -it -p 9090:9090 -v $(pwd):/app bpetetot/claat serve -addr 0.0.0.0:9090 my-codelab.md

Now you can create amazing codelabs and documentation. 🎉

Here a simple example

The markdown file: https://github.com/bpetetot/claat-image/blob/master/howto.md
The codelab online: https://bpetetot.github.io/claat-image

Some useful resources:

Google codelabs tools on GitHub: https://github.com/googlecodelabs/tools
Formatting guide: https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md
Claat image on Docker Hub: https://hub.docker.com/r/bpetetot/claat
Claat image on GitHub: https://github.com/bpetetot/claat-image

Useful JS libs in my web developments

Benjamin Petetot — Thu, 02 Jan 2020 18:26:23 +0000

Useful JS libraries I'm using in my web projects, some are famous, some should be. None are framework oriented, you can use it with React, Angular, Vue, JQuery etc.

lodash

Always useful, lodash is a set of utilities to handle strings, iterables, collections, functions. Don't reinvent the wheel, you will find what you need in lodash. 2 things to keep in mind when you use it in a webapp.

Don't forget to import only the module you need. You don't want to import all lodash utilities in your final bundle.
lodash/fp module will you give the ability to use it in a functional programming style.

// import only the debounce function from lodash/fp
import debounce from 'lodash/fp/debounce'

const debounced = debounce(250)(search) // debounce the search function

date-fns

Like lodash, date-fns has a bunch of functions but dedicated to handle dates. This is a great alternative to moment.js It uses the native Javascript Date object and you can import only the modules you need. Formatting, parsing, operations... most of date use cases can be done with date-fns.

import formatRelative from 'date-fns/formatRelative'
import subDays from 'date-fns/subDays'

formatRelative(subDays(new Date(), 3), new Date())
//=> "last Friday at 7:26 p.m."

Day.js is also a good alternative to moment.js. It is a minimalist lib (only 2KB) with almost the same complete API.

validator.js

In web development, you always need to validate user's inputs. validator.js contains all the validation functions you need: email, alpha, currency, credit cards, MAC address, etc. More than 60 validators!

import isEmail from 'validator/lib/isEmail'

isEmail('foo@bar.com') // true

intl-messageformat

intl-messageformat provides a way to manage and format your app's string messages into localized strings. It uses the ICU Message syntax and works for all CLDR languages which have pluralization rules defined.

import IntlMessageFormat from 'intl-messageformat';

const photos = `You have {numPhotos, plural,
    =0 {no photos.}
    =1 {one photo.}
    other {# photos.}
}`

const messages = new IntlMessageFormat(photos, 'en-US');

console.log(msg.format({numPhotos: 0}));    // => "You have no photos."
console.log(msg.format({numPhotos: 1}));    // => "You have one photo."
console.log(msg.format({numPhotos: 1000})); // => "You have 1,000 photos."

DOMPurify

In some webapp, I needed to sanitize HTML string coming from the user or external sources. Most of libs I found were very heavy. DOMPurify is one of the lowest and fastest sanitizer. Very easy to use, you can also override its default configuration.

DOMPurify.sanitize('<img src=x onerror=alert(1)//>'); // becomes <img src="x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('<p>abc<iframe/\/src=jAva&Tab;script:alert(3)>def'); // becomes <p>abcdef</p>
DOMPurify.sanitize('<math><mi//xlink:href="data:x,<script>alert(4)</script>">'); // becomes <math><mi></mi></math>
DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>'); // becomes <table><tbody><tr><td>HELLO</td></tr></tbody></table>

Feather icons

Feather icons is just an awesome set of beautiful open source icons.

Faker.js

You are tired to use lorem ipsum text or foo, bar, baz in your unit tests and mockups. So. You have to check faker.js. It can generate addresses, company names, account numbers, phone numbers, images and so on. It supports multiple languages and locales. Here a complete demo

import faker from 'faker'

faker.name.findName() // Rowan Nikolaus
faker.internet.email() // Kassandra.Haley@erich.biz
faker.helpers.createCard() // random contact card containing many properties

And you. Which lib do you use in your web projects?

Firebase callable functions tests with emulator suite

Benjamin Petetot — Tue, 17 Dec 2019 13:12:02 +0000

The Firebase emulator suite brings lot of new capabilities to test your Firebase code. In this article, I will experiment testing callable functions with jest and the Firestore emulator.

Here is a short callable function incrementing a counter document:

// increment.js
const functions = require('firebase-functions')
const admin = require('firebase-admin')

async function increment({ counterId, value }) {
  // get the counter document
  const ref = await admin
    .firestore()
    .collection('counters')
    .doc(counterId)
    .get()

  const counter = await ref.data()

  // increment and save the new counter value
  await admin
    .firestore()
    .collection('counters')
    .doc(counterId)
    .update({ value: counter.value + value })
}

module.exports = {
  increment: functions.https.onCall(increment),
}

To test the function with jest and the emulator we will need to:

Execute jest and the emulator
Mock firebase-functions and firebase-admin
Write the test

Execute the emulator with jest

Following the Firebase emulator documentation, you need to install the emulator with this command:

firebase setup:emulators:firestore

Then, execute the emulator and the jest test suite:

firebase emulators:exec --only firestore "jest"

The emulator will start, then run the test suite, finally shut down the emulator after the tests run. You can add it as a test script in your package.json file. If you want to run jest in watch mode, just set "jest --watch" in the previous command.

Mock `firebase-functions`

For the test, we will directly execute the function, without using firebase-functions. So let's create a simple mock to retrieve exported callable function. Add a file firebase-functions.js in a __mocks__ folder:

// __mocks__/firebase-functions.js
module.exports = {
  https: { onCall: func => func },
}

The mock will directly return the function given to functions.https.onCall, so we will able to execute it directly within the tests.

Mock `firebase-admin`

firebase-admin is used to get the Firebase app instance. We will replace it by the @firebase/testing app to be able to use the emulator. Add a file the firebase-admin.js in the __mocks__ folder:

// __mocks__/firebase-admin.js
const firebase = require('@firebase/testing')

module.exports = firebase.initializeAdminApp({ projectId: "projectId" })

Now we are ready to write tests and we will be able to use Firestore emulator to store, retrieve and test data.

Write the tests

Thanks to the mocks, the emulator and @firebase/testing, you can:

Directly execute your function.
Create and retrieve documents in your test.
Clear firestore database before each tests to get isolated tests.

// increment.spec.js
const firebase = require('@firebase/testing')
const admin = require('firebase-admin')

// use mocks
jest.mock('firebase-admin')
jest.mock('firebase-functions')

const { increment } = require('./increment')

describe('Increment function', () => {
  afterAll(async () => {
    // close connexions to emulator
    await Promise.all(firebase.apps().map(app => app.delete()))
  })

  beforeEach(async () => {
    // clear firestore data before each tests
    await firebase.clearFirestoreData({ projectId: 'projectId' })
  })

  it('Should be able to increment the given counter', async () => {
    // create a counter document
    const counterId = 'counter1'
    await admin
      .firestore()
      .collection('counters')
      .doc(counterId)
      .set({ value: 10 })

    // call the 'increment' function
    await increment({ counterId, value: 20 })

    // get the counter to test the incremented value
    const updatedCounter = await admin
      .firestore()
      .collection('counters')
      .doc(counterId)
      .get()

    // check if we correctly get the counter document
    await firebase.assertSucceeds(updatedCounter)

    // check the counter value
    const { value } = await updatedCounter.data()
    expect(value).toBe(30)
  })
})

Here you can now test your cloud functions locally and in isolation using Firestore emulator. 🎉

Understanding software licenses

Benjamin Petetot — Tue, 10 Dec 2019 14:43:10 +0000

As a developer or an open source project maintainer, it's essential to have knowledge of the different types of licenses. What are your rights and duties when you use them? Which license should you use for your project?

There are several types of licenses available and each may have pros and cons that should be measured before choosing. You must remain vigilant, there may be confusion between different categories of "free" software (OSS, freeware, public domain ...). It exists dozens of free licenses, some of which are viral. This article is intended to help you understand the different features of licenses and choose the most suitable for your project.

Free Software & Open Source

The Free Software Foundation (FSF), an American non-profit company founded in 1985 by R. Stallman, supports the GNU operating system and manages "GPL" licenses.

This foundation gives a definition of free software based on four irrevocable freedoms:

Freedom to use the software.
Freedom to copy the software (includes the freedom to sell copies).
Freedom to study the software (suppose access to the source code).
Freedom to modify the software and redistribute the modified versions.

Free license works are not always available for free and you will often paid for associated services (development, warranties, support, etc.). A work contaminated by a free license, which could initially be available only against payment, must be rebroadcast freely.

« Think Free as Free speech and not Free beer »

R. Stallman

While the Open Source Initiative (OSI), an American non-profit society founded in 1998 by E. Raymond & B. Perens, promotes open source code.

According to OSI, for software to be open source, its license must meet the following 10 criterias:

Free redistribution.
Provision of the source code.
Allow derivative works and modifications.
Integrity of the source code of the author.
No discrimination between individuals or groups.
No discrimination between the fields of application.
No restriction on the distribution of the license (vs NDA).
The license must not be specific to a product.
The license must not restrict other software.
The license must be technologically neutral.

Both terms describe virtually the same category of software. But they represent views based on fundamentally different values.

R. Stallman

Liquid error: internal

Copyright, copyleft and public domain

Before presenting the different types of licenses available, it is necessary to understand the different types of rights applied to projects. Here is an explanation, in simple terms, of the 3 major license types.

Copyright is a right granted to the author of the original work, including the right to authorize or prohibit the publication or distribution of their work. It protects authors from copying or unauthorized sale of their works. Copyright is granted for a limited period of time, then the work enters the public domain.

The public domain includes all creations where no intellectual property rights is applied. These rights may be expired, confiscated, expressly waived or inapplicable. Copyright is generally valid until 50 to 100 years after the author's death. In simple terms, anyone can use, modify and sell these creations without permission from the author.

For example, Beethoven's compositions entered the public domain 70 years after his death in 1827. His musical compositions are available for use and sale by all.

Under copyleft, everyone can edit and distribute the work. It requires only one condition:

the same freedom must be preserved in modified versions of the original work.

People can use, modify and distribute the work as they wish. However, copyleft requires modified work to be distributed on the basis of the same license.

The GNU General Public License, originally written by Richard Stallman, was the first copyleft license.

What type of license to choose or use?

A free software always has a license (contract) of use associated, it is necessary to analyze the conditions of use, the rights and the obligations resulting from it.

To facilitate the understanding of the different types of licenses, we can classify them according to the degree of freedom they grant to the user:

"Strong Copyleft"
"Low Copyleft"
"Permissive"

Strong Copyleft

A license with a strong copyleft has a highly contaminating character. If a software component is under a copylefted license, the same license is imposed on all the software which contains this component. This is known as a "contaminating" or "viral" license. It forces to make available the associated source code and to distribute the entire program (free and proprietary) under the same license.

Some strong copyleft licenses:

GPL: General Public License V3
AGPL: Affero General Public License
CC: Creative Commons declined in 6 licenses, some permissive

In the case of the GPL license, there are some explicit use cases that do not trigger the phenomenon of contamination:

Either by exception clauses included in the license: For example, the GCC Runtime
Either in the case of independent binaries, ie your software uses a program with the GPL license, but does not distribute it.

Stack Overflow threads are also licensed. When you copy and paste a piece of code from the forum, it is important to know that all code snippets posted are under the CC Creative Commons license. 😱

Low Copyleft

A license with a low copyleft, a weakly contaminating character, forces to distribute the modified free software under the same license and to make available the associated source code. But you can freely use a component with a low copyleft in a proprietary software without constraining it to have the same licence.

Some low copyleft licenses:

LGPL: Lesser GPL
EPL: Eclipse Public License
MPL: Mozilla Public License

Here some software and librairies using LGPL license: VLC media player, 7-Zip, GLib, etc.

Permissive

Permissive licenses offer the greatest freedom with unconditional sharing. In general, only the citation of the original authors is requested and allow any actor to change the license under which the software is distributed and without obligation of diffusion.

Some permissive licenses:

BSD: Berkeley Software Distribution
MIT: Massachussetts Institute of Technology
Apache2

The Apache license is the second most popular license in the Free and open source domain after MIT license. If you want to open source your project, I recommend using Apache2 or MIT licence.

There are also more esoteric permissive licenses. Like the Postcard license, which only obligation is to send a postcard to the author. Or the WTFPL (Do What the Fuck You Want to Public License), the name speaks for itself. 🙂

Conclusion

As a developer, if you use libraries or software, do not forget to check their licenses because it can impact your software. As an open source project maintainer, choose your license properly to protect your work or its use. I hope this article help you to know more about different type and categories of licences. Finally I recommend you the website "Choose a license" to compare and choose your license according to your usage.

If you want further news about our projects or future articles consider following our twitter @ZenikaOSS!

Getting started in open source

Benjamin Petetot — Tue, 30 Jul 2019 12:48:29 +0000

The world of open source is vast, it is very easy to get lost. When starting, this world can feel unaccessible and intimidating. Where to start? What are the rules and codes to follow? Can I contribute even if I do not code?
No worries, in this article we will give you all the tips you need to start well, choose the right project and submit your first contribution.

First steps 🐣

First of all, you have to decide on which project you want to start your first contribution. Since there are millions of open source projects, it can be difficult to find one's way.

A first idea, which is perhaps the simplest, is to identify projects that you like, that you often use or projects that mean a lot to you. It will be easier to start in a familiar environment which will keep you motivated in the long term.

It is also important to take into account the maturity of the project and its size. It is tempting to start with large frameworks, libraries or tools like VS Code, MongoDB, Android, React…. These kind of projects have many contributors, many bugs to fix or features to add. Contributions on these projects bring some satisfaction when they are merged. But these projects, with millions of lines of code, are not the best choice to get started in open source. Their communities are already well developed and many people are offering contributions for a limited number of maintainers. It can take a while before your contribution is studied and potentially accepted.

Starting on smaller projects with potential is a better way to get started. Keep an eye out for growing projects, on the GitHub trending for example,and find the ones that match your interests.

Another good way to identify a suitable project is to select those which are actively looking for contributors. Several websites and tools can help:

Awesome for beginners is a list of projects looking for contributors (beginners or not) by listing their "Good First Issues". In the same way, the website Up for grabs makes it possible to find projects in need of contributors.
CodeTriage is a tool for subscribing to open source projects and receiving new requests for contributions every day.
First contributions is a little different, it is a workshop to make your first contribution in less than five minutes. It introduces the basis of the Git workflow to make contributions on GitHub. In addition to this tutorial, the website offers links to "Good First Issues" of large GitHub projects.
Evenings or community events like HacktoberFest are also a good way to get started on projects looking for contributors. For example, the hack.commit.push organizes an open source development day, open to everyone, regardless of your level. At the beginning of the day, introductory workshops are presented, followed by open source contributions with mentors.

Once you have found your dream project(s), you will need to start reading up on these projects, The README is a good entry point for project overview. The Code of Conduct and the Contribution Guide are more focused on how to interact with the project and its community. It doesn’t take long, but it is mandatory before starting a contribution. It will give you the tips, rules and procedures you need to follow, allowing consistency and maintenance of the project.

Code of conduct

Most open source projects have a code of conduct. It allows maintainers to define rules and behaviors to adopt on their project.

The essential points of this code define the rules to be followed by the participants. Learn to respect different points of view, listen and accept feedback on your contributions. Potential disagreements are to be expected. Do not take them personally. Sometimes, during reviews, it is possible that individuals do not agree on some decisions or approaches taken. It is therefore very important to stay professional and respect the code of conduct. Any feedback is valuable and it is during these discussions that we learn the most.

It is also very important to be patient. Many open source projects are maintained on personal time. It may take some time before your contribution is reviewed or accepted.

Here is an example of a code of conduct used by many projects: Contributor convenant. The rules it defines should be applied in both open source and professional environment.

The contribution guide

It defines workflows and ways of coding on the project, it helps understanding the standards and expectations of the community. For example:

How to set up my development environment?
How to post an issue?
What are the commit standards?
What are the expectations on the tests?

If a contribution does not follow these recommended practices, it may be rejected before it has even been reviewed. These standards serve to maintain coherence in the project but also to save time for the project maintainers. So read it carefully.

Join the community

A project is not limited to documentation and source code. It is also important to understand and interact with the project community. There are different roles in an open source project, the three main ones are:

The maintainers or core contributors, who are at the origin of the project or have been invited to this role thanks to all the contributions they have made.
Contributors, who participate in the life of the project by offering contributions (documentation, bug fixes...), answering questions or opening user tickets.
And users, who will of course use the project but mostly give feedback, post bugs, propose improvements or ask questions on forums.

The means of communication in the community vary based on the project. It can be a mailing list, a Slack, a Discord or any other tool of this kind. You will be able to ask questions, help defining roadmaps, or simply discussing amongst enthusiasts.

First contribution 🐥

Now that you have identified a project that interests you and you have read the necessary documentation to get started, you are ready to offer your first contribution.

Above all, you do not need to know how to code to contribute to open source projects:

Do you like to write? Correct or develop the project’s documentation.
Do you master design? Create the logo or project website.
Do you like to communicate? Answer questions from the community.

All contributions are good and help the project. Here is a non-exhaustive list of tasks you can do to help open source projects:

Documenting

Write and correct the project’s documentation;
Translate the documentation.

Organizing

Submit bugs or new features;
Answer issues, file them and close them if necessary;
Answer questions (e.g. on GitHub, Stack Overflow...).

Communicating

Write articles or tutorials;
Organize meetups or conferences about the project;
Communicate on Twitter (new releases, contributions...);
Create a design for the project (logo, colors...);
Develop a website for the project.

Coding

Conduct code reviews;
Develop tests;
Automate the project (CI...);
Fix bugs;
Add new features.

If you do not know where to start, go through the list of open issues on the project. In many projects, some tickets are identified as "Good First Issues" or "Beginner". They are identified by the main contributors as simple contributions and good entry points into the project. Also look out for "Help needed/wanted" categorized tickets waiting for a contributor to assign themselves.

When you have identified an issue or a ticket you wish to contribute to, you must position yourself on it. Do not hesitate to ask other contributors for information. Discussions and exchange are essential to properly start a new contribution. They will guide you towards the expectations of the community, validate a technical solution or identify potential constraints or difficulties.

Before you publish your first contribution, check your code and do not forget to test it before submitting. Do not hesitate to explain the context and document your contribution. Anything that will help other contributors and maintainers to review it will speed up its integration.

Finally, when you have made your first contribution, do not forget to communicate on it and share it with the world on Twitter, Facebook, or your favorite social network.

If you want further news about our projects or future articles don't forget to follow our twitter @ZenikaOSS!

Themify your app with Custom Properties

Benjamin Petetot — Wed, 10 Jul 2019 13:41:24 +0000

My current side-project is an open SaaS platform to manage call for papers called Conference Hall. When I started it, I wanted to have different themes following the user's role. A blue theme if you are a speaker, and a red one for organizers.

The application is currently built with React and there are plenty of ways to build a theming system using providers, hooks, styled components, css-in-js etc. But I wanted to keep it simple and closed to what it's supposed to be: "style". So I decided to use one of the new powers of CSS: "Custom Properties" (or CSS variables) and its inheritance system.

Here a live demo and explanations following.

Themify with custom properties

First declare a default theme with all custom properties needed for the theme.

.default-theme {
  --background-color: #FFF;
  --font-color: #000;
}

Set the default theme class to the body (or an other root element). This element and its children will have access to the variables.

<body class="default-theme">
...
</body>

These variables can be used in your CSS through the var() function.

body {
  background: var(--background-color);
  color: var(--font-color);
}

So, what should we do to change the theme of the app ?

Declare a new CSS class with the custom properties to override in the new theme, then apply it to the element. Thanks to the inheritance of custom properties you have the dark mode in your application.

.dark-theme {
  --background-color: #000;
  --font-color: #FFF;
}

<body class="default-theme dark-theme">
...
</body>

Apply theme to sub-components

If you use the custom properties (var()) in all your sub-compoments the theme will be automatically applied.

But you may build your components independently from your application (with Storybook, DocZ, etc.) and the theming system implies that some of your components should use these custom properties. So if you want to have a component that renders correctly without declaring CSS variable, you can:

Pass the CSS variable through a color props to the component;
Pass class or style with CSS variables to the component;
Or use the CSS variable inside of it with a fallback value (2nd parameter of the var function):

.my-component {
  background: var(--background-color, #DDD), 
}

Browser compatibility

Most browsers already support custom properties except Internet Explorer. But if you want to keep a fallback for IE you can add an additional property in the CSS class. Of course, theme switching will not work on IE with custom properties.

.my-component {
  background: #DDD, 
  background: var(--background-color, #DDD), 
}

All the theming system of my application Conference Hall is entirely based on custom properties and works very well. I hope it will help you.

See the live demo in codepen: