DEV Community: Guillaume Martigny

TypeScript is wasting my time

Guillaume Martigny — Fri, 22 Apr 2022 12:47:46 +0000

⚠️ This is a bit of a rant as I've lost patience with TypeScript and I need to vent.

While converting a medium sized Nuxt application (~15 pages, i18n, auth, REST API) to TypeScript, I compiled a list of pain points (no specific order). This is not the first time that TS made me miserable while trying to use it. Maybe this is a "me" problem and I lack knowledge or skills. But, if this is the case, I bet that a lot of new developers also hit these roadblocks and didn't say anything because of the hype surrounding TS.

Is it `null` tho ?

Consider this simple "cache initialization" code:

Object.keys(localStorage).forEach((key) => {
  store.commit('cache/init', {
    key,
    value: JSON.parse(localStorage.getItem(key)),
  });
});

Playground

It iterate over all items in localStorage and send the parsed value to the store.
Here, I get an error under localStorage.getItem(key) because JSON.parse accept string as its first argument and localStorage.getItem can return null. Ok ... but ... whatever dude ! JSON.parse(null) doesn't even produce an error. Even worse, I can't have unset values because I'm looping over existing items in the localStorage.

`"compact"` is not `"compact"`

Consider this number formater code:

function formatNumber(value: number, lang: string = 'en') {
  const options = {
    notation: 'compact',
    maximumFractionDigits: 1,
  };
  const formatter = Intl.NumberFormat(lang, options);
  return formatter.format(value);
}

Playground

The options parameter is underlined with an error because the field notation is a string when it should be "compact" | "standard" | "scientific" | "engineering" | undefined. Well ... it's hardcoded to "compact", which is pretty close to "compact" to me.

Type `IDontCare`

Consider this plugin declaration in Nuxt:

export default (_, inject: Function) => {
  inject('myPlugin', /* Plugin code */);
};

Playground

In Nuxt, plugins are called with 2 parameters. The first is the Nuxt context, the second is a function that add the plugin to said context.
Here, I don't use the context, so set it to _ (as per the recommendations). But I get an error because it has an implicit type any. I mean ... right, but who cares ? I'm not using this parameter. I have specifically renamed it to inform that I don't use it. Why does it reports as an error ?

Code duplication !

This one is pretty nasty to me. Again, consider a plugin declaration in Nuxt. This plugin expose a set of function.

export default (_: DontCare, inject: Function) => {
  const API = {
    get(key: string): object { /* Code code code */ }
    set(key: string, value: object): void { /* Code code code */ }
  };
  inject('myPlugin', API);
};

Everything's good until there. Now, I want to use it in my code. I have to declare the injected function in every possible place.

interface API {
    get(key: string): object
    set(key: string, value: object): void
}
declare module 'vue/types/vue' {
  // this.$myPlugin inside Vue components
  interface Vue {
    $myPlugin: API
  }
}

declare module '@nuxt/types' {
  // nuxtContext.app.$myPlugin inside asyncData, fetch, plugins, middleware, nuxtServerInit
  interface NuxtAppOptions {
    $myPlugin: API
  }
  // nuxtContext.$myPlugin
  interface Context {
    $myPlugin: API
  }
}

declare module 'vuex/types/index' {
  // this.$myPlugin inside Vuex stores
  interface Store<S> {
    $myPlugin: API
  }
}

export default (_: DontCare, inject: Function) => {
  const API: API = {
    get(key) { /* Code code code */ }
    set(key, value) { /* Code code code */ }
  };
  inject('myPlugin', API);
};

The worst part is not even that I have to tell TS that Nuxt is injecting my plugin everywhere. The worst part is that I have to make sure that every function signature in the plugin match with the interface. Why can't I infer types from the API itself ? Also, ctrl + click become useless as it points to the interface and not the implementation (maybe an IDE issue, but still ...).

The cherry on top is that now, ESlint is pouting because function params in the interface are considered unused.

Import without the extension

TS need the file extension to detect the file type and compile accordingly. Fair enough, but now I have to go through all my import and add .vue everywhere.

Dynamic interface

I have an URL builder that I can chain call to append to a string.

const API = () => {
  let url = 'api';
  const builder = {
    currentUser() {
      return this.users('4321');
    },
    toString() {
      return url;
    }
  };
  ['users', 'articles', /* ... */].forEach((entity) => {
    builder[entity] = (id) => {
      url += `/${entity}${id ? `/${id}` : ''}`;
      return builder;
    };
  });
};

// Usage
const url = `${API().users('4321').articles()}`; // => 'api/users/4321/articles'

This is fine and dandy until TS coming shrieking. I can declare a type listing my entities and use this type as key in a Record (see Code duplication !). But I also need to describe the toString and currentUser methods aside.

type Entities = 'users' | 'articles' | /* ... */;
type URLBuilder = Record<Entities, (id?: string) => URLBuilder> & {
  currentUser(): URLBuilder
  toString(): string
};

const API = () => {
    let url = 'api';
    const builder: URLBuilder = {
        currentUser() {
            return this.users('4321');
        },
        toString() {
            return url;
        }
    };

    const entities: Entities[] = ['users', 'articles'];
    entities.forEach((entity) => {
        builder[entity] = function (id?: string) {
            url += `/${entity}${id ? `/${id}` : ''}`;
            return this;
        }
    });

    return builder;
};

Playground

Problem solved ? Not quite ... The temporary builder initialized while building the whole thing is not yet of type URLBuilder. I have no idea how to say "This will be of type T in a few lines".

Conclusion

I'm absolutely sure that all those issues are due to some lack of knowledge. If you have an elegant solution for any of those, please share in the comments.

Microsoft is not investing so much energy in something that's wasting time. I would love to come back to this article in a few years and finding all of this ridiculous, but for now, I really don't get the hype around Typescript.

Thanks for indulging me 😎

How I write web apps in 2021 ?

Guillaume Martigny — Wed, 10 Feb 2021 11:21:46 +0000

Content

Introduction
- Disclaimer
Languages
Installation
- Vue
- Bundler
- Optionals
Development
- Adding views and components
  - Views
  - Components
- Dynamic page
  - Fetch from API
  - User editing
- Component libraries
Deployment
Troubleshooting
FAQ

Introduction

In this article, I'm going to present you step by step what tools I use.
You can follow along, but it's more important to understand "why I am doing this" rather than "what I am doing".
A good advice is, try to do the same step alongside me in this tutorial. Then, try to change a few bigger and bigger things. Finally, at the end, you should be able to do everything again on your own.

You can find all the produced code over at the Github repository.

Disclaimer

First of all, and this is really important, all of this is my own bias opinion on development. We all have our unique way at looking at things.
Web development is a huge and complex topic. This post is not meant to describe the easiest or quickest methods.
However, this is the methods I grew up preferring (for reasons I'll get to), and the one I'm most capable of explaining in details.

From here, I assume you have basic Javascript and Vue understanding. I'm also not going to detail how to install Node.js and how to use NPM.

Languages

With that out of the way, let's start with languages.
I have worked with Javascript for about 10 years. It has a lot of detractors, but it was and still is the language I enjoy the most.
It's easy to use, has one of the largest community and can power huge application.

Of course, I'm also writing everything in English. Although it's not my mother tongue, it's recognize as the international language.

Installation

Node.js is installed on my computed, so I'll use NPM to install all my JS dependencies.
The first thing I always do when starting a new project is

$ npm init

This will create the package.json file.
Then I manually create a readme.md and .gitignore file as well as a src directory that will be useful later.

Vue

I like Vue and that's what I mostly use. The installation is straightforward

$ npm install vue

Bundler

I like the modular template syntaxe that Vue offer. However, this is not native JS that a browser can understand.
So, it needs to be transformed before it can be used.

I use Webpack for that. The installation is not as simple because we need a lot more modules.
First, let's start with Webpack itself and its CLI interface

$ npm install webpack webpack-cli

Then, I need to add the plugin that handle Vue files with its compiler

$ npm install vue-loader vue-template-compiler

Finally, chances are that I'm going to write CSS, so I need another pair of plugins to handle CSS code

$ npm install css-loader style-loader

Now, I need to configure Webpack. This is the least fun part, but we need to understand this step to solve possible future issues.
Webpack can be configured with a file named webpack.config.js, so let's create it.

Here is the bare minimum. We'll come back later if we need to expand it.

// Get the vue-loader plugin
const VueLoaderPlugin = require("vue-loader/lib/plugin");

// This is what the file exports
module.exports = {
    // My entry point
    entry: "./src/index.js",
    module: {
        rules: [
            // All Vue files use the vue-loader
            {
                test: /\.vue$/,
                loader: "vue-loader",
            },
            // All CSS files use css than style loaders
            {
                test: /\.css$/,
                use: [
                    "style-loader",
                    "css-loader"
                ]
            },
        ],
    },
    plugins: [
        // Register the vue-loader plugin
        new VueLoaderPlugin(),
    ],
};

With all that out of the way, I just need to run in my terminal

$ webpack

to see my project being entirely compacted and minified. This will fail for now, don't worry.

Optionals

These tools are out of scope for this article. Maybe I'll go in more details in the next one.

I always use Eslint to check for potential mistakes in my code.
In order to use it with my personal configuration I run

$ npm install eslint eslint-plugin-vue @gmartigny/eslint-config

I try to test my code to catch regression and be sure that I cover most use cases. I use AVA for the test and NYC for the code coverage.

$ npm install ava nyc

Development

That's already a lot of steps, and I haven't even write a single line of code. All of that looks like a lot, but trust me, it will make you go faster in the future.

The most attentives around you would remember that in my Webpack configuration, the entry file was ./src/index.js. So, let's start there.
I create an index.js file in src and add a few lines of code to call Vue (with ESM).

// Import Vue, I prefer the ESM syntaxe
import Vue from "vue/dist/vue.esm.js";

// Create a new Vue instance targeted at the element with the id "app"
new Vue({
    el: "#app",
});

With this bare-bones JS file, I can safely run

$ webpack --mode=development --watch

to trigger Webpack in development mode (slower but more descriptive on errors) with watch (will rebuild every time I change the code).
This will create a new main.js file within a dist directory. It's the file that my final users will use.

I now create a index.html file (usually in a public directory, but it doesn't matter).

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Test</title>
</head>
<body>
<!-- My target element -->
<main id="app"></main>
<!-- The JS file from webpack -->
<script src="../dist/main.js"></script>
</body>
</html>

Opening this file in your browser will show nothing as expected, but this is all working. This is the state of my project so far.

Adding views and components

Your Vue files should be split between views (an individual screen, eg: Menu, About ...) and components (composing your views, eg: Button, Footer ...)
Both works the same, but don't have the same concerns. So let's add two directories (views and components) in src to sort them out.

Views

Let's begin by creating a new view. This is going to be the homepage, so I'll call the file Home.vue.

I used a capital letter in the file name to show that it's a class as in other OOP language like Java.

<template>
    <h1>Home</h1>
</template>

<script>
export default {
    name: "Home",
};
</script>

In order to go into that view, I have to tell my Vue instance to render it. In the index.js file, I'll add the necessary lines.

import Vue from "vue/dist/vue.esm.js";
// Import the view
import Home from "./views/Home.vue";

new Vue({
    el: "#app",
    // Declare it as a components I'll use (I know, views are treated as components by Vue)
    components: {
        Home,
    },
    // Render the view
    template: "<Home/>",
});

In order to have more views, you need navigation between the views, so you need vue-router. We're not going to talk about it for now.

Components

Imagine I want to have a simple card (title + text) for each film I want to see, I don't want to duplicate the code for each cards. A good rule is DRY (Don't Repeat Yourself).
If you write something more than twice, it should be factorized in one place.

Again, I create a new file called Film.vue in the components directory.

<template>
    <div class="film">
        <h2>Title</h2>
        <p>Text</p>
    </div>
</template>

<script>
export default {
    name: "Film",
};
</script>

<!-- scoped because I don't want to interfere with any other component -->
<style scoped>
.film {
    border: 1px solid blue;
}
</style>

And use it in Home.vue.

<template>
    <div>
        <!-- Use the component -->
        <Film />
        <Film />
        <Film />
    </div>
</template>

<script>
// Import the component
import Film from "../components/Film.vue";

export default {
    name: "Home",
    components: {
        // Declare the component
        Film,
    },
};
</script>

As you should already see, I have 3 cards with the same title and text.
Which is not what I want to do.
If I add properties to my card component and write data in my home view, it will allow me to define value for each individual card.

<template>
    <div class="film">
        <!-- Use properties here -->
        <h2>{{ title }}</h2>
        <p>{{ text }}</p>
    </div>
</template>

<script>
export default {
    name: "Film",
    // Properties list declaration
    props: ["title", "text"],
};
</script>

<style scoped>
.film {
    border: 1px solid blue;
}
</style>

<template>
    <div>
        <!-- Loop through my data -->
        <Film v-for="(film, index) in films" :key="index"
              :title="film.title" :text="film.text"/>
    </div>
</template>

<script>
import Film from "../components/Film.vue";

export default {
    name: "Home",
    components: {
        Film,
    },
    // data should be a function
    data () {
        // that return a set of values
        return {
            films: [
                {
                    title: "Alien",
                    text: "It follows the crew of the commercial space tug Nostromo, who encounter the eponymous Alien, an aggressive and deadly extraterrestrial set loose on the ship.",
                },
                {
                    title: "Interstellar",
                    text: "In a dystopian future where humanity is struggling to survive, it follows a group of astronauts who travel through a wormhole near Saturn in search of a new home for mankind.",
                },
                {
                    title: "Reservoir Dogs",
                    text: "Diamond thieves whose planned heist of a jewelry store goes terribly wrong.",
                },
            ],
        };
    },
};
</script>

With that in place, any changes applied to my data will be reflected on screen.

Dynamic page

I can, for example, fetch data from an API or allow the user to edit the page (or both 😉).

Fetch from API

First, I'll fetch my data from a mock API online. In order to do that, I start by emptying the data array.
Then, according to the Vue lifecycle, I can use mounted function to execute code when the view appears on screen.

<template>
    <!-- ... -->
</template>

<script>
import Film from "../components/Film.vue";

export default {
    name: "Home",
    components: {
        Film,
    },
    data () {
        return {
            // Emtpy film list
            films: [],
        };
    },
    async mounted () {
        // Fetch from mock API
        const response = await fetch("https://mock-film-api-t0jk5mabvwnt.runkit.sh/");
        if (response.ok) {
            // Load result into films list
            this.films = await response.json();
        }
    },
};
</script>

User editing

In the same way, I can allow users to add new film to the list. A small HTML form that push a new entry when submitted will see the modifications reflected on the view.

<template>
    <v-app>
        <Film v-for="(film, index) in films" :key="index"
              :title="film.title" :text="film.text"/>
        <!-- Form that will call addFilm when submitted -->
        <form @submit="addFilm">
            <div>
                <label for="title">Title</label>
                <!-- v-model link the input value to a variable -->
                <input type="text" v-model="inputTitle" id="title">
            </div>
            <div>
                <label for="text">Text</label>
                <input type="text" v-model="inputText" id="text">
            </div>
            <button type="submit">Add</button>
        </form>
    </v-app>
</template>

<script>
import Film from "../components/Film.vue";

export default {
    name: "Home",
    components: {
        Film,
    },
    data () {
        return {
            films: [],
            // Holds the value of each input
            inputTitle: "",
            inputText: "",
        };
    },
    async mounted () {
        // ...
    },
    methods: {
        // New method
        addFilm (event) {
            // Stop the form from reloading the page (default behavior)
            event.preventDefault();
            // Add a new film to the list
            this.films.push({
                title: this.inputTitle,
                text: this.inputText,
            });
            // Clear out input fields
            this.inputTitle = "";
            this.inputText = "";
        },
    },
};
</script>

This will of course not save anything online, and changes made will be lost when the page is reloaded.
You could improve this example by sending a request to a server that save the inputs in a database.

Component libraries

I'm lazy. Being an efficient developer often means being lazy.
Instead of creating all my components, I can use already existing libraries of components. That way, I can focus more on content instead of how to correctly design a datepicker.

Since I use Vue, I choose a Vue compatible library, Vuetify.

npm install vuetify

Really few changes are needed to activate it in index.js.

import Vue from "vue/dist/vue.esm.js";
// Get Vuetify and its CSS
import Vuetify from "vuetify";
import "vuetify/dist/vuetify.min.css";

import Home from "./views/Home.vue";

// Prepare the usage of vuetify
Vue.use(Vuetify);
const vuetify = new Vuetify();

new Vue({
    // Pass the instance to Vue
    vuetify,
    el: "#app",
    components: {
        Home,
    },
    template: "<Home/>",
});

Then I can use it everywhere in my application (here in Film.vue).

<template>
    <!-- All Vuetify components are prefixed with "v-" -->
    <v-col cols="12">
        <v-card shaped>
            <v-card-title>{{ title }}</v-card-title>
            <v-card-text>{{ text }}</v-card-text>
        </v-card>
    </v-col>
</template>

<script>
    // ...
</script>

<!-- I don't need my crappy style anymore -->

Deployment

One of my favorite recent discovery is serverless. Basically, as long as your application is stateless (always return the same result with the same parameters), you don't need to have a complex, always running server. By leveraging the power of caching and ressource sharing you can reduce your server to almost nothing.

Using Vercel, I'm able to freely host, deploy and serve with a few clicks. All I need is for the project to be on Github.

Troubleshooting

You are using the runtime-only build of Vue where the template compiler is not available.

Your import of Vue is wrong. If you remember, there are many ways to import Vue. By default, import "vue" will call the vue.runtime.common.js file.
In my code here, I'm using the ESM with template (so I need the vue.esm.js).

[Vuetify] Multiple instances of Vue detected / this.$vuetify is undefined

Your application and Vuetify didn't import the "same" Vue. As explain above, it's important to import the right Vue for your usage.
A nice solution to this is to create an alias in webpack.

// In webpack.config.js
module.exports = {
    // This will tell all your code to use the same Vue.
    resolve: {
        alias: {
            vue$: "vue/dist/vue.esm.js",
        },
    },
    // ...
};

FAQ

Why do you don't use CLI to setup your app ? (like vue-cli or create-react-app)

While these CLI are great ways to quickstart a project, they slow you down in the long run. They all use the same technologies I presented you today, but in a complex and confusing way.
Using create-react-app install about 2000 packages. If something goes wrong, debugging that much code is not an easy task.
I've always preferred taking the longer road, but at the end of the day, understand what's going on.

Why don't you need to import each Vuetify components when you use them ?

When I do Vue.use(Vuetify); in the index.js, it activates it in the whole project.
It's possible to import only Vuetify components when you use them. But this requires a bit more work that is out of scope for this tutorial.

Why don't you use X instead of Y ?

I'm used to it. I'm sure you'll find better alternative to any tools or methods I describe above. But I know them.
At the end of the day, it's more important to deliver than endlessly learn new technologies.

What are my alternatives ?

Vue:

React
Angular
Svelte

Vuetify:

Material-UI
Any CSS frameworks:
- Bootstrap
- Bulma
- Tailwind

Webpack:

Rollup
Skypack

Vercel:

Netlify
Heroku

Pencil.js quick-start

Guillaume Martigny — Tue, 24 Mar 2020 13:24:45 +0000

I recently spent some time putting together a new way to discover the Pencil.js library. In 9 steps, I show how to create this nice interactive scene form scratch.

Go check it out on the Pencil.js website.

It was a fun exercise to find the most straightforwards way to present a handful of modules. I also tried to keep it short in order to not make it boring.

I really hope you like it and this help new people discover all Pencil.js can offer. If you followed the tutorial to the end, I would love to hear what you think about it.

Peace 😎

Come code with me ...

Guillaume Martigny — Mon, 05 Aug 2019 16:43:48 +0000

From now on, I'll stream my working process over Twitch everyday.
So come join me all days of the week from 12:00pm to 6:00pm CEST.

So why come joining me ?

I'll be working on open-source projects using modern Javascript stack. I'll do my best to answer any question related to the stream, so come if you want to have a nice chat about new web technologies.
Also, you can laugh at my weird French accent 🤓🇫🇷.

I hope to see you there, and until next time, peace ✌️

Arbitrary large integer

Guillaume Martigny — Fri, 02 Aug 2019 13:22:21 +0000

Problem

At one point or another, while using JS, you should have encounter the limitation of number encoding. The most infamous example is:

0.1 + 0.2 === 0.3 // => false

Javascript encode numbers using 64bits of memory (64 binary digits). Since we want to deal with floating numbers (non-finite set), modern languages have to rely on weird maths.
I'm not going to explain it here, because I don't understand it fully myself. But you should know that storing infinite precision numbers over finite memory is not possible.

Math.PI // => 3.141592653589793 "only" 16 digits long.

As it can lack precision for small number, it's also true for large numbers. As soon as you go higher than Number.MAX_SAFE_INTEGER or 2^53 - 1, you're subject to error.

Number.MAX_SAFE_INTEGER     // => 9007199254740991
Number.MAX_SAFE_INTEGER + 2 // => 9007199254740992 (1 + 2 = 2 ?)

It can get even worse if your integer goes beyond Number.MAX_VALUE or 2^1024 - 1, because JS will treat it as Infinity.

Number.MAX_VALUE // => 1.7976931348623157e+308
Number.MAX_VALUE * 2 // => Infinity
1.8e308 // => Infinity

Solution

Recently, Javascript has a new number representation: BigInt. It's now supported by FireFox (v68), Chrome (v67) and Edge (v76). This allow you to write number as large as your computer memory can handle.

It's extremely easy to use, just add a n character in the end of your numbers.

99 ** 999 // => Infinity
99n ** 999n // => 436073206168265161501341703386462012231079860756206...

If you can't add the n, like when you consume the result of a function, you can wrap it in a constructor.

BigInt(getNumberViewers()) * BigInt(getAverageWatchDuration())

There's a few thing to remember while using BigInts.

First, BigInts are not compatible with regular numbers. So, you need to transform all operand to one or the other when doing maths.

const bigInt = 99n ** 999n;
bigInt * 10 // => TypeError: Cannot mix BigInt and other types

Secondly, BigInts are not compatible with Math. Only basic maths operation are allowed.

Math.max(10n, 20n) // => TypeError: Cannot convert a BigInt value to a number
10n < 20n // => true

Thirdly, while division are supported, they automatically round to the closest to 0 integer.

19n / 10n // => 1n
-19n / 10n // => -1n

Finally, you'll have to consider that BigInt are a bit more ressource consuming than native numbers. So you should be using them only when manipulating ever growing numbers, like timestamps, users actions ...

I hope you enjoy this little article. Look for more articles from me on the right panel and consider following me on Github or Twitter.

Until next time, peace ✌️

Do you know any social network for personal projects ?

Guillaume Martigny — Tue, 09 Jul 2019 18:59:26 +0000

Hello everyone,

Many of us (not everyone) love to create side projects and more often than not these projects are never finished or never see a single user.

That's a shame that so many hours and motivation are poured into the void. So I was looking for some kind of social network for digital makers. Whether it be art, code, sound, etc, you could share what you're working on and get unbiased feedback. At the same time it could allow to connect people with complementary skills willing to work together.

There's so many social network out there, but I can't find any dedicated to ongoing projects and I don't seems to be the only one.

Do you know anything like it ?

V8.js - Access native v8 engine function from Javascript

Guillaume Martigny — Fri, 17 May 2019 18:52:21 +0000

When Google decide to create his own web browser, their engineers build a brand new Javascript engine. Build for speed and memory performance, its adoption into Node.js makes it the most influential engine out there.

A few things was impossible to do in Javascript. Specifically discussing with the engine itself and make use of its native methods. Getting a precise measure of the heap memory size (only possible on Chrome), triggering the garbage collector or getting the optimisation status of a function was inaccessible to Javascripts devs.

Not anymore.

V8.js

Using the flag --allow-natives-syntax on execution now allow you to call all V8's native methods. Since the syntaxe can still be a bit clanky, V8.js wrap it around a more classic library interface.

Install

Like any other library available on NPM, you can install V8.js with one command line:

$ npm install v8.js

Or add a <script> tag in your HTML page:

<script src="https://unpkg.com/v8.js"></script>
<!-- Or -->
<script src="https://cdn.jsdelivr.net/npm/v8.js"></script>

Usage

Once installed, V8.js can be required and expose a list of functions for you to use.

const v8 = require("v8.js"); // Only for node

v8.getHeapUsage();

Example

const v8 = require("v8.js");

const previousUsage = v8.getHeapUsage();
v8.collectGarbage();
const afterUsage = v8.getHeapUsage();

console.log(`Just cleared ${previousUsage - afterUsage} bytes of memory.`);

I need you !

I still consider it a beta version (hence the v0.2.0 version). So I'll warmly welcome any feedback.

The list of available functions of the v8 engine is quite large and I didn't want to include everything blindly. So if you see something useful V8.js is missing raise a new issue with your use-case.

Peace ✌️

Why the JS ecosystem is awesome !

Guillaume Martigny — Sat, 27 Apr 2019 17:26:36 +0000

The Javascript world is today's the most vibrant development ecosystem. It's popularity propelled it from a simple scripting gadget to the backbone of today's web. Browsers are more powerful each passing day, NPM registry grows to whooping 1 million packages and Node has long shown it's a competent back-end language.

Today, we're going to create a tiny project from scratch together and take full advantage of all that. I want to show you that you don't need years of experience to create something cool.
Buckle up, it's a long ride, but I promise you that by the end you can do it all by yourself.

Act I: the code

Let's say you have an idea you want to code. No, no, a simpler one. Something that can fit in one function. Something like creating a unique image per username, returning the hour of any timezone or return a random color.

For our purposes, we're going to create a function that give a blank image given dimensions. No big deal, just create a canvas, color it and return the data. We will called it lorem-pix.

So, I start every project the same way:

$ mkdir lorem-pix
$ cd lorem-pix
$ git init
$ npm init

Then, let's create that index.js and start coding:

const loremPix = (width, height, color) => {
    const canvas = createCanvas(width, height);
    const ctx = canvas.getContext("2d");

    ctx.fillStyle = color;
    ctx.fillRect(0, 0, width, height);

    return canvas.toDataURL("image/png");
};
module.exports = loremPix;

At this point, you should note that createCanvas is not defined. If I was in a browser, I'll just have to do document.createElement("canvas"), but I already know I don't want to stay in the browser environment and Node has no Canvas support. 😱
What could we do ?

Act II: NPM

With hundreds of thousands of packages, NPM potentially hold a solution for any of your problems. As NPM-cli comes bundled with Node, it's safe to say that it's the most influential program in Javascript.

Don't mix-up NPM and NPM-cli. The former is the public registry holding all the codes while the latter is the utility requesting from the registry.

A bit of research gives me exactly what I need. All left to do is fetching the desired dependency.

$ npm install canvas

And add a require at the top of our index.js file.

const { createCanvas } = require("canvas");

Note that Node sadly don't support the import statement as of today.

And voilà, our function is now done. We can even publish it at NPM so anyone can use it. Just make sure your package.json is correctly filled and we're good to go.

$ npm publish

Ok, this is already pretty great. We have a function that rely on someone else code and we published it so anyone can rely on us.
But why not go a little further ?

Act III: CLI

Since NPM-cli 5.2.0, a new command is available: npx. Thanks to it, you can execute code hosted on NPM with a single command line. It magically download, install what need to be and run the required binary file.

But we need to have a binary executable. Our JS function is great, but can only be called by a JS script.
Let's remedy that by creating a new file named cli.js. Running a plain text file on the operating system is not going to work. We need to tell which program have to parse the code inside it. In our case we need it to be Node (default is bash on unix or cmd.exe on windows). Fortunately, we can do so with a shebang.

#!/usr/bin/env node
const loremPix = require(".");
const { writeFileSync } = require("fs");

const inputs = process.argv.slice(2);

const dataURL = loremPix(...inputs);

writeFileSync("lorem.png", dataURL.split(",")[1], "base64");
console.log("Done creating image.");

On the first line, you can notice the shebang thing. Then we import our own library and the Node file-system utility.
Next, we gather the inputs from the command-line arguments, the first one being the program (node) and the second one the file executed (cli.js). Anything after that is treated as arguments to our function.
Finally, the script write the file using the returned data. Details don't matter, but it need a file name, some data and the encoding method.

After a chmod to add execution rights, we are now able to run this script like any program installed on your computer.

$ chmod +x cli.js
$ ./cli.js 200 150 red
> Done creating image.

Boom! A new file called lorem.png appeared right next to the cli.js and you guessed it, it's a red image of 200 by 150 pixels.

Incredible! 😮

It means that anyone with Node installed can call npx to use our fantastic library.

$ npx lorem-pix 200 150 red

So now, what if we want to make it available to user even without Node ?

Act IV: API

Historically, JS was created to be used on back-end and Node is the rightful heir of that history. If our code is deployed on a Node back-end, it can be run with a simple URL call.
I'm going to use ZEIT's now because I love it. It's so simple it hurt.

First, we can again add a new file called api.js and fill it according to the documentation.

const loremPix = require(".");
const { parse } = require("url");

module.exports = (request, response) => {
    const { query } = parse(request.url, true);
    const { width, height, color } = query;

    const data = loremPix(width, height, color);

    response.writeHead(200, {
        "Content-Type": "image/png",
    });
    response.write(data.split(",")[1], "base64");
    response.end();
};

Almost like cli.js: import our library, parse the URL for the right parameters and write the result to the response back to the user.

We also need a now.json file to configure now.

{
    "version": 2,
    "builds": [
        {
            "src": "api.js",
            "use": "@now/node"
        }
    ],
    "routes": [
        {
            "src": "/api/(?<width>[^/]+)/?(?<height>[^/]*)/?(?<color>[^/]*)",
            "dest": "/api.js?width=$width&height=$height&color=$color"
        }
    ]
}

First we tell now to use Node to run api.js. Kind of like the shebang for the cli.js.
The hieroglyphs by the end is a regular expression. Users are lazy and so am I. It's easier for me to parse URL like api.js?width=200&height=150, but it's more simple for users to write api/200/150. The regexp do just that by rerouting requests.

Ok, time to deploy the API.

$ npx now login
$ npx now

Once done, the program tells you which URL you can use to execute the code. In my case:
https://lorem-pix-o5fjmzam5.now.sh/api/200/150/red

The API return an image whenever someone request it. It means that any HTML page can use it without any installation.

<img src="https://lorem-pix-o5fjmzam5.now.sh/api/200/150/red" alt="placeholder"/>

Hol' up a minute !

Act V: Webservice

Any HTML page can use it ? Why not create our own page ?
We already set now to host the JS code, we can add a static HTML page along side it. More than just a landing page to present our project, we can have user inputs with live preview of the result.
Yet another file, this time of course named index.html.

<h1>Lorem pix</h1>
<form id="form">
    ...
</form>
<img src="" alt="live preview" id="preview"/>
<script src="front/live-preview.js"></script>
<script>
const form = document.getElementById("form");
const img = document.getElementById("preview");

form.addEventListener("change", () => {
    const { width, height, color } = form;
    livePreview(img, width.value, height.value, color.value);
});
</script>

I put the CSS and JS file under the front folder just for organization's sake. Here's what our script looks like.

const API_URL = "https://lorem-pix-o5fjmzam5.now.sh/api";

const livePreview = (img, width, height, color) => {
    const url = `${API_URL}/${width}/${height}/${encodeURIComponent(color)}`;
    img.src = url;
    return url;
};

Pretty straightforward!
I just used encodeURIComponent to avoid the # charactere messing with the URL.
Finally, we need tell now to serve the static files in now.json.

"builds": [
    ...
    {
        "src": "index.html",
        "use": "@now/html-minifier"
    },
    {
        "src": "/front/*",
        "use": "@now/static"
    }
]

Let's not forget to deploy again with npx now and we are live.

Conclusion

What a ride!
Being able to access the same function as a package, a CLI, an API and a front-end webservice is still incredible for me. I highly encourage everyone reading to try and do it's own. You can access the whole code-base at Github and copy/paste from here.
With a little more creativity than just making a blank image, I'm sure all of you can offer some great product. Be sure to share them in comments below.

Peace 🙏

Awesome projects under 1000 stars (3) - Lyo

Guillaume Martigny — Wed, 07 Nov 2018 10:42:15 +0000

Lyo

One of the most appreciated feature of the Javascript environment is undoubtedly the NPM huge choice of open-source packages. Easy to use, (mostly) reliable, fast, secure ... it has many big advantages under its belt.

On the other hand, one of the most hated subject, even by veteran developer is the weird dichotomy between node.js and javascript browser engines. The language offer the possibility to run the same code on back-end and front-end, but we never quite got where it works seamlessly.

Lyo aim to fill that gap. This tool could turn any node.js package into a single file browser library.
Let's walk through an example to see it running.

First, I choose a random package on NPM that I want to have on my browser. A common feature missing from Javascript is native encryption, so I choose sha1. Imagine I want to add this hashing script to a plain HTML page.

Since npx exists, I don't even have to install Lyo, I can just run:

npx lyo get sha1

From top to bottom, we can see that :

Lyo was installed in 6.5s
run over sha1 version 1.1.1
it read the file sha1.js
output a file named sha1.min.js
named the library sha1
Browserify, Babel and Uglify was successfully ran
Lyo terminated without error

Then, I can simply add the output file into my HTML page.

<script src="sha1.min.js"></script>
<script>
console.log(sha1("P@ssWord")); // => 56355fa0c17cb7f9dc0d936f6c7aa385114ee097
</script>

How easy is this !

Not easy enough ? You don't even want to open your terminal ? Lyo got you covered. Open lyo.now.sh on your favorite browser and enter the name of the package you want to compile. Lyo will take care of everything and output how you can use this package over a CDN or node.js.

On the other side of the spectrum, why not provide your user with a browser version of your node.js package ?
Of course, you might already use Browserify or Webpack, but you can now delegate all the work to Lyo.

Open your project folder, then run:

npx lyo init
npm install

Lyo will edit the package.json file to add itself as a dependency and add a script to execute it.
Now, every time you publish your work on NPM, it will be packed in a single file. This file can then be directly downloaded or through a CDN like jsDelivr or unpkg.

A few caveat, Lyo can't ensure that its output is working under the browser environment. For example, a package using the file system or any node-only capability, won't be able to run on a browser. Also, Browserify is quite opinionated on the use of ES6 features like import/export. It means you can't use any syntax not already supported by the node.js' last version.

I really love how a so complex process can be used so easily. Whether you like or not the extreme modularity of NPM, Lyo allow you to harness this power.

See you all next month.

Awesome projects under 1000 stars (2) - Gridland

Guillaume Martigny — Mon, 01 Oct 2018 11:43:52 +0000

Gridland

This month, I wanted to do thing a little differently. I mean, I never said this thread have to be serious and that's my post after all.
So this time, I present you GridLand. A very addictive and fun time waster game.

Wrapped around a simple "match 3" game, Gridland allow you to build and upgrade buildings in order to improve your abilities.
Each time you match enough squares, you earn a new resources to be spend on your camp. With enough resources, you little avatar will grow your camp.

But don't match loosely, indeed, each moves make time pass a little and when night comes ... like most games ... monsters are unleashed.
At night, your grid of resources turn into a grid of monsters and defenses.
Game-play change a bit too. The careful "match as many as day last" turn into a frantic "give me a freakin' sword instead of spawning dozens of monsters !".

Of course, if I'm showing this today, it's not just because the game is fun. It's because the whole game's code is open-sourced on github.
Like many projects, there's a huge lack in documentation 🙄. However, the code is very well formatted and architectured.
You can find (and learn from) every game development traditional parts: event-manager, game-state save, localisation, audio, entities ...
It's all basic Javascript, so even if you're not a master developer, you can understand and pick good bits from the code.

Start by playing around a little before diving into code.
First it will reduce spoilers. Then You will have an idea on how the game works and what to expect from each files.

Here some advice :

Matching more than 3 tiles has a great bonus, try to do it as much as possible
Don't use magic to turn night into day, you need that XP from fights
You can prioritize building by clicking on them

And some dev tips :

The event-manager is simple, but very useful
the gamestate.js file handle saving, which is pain to do right
Check Require.js for those strange define(['...', '...'], function(

See you all next month.

ps: The next game from DoubleSpeak studio called "a dark room" is amazing. Try it as well.

Awesome projects under 1000 stars (1) - Badgen

Guillaume Martigny — Wed, 05 Sep 2018 14:05:23 +0000

Discovering new projects is not an easy task. Thousands pops every days and a happy few become renown. This leaves a huge chunk of work forgotten by everyone, sometimes for good reasons (useless, copy-pasta, under-maintained ...) and sometimes for no reason whatsoever.

With this thread of article I aim to shine some light over an interesting project once a month.

As it's the very first post, I lay some basic rules for myself:

Any project in the web-sphere is eligible (library, tool, website ...)
Only open-source hosted on github (I want to promote OOS, but I don't have the time to parse many source)
Project under 1000 stars are considered, but the lower the better
I handpick and test every project for a while before giving any appreciation
Project should be stable, maintained and over 1 month old

I'm welcoming with great pleasure any suggestions in the comments. I'll look at them all and surely write about it if it respects the initial rules.

Without further ado, I present you

badgen and badgen-service

Yes two for the price of one !

Badgen can be used as a online service or as a javascript library.

I'm sure you've already seen a repository badge like:

Well, it's never been easier and faster to render one using badgen.

Built to be a faster alternative to shields.io, badgen deliver with awesome speed. The syntaxe to build badge is really clear and hackable. You can even use any arbitrary end-point returning a JSON formatted response.

You can check all examples on the badgen website, but here's a handful of them for a taste with corresponding URL:

Static values: /badge/dev/to/black
Github stars: /github/stars/thepracticaldev/dev.to
NPM dependents: /npm/dependents/left-pad
Code coverage: /codeclimate/coverage/thepracticaldev/dev.to

Serving a JSON with a "subject", "status" and "color" field allow you to build custom dynamic badge. Here's a stupid example loosely showing what I should be doing right now.
I create a runkit script outputing the right data. Then use this end-point in the badgen URL.

/https/untitled-ljtss6i6xow1.runkit.sh

The most awesome thing, in my opinion, is the reactivity of the main maintainer. The project is very active and you get answer to your issue or PR in a matter of hours.

Bonus points: the code is clear and well put together (even if it lack documentation) and can be a nice learning point.

Go check it out and see you all next month.

Should a library log its version number ?

Guillaume Martigny — Mon, 20 Aug 2018 15:00:33 +0000

Most libraries, log their version number (and some other data) when you import them. Sometimes, you can disable this behavior, sometimes you can't.

I don't find it awfully bothering, but I wonder what everyone think about it.

DEV Community: Guillaume Martigny

TypeScript is wasting my time

Is it null tho ?

"compact" is not "compact"

Type IDontCare

Code duplication !

Import without the extension

Dynamic interface

Conclusion

How I write web apps in 2021 ?

Content

Introduction

Disclaimer

Languages

Installation

Vue

Bundler

Optionals

Development

Adding views and components

Views

Components

Dynamic page

Fetch from API

User editing

Component libraries

Deployment

Troubleshooting

FAQ

Pencil.js quick-start

Come code with me ...

Arbitrary large integer

Problem

Solution

Do you know any social network for personal projects ?

V8.js - Access native v8 engine function from Javascript

V8.js

Install

Usage

Example

I need you !

Why the JS ecosystem is awesome !

Act I: the code

Act II: NPM

Act III: CLI

Act IV: API

Act V: Webservice

Conclusion

Awesome projects under 1000 stars (3) - Lyo

Lyo

Awesome projects under 1000 stars (2) - Gridland

Gridland

Awesome projects under 1000 stars (1) - Badgen

badgen and badgen-service

Should a library log its version number ?

Is it `null` tho ?

`"compact"` is not `"compact"`

Type `IDontCare`