I designed this blog to be more serious and formal compared to my first blog. In order to expand my reach, I decided to write articles in English. However, I still find it easier to formulate some parts of the article in Russian and then translate them into English. As a result, after each publication, there is quite a bit of material left in my workshop that could be polished a bit and published, but unfortunately, the technical capability to do so was not available until recently.

So today, I will tell you about how I upgraded my blog to support multiple languages and also share the challenges I encountered.

Theory

A minute of nerdiness, as usual.

Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes.

Localization is the process of adapting internationalized software for a specific region or language by translating text and adding locale-specific components.

In this project I did both.

Data

The development (referring to the stage when we've already moved on to writing code) of any feature in my blog starts with defining types. Whether it's component props, DTOs, or database models, all of this is described using TypeScript. This approach ensures a rather obvious effect - when something changes in one place, something else might break elsewhere, and typically, the fix is to repair it in desired way to make the feature work.

I'm developing the blog in a monorepository, which means both the api and the web-client of the service are in the same Git repository. Additionally, I have a shared module where various project-wide constants are defined (such as existing roles and now supported languages), as well as DTOs. As a result, both the controllers in the API and the data-layer in React components use the same types. I want to emphasize that the shared module is simply a directory from which what's needed is imported. It's not an NPM package or anything else; just a regular folder with TypeScript files.

I use Kysely SQL query builder for database querying. The usage looks like this:

const { id } = await pg
    .selectFrom('articles')
    .select(['id'])
    .where('slug', '=', slug)
    .executeTakeFirst();

This query will retrieve the article's id based on its slug. In my opinion, the query looks quite clear and concise, and moreover, Kysely will infer the return type (and even for more complex queries with JOIN or subqueries). Since each controller knows what type it should return to the client, the entire project, despite deploying each application separately, forms a unified system.

This case was no exception. First and foremost, to support multiple languages, I had to make significant changes to the database structure. Everything that can be localized was moved to a separate table, so in the end, each Article can have as many ArticleContent entries as needed, but there is a unique constraint for the combination of lang and article_id.

I decided not to create a separate Languages table, so the lang field is just a varchar where a two-letter language code (according to the ISO 639-1 standard) is stored. I decided not to do this because adding a language isn't as simple as just inserting a record into the database; that's quite a lot of work, including changes in a source code.

After updating the data schema, almost all controllers depending on it broke. I fixed all the errors and in some places also updated the DTOs. After updating the DTOs, errors started to appear on the client side, and those were also fixed. In fact, the multilingual articles were ready by that time. Although there was still a lot of work ahead in terms of translating the interface in this project, I'll talk about that a bit later.

Font

When I was designing this blog, I wanted it to have a clean and formal appearance, perhaps even resembling a printed publication. I tried out several fonts, and my choice fell on Libre Baskerville.

Baskerville is a serif typeface designed in the 1750s by John Baskerville (1706–1775) in Birmingham, England. Baskerville is classified as a transitional typeface, intended as a refinement of what are now called old-style typefaces of the period.

Libre Baskerville is a web font optimized for body text. It is based on American Type Founder's Baskerville 1941 but has a higher x-height, wider counters and slightly less contrast, making it well-suited for screen reading.

I really like this font, and in my subjective opinion, it suits my blog very well. However, during the design of this feature, it was discovered that Libre Baskerville doesn't support Cyrillic glyphs. This means that when attempting to render text with Russian letters, the font will fallback to a serif font (most likely Times New Roman), and it will look not very good:

Of course, this is unacceptable, so I started looking for ways to solve this problem. I tried about a dozen free fonts similar to Libre Baskerville, but my search didn't yield any success. Then I even thought about purchasing a paid version of the Baskerville font on the Paratype website, for example. I would have to pay $60 for two styles, plus there are additional complexities such as the increasing subscription cost based on pageviews, and a rather strange requirement - "May not use the font to create content by visitors to your websites." This is strange requirement because in my case, it seems like this requirement restricts the use of the font in comment forms, for example.

In general, there were quite a few questionable and unclear points, and on top of that, I would have to pay, and $60 is relatively a lot, roughly equivalent to about half a year's payment for hosting services. That's why I ruled out this option as well.

In the end, there was nothing left to do but take Libre Baskerville (it's distributed under the OFL) and add Cyrillic glyphs to it. I thought it wouldn't be too difficult, especially because some letters look the same as Latin ones and could simply be copied. In reality, it's indeed not very difficult, but it's quite a large and painstaking task. Of course, I understand that I haven't experienced creating a font from scratch. I already had ready guidelines from the authors of Libre Baskerville and even some letters for comparison. Honestly, I think I wouldn't be able to create a font entirely from scratch.

So, slowly but surely, I was drawing letter by letter. In the end, I had to draw 33 * 2 (uppercase + lowercase) * 2 (regular + bold) = 132 letters. Some letters I copied without changes, some I created from others (for example, П can easily be made from Н, and Ж from two Кs). However, some I had to draw almost from scratch (for example, Ф or Л), which explains why those letters turned out slightly more uneven than the rest. Although, to be honest, all the letters turned out a bit uneven, it's still better than falling back to Times New Roman, and overall, I was satisfied with the result.

I used Glyphr Studio, and overall, it's quite a convenient program. However, sometimes it has memory leaks and crashes, so I had to save every time after drawing each letter. Unfortunately, I had to redraw some things.

And to you, dear readers, right now, these two wonderful fonts are entirely available for free (licensed under OFL):

- BlogBaskerville-Bold.ttf

- BlogBaskerville-Regular.ttf

- License

Interface

Dealing with the interface is much simpler. I use react-intl for internationalization. In the code, I use keys, and then, based on the key and the selected language, the appropriate translation is inserted. Additionally, it supports pluralization, value substitution, and formatting for time, dates, numbers, and so on out of the box.

But I want to share my experience, which can be helpful to make work with translations simpler.

The first recommendation is to store translations alongside the component. Let's take the example of the ArticleStats component (this is a component for displaying article statistics, you might have seen it on the homepage, in the sidebar on each article page, and also in search results):

📦ArticleStats
 ┣ 📂__Icon
 ┃ ┗ 📜ArticleStats__Icon.css
 ┣ 📂__Name
 ┃ ┣ 📜ArticleStats__Name.css
 ┃ ┗ 📜ArticleStats__Name.tsx
 ┣ 📂__Stat
 ┃ ┣ 📜ArticleStats__Stat.css
 ┃ ┗ 📜ArticleStats__Stat.tsx
 ┣ 📂__Value
 ┃ ┣ 📜ArticleStats__Value.css
 ┃ ┗ 📜ArticleStats__Value.tsx
 ┣ 📂ArticleStats.helpers
 ┃ ┗ 📜capitalize.ts
 ┣ 📂ArticleStats.i18n <- directory with translations
 ┃ ┣ 📜ArticleStats.en.json
 ┃ ┗ 📜ArticleStats.ru.json
 ┣ 📜ArticleStats.css
 ┗ 📜ArticleStats.tsx

In the ArticleStats.en.json file, the keys are stored in the following format:

{
    "ArticleStats.published": "Published",
    "ArticleStats.views": "{views, plural, one {view} other {views}}",
    "ArticleStats.mins": "{mins, plural, one {min} other {mins}}"
}

As a result, all translation files for one component are stored in one place, and they can be easily compiled together using a simple Node.js script. Then, this single large file is read on the server, and all translations for all languages are loaded into memory at once. During SSR (server-side rendering), only the keys for the required language are sent to the client. I want to note that all keys are prefixed with the component's name to reduce the likelihood of collisions.

The second piece of advice I could offer is to restrict the use of anything other than string literals when specifying keys. Let me explain. To retrieve a string in react-intl, you must render the FormattedMessage element:

<FormattedMessage id="ArticleStats.published" />

or call the intl.formatMessage function:

intl.formatMessage({ id: 'ArticleStats.published' })

And sometimes I've seen examples with template strings and ternary operators, which actually make things more complicated.

For example, instead of:

<FormattedMessage id={`ArticleStats.${action}`} /> // action: 'published' | 'created' | 'updated'

Much better to write:

const actionsMap = {
    published: <FormattedMessage id="ArticleStats.published" />,
    created: <FormattedMessage id="ArticleStats.created" />,
    updated: <FormattedMessage id="ArticleStats.updated" />
};

<div>
    {actionsMap[action]}
</div>

The code becomes slightly more complex (though not significantly), but now you can search for such calls with regular expressions, not to mention querying the code through the AST (you can experiment with it here by yourself). Static code analysis in this situation is very useful because it allows you to immediately identify which keys are not being used, so you can remove them! The code becomes smaller, bundles become leaner, and there's nothing unnecessary - this is a beauty.

In fact, you can further improve the DX (developer experience) by writing a custom rule for ESLint. It may not be possible to auto-fix it, but correcting such occurrences will likely be straightforward. In most cases, complex expressions like these can be refactored into a hashmap or a switch-case. If you have just two keys, you can continue to use the ternary operator, but do it outside the message descriptor, not inside it.

Algorithm

First and foremost, we check the lang query parameter. If it exists, and its value matches one of the supported languages, then that specified language is used, and the algorithm stops. Otherwise, we look at the corresponding cookie. If the cookie exists and its value matches one of the supported languages, then the specified language is set. However, if there is no cookie (or an unknown language is specified), we will attempt to parse the Accept-Language header. If that also fails, or if none of the supported languages are specified in Accept-Language, English (en) is chosen.

After determining the language, it's set as a "sticky" choice using a cookie. Afterward, the language can only be changed explicitly by visiting a page with the lang parameter.

SEO

A search engine robot should be aware that my website supports multiple languages. When requesting a page without query parameters, GoogleBot (or another search bot) will receive the English version (it doesn't send cookies and the Accept-Language header), which means the algorithm will fallback to en.

To indicate the language of the current page, the lang attribute of the html element is used.

And for links to other pages, link elements with the rel attribute set to alternate are used. It looks like this:

<link rel="alternate" hreflang="en" href="https://vladivanov.me/"> <!-- link to self -->
<link rel="alternate" hreflang="en" href="https://vladivanov.me/?lang=en">
<link rel="alternate" hreflang="ru" href="https://vladivanov.me/?lang=ru">

Deploy

Kysely can generate migrations, but I decided to do everything myself. I manually did both the structural changes and data migration right in the production database container using psql😁. First, I created a new table, set up indexes for searching, dumped the Articles table, then deployed the new version of the service, and only after that dropped the old, unnecessary columns. It was a bit nerve-wracking, even though I think I have weekly backups from DigitalOcean. On the other hand, I've never actually tried to restore from them.

The whole feature was introduced under a feature flag, and regular users couldn't use it. After testing and creating editions in Russian for all articles in the admin office, I removed the feature flag. However, I temporarily disabled language detection based on the Accept-Language header.

Now, along with this article, the feature has started working as described. A language switch button has been added to the interface, and a little later, I will set up an email newsletter for subscribers. This is quite a significant milestone in the development history of my blog.

Conclusion

This was an extremely exciting project, considering that it covered all kinds of work. It involved development, database administration, and even design-related aspects like typography. I'm very pleased that my blog now has support of multiple languages, and I'm also happy to share this wonderful experience with you.

Please write in the comments if you're interested in how my blog works; I'm ready to tell you about any part of it.

Thank you for your attention!

If you have ever had the pleasure of developing something in JavaScript, I believe at least once in your life you have come across something like:

SyntaxError: Cannot use import statement outside a module

(if you haven't, it's still ahead of you 😉)

In particular, it can be challenging to understand what happens when the source code undergoes transpilation during the build process, and one module system transforms into another.

So today, I will talk about JavaScript/TypeScript module systems, how it happened that there are several of them, and personally, what I would recommend using in 2023.

A bit of theory

The principle of modularity allows to simplify the task of software design and distribute the development process among groups of developers.

It is the need to develop large-scale software systems that led to the emergence of modular programming, where the entire program is divided into components called modules, each with a manageable size, a clear purpose, and a well-defined interface aka API.

A module in programming is a sequence of logically related code fragments, organized as a separate part of a program. In many languages, it is encapsulated in a separate file or named continuous portion of code.

Of course, the principle of modularity did not bypass JavaScript. On the contrary, JavaScript has implemented several approaches to code organization, but let's take it step by step.

IIFE

Let's start, with IIFE, even though it is not a module system but a native language mechanism. I believe that for the sake of completeness, we need to consider it. IIFE stands for Immediately Invoked Function Expression. It is a function that is declared and immediately invoked. This technique is used for the purpose of isolation - variables declared within the body of such a function are not accessible from the outside, which helps to avoid naming conflicts and pollution of the global namespace. An example of such a function can be seen below:

;(function () {
  const a = 5;

  console.log(a) // 5
})()

console.log(a) // Uncaught ReferenceError: a is not defined

If you prefer to use JS without ;, then I recommend placing a ; before declaring the IIFE, as shown above, to prevent the expression from being interpreted as a function call. However, if you use ; consistently throughout your code, you won't encounter such issues.

By the way, an IIFE can be asynchronous, which means that the body of such a function can use the await keyword. However, this is not directly relevant to the topic of this article.

Although IIFE provides a convenient (and native) way to isolate code, it does not provide a convenient mechanism for splitting code into files. Of course, you can use as many script tags as you want on a page (if you develop frontend), but it becomes very difficult to track module dependencies on larger projects. While, from a programming perspective, as I mentioned earlier in the module definition, a module doesn't necessarily have to be a separate file, the practice shows that working with separate files is much easier. As a result, more powerful tools and approaches have emerged over time.

AMD

AMD (Asynchronous Module Definition) is a module system designed for use in the browser environment. It provides a mechanism for discovering and resolving module dependencies, enabling automatic loading and execution of modules in the correct order.

AMD was born out of a group of developers that were displeased with the direction adopted by CommonJS. In fact, AMD was split from CommonJS early in its development.

One of the key features of AMD is its ability to load modules asynchronously. When a module is requested for loading, the AMD loader asynchronously loads the module's dependencies, ensuring the proper loading order.

Here's an example of how it can be used:

define('sounds', 
  ['dog', 'audio'], 
  function (dog, audio) {
    return {
      bark: function() {
        return audio.play(dog.getVoice());
      }
    }
  };
});

Here, we are implementing the sounds module and explicitly stating its dependencies. One of the most popular tools that implements AMD is RequireJS. Here’s an example of how it can be used from official documentation:

requirejs(
  ['helper/util'],
  function(util) {
    // This function is called when scripts/helper/util.js is loaded.
    // If util.js calls define(), then this function is not fired until
    // util's dependencies have loaded, and the util argument will hold
    // the module value for "helper/util".
  }
);

CommonJS (CJS)

While AMD was used in browser environments, another module system called CommonJS was used in Node.js environments. The main difference between AMD and CommonJS lies in its support for asynchronous module loading.

While AMD is somewhat difficult to come across nowadays, CommonJS is literally everywhere. It's important to note that CommonJS is still the default module system in Node.js.

Here's an example code using CommonJS:

const fs = require('fs');
const dog = require('./dog');

module.exports = {
  barkToFile: function () {
    fs.writeFileSync('./bark.txt', dog.voiceToString());
  }
};

To import modules in CommonJS, the require function is used. It takes the path (and extension may be omitted) to the module or module name and returns the exported values of that module.

Any properties added to exports or assigned to module.exports become the exported values of the module.

In CommonJS, modules are loaded synchronously and resolved at runtime. When a module is initially loaded, its code is executed, and its exported values become available for import in other modules.

In the browser, there is no built-in require function or access to the file system, so CommonJS is not supported. However, a similar API can be achieved using the AMD approach and the RequireJS library:

define(
  function(require, exports) {
    const dog = require("dog");

    exports.barkToConsole = function() {
      console.log(dog.voiceToString());
    }
  }
);

ES Modules (ESM)

And here we finally come to the first module system described in the ECMAScript standard. ES modules were introduced with ES6 in 2015. And yes, you understood it correctly, for 20 years there was no standardized module system in JavaScript. Over time, the standard has evolved and I believe you are also familiar with this syntax:

import api from 'api.js';
import dog from './dog.js';

export function makeBarkRequest () {
  api.post('/bark', (err) => {
    if (err) return;

    dog.bark();
  });
}

Despite being standardized, ES modules are disabled by default. In a Node.js environment, you need to set type to 'module' in your package.json or use the .mjs file extension. In browser environments, to use ESM syntax within a script tag, you need to set the type attribute to 'module'. Support for ES modules first appeared in Node.js 12 under the --experimental-modules flag. In later versions, ES modules were came out from the flag.

That concludes the discussion of module systems, but there are a couple more approaches that are important to look at.

UMD

UMD (Universal Module Definition) is a template or approach for creating modules that can work in both CommonJS and AMD environments, as well as be accessible as global variables if no module loader is present.

The main idea behind UMD is to create a module that can automatically adapt to different runtime environments and module loaders.

UMD uses conditional constructs to determine which existing module system is available and selects the appropriate method for exporting and importing the module. In many cases, it uses AMD as a base and adds special handling to ensure compatibility with CommonJS.

Here's an example of how it typically looks:

(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD env
    define(['dependency'], factory);
  } else if (typeof exports === 'object') {
    // CommonJS env
    module.exports = factory(require('dependency'));
  } else {
    // global
    root.ModuleName = factory(root.Dependency);
  }
}(this, function (dependency) {
  // module logic
  return {
    // exports
  };
}));

If the runtime environment supports AMD (checked using define), the module is defined using define and the dependencies are specified for the module loader.

If the runtime environment supports CommonJS (checked using exports), the module is exported using module.exports and the dependencies are resolved through require.

If none of the checks pass, it is assumed that the module is running in a global environment, and it is exported by assigning its property to the global object (root), which represents the global namespace in this case.

UMD allows developers to create modules that can be used in different runtime environments, providing maximum flexibility and code portability.

SystemJS

SystemJS is a universal JavaScript module loader designed for use in the browser and Node.js runtime. It is designed to support and load various module formats, including AMD, CommonJS, UMD, and ESM, allowing developers to use different module formats within a single project.

Here's an example of how it looks:

System.import('dog.js').then(function(module) {
  console.log(module.bark());
}).catch(function(error) {
  console.error('Failed to load module:', error);
});

And keep in mind that the 'dog.js' module can be written in ANY of the formats mentioned above. However, I would say that if you find yourself needing to use different module systems within a single project, there might be something wrong with your project.

In real life, you are unlikely to deal with AMD, UMD, or SystemJS. ESM and CJS, on the other hand, are widely used, and you will encounter them regardless of the environment you're developing in.

Bundlers and traspilers

In fact, module systems are not something complicated. I believe it won't be difficult to determine the approach being used by examining the source code. However, in real-world development, the code we write doesn't go into production as-is. On the backend, a transpiler is usually sufficient. The most common scenario is transpiling TypeScript code to JavaScript (of course, there are other solutions like ts-node or deno, but that's a topic for another article). On the frontend, things are even more complex - the code goes through not only a transpiler but also various tools called bundlers, minifiers, and so on.

Transpilers (for example, tsc) have the ability to generate code using various module systems. tsc supports generating code into all of module systems we've looked at: ESM, CJS, AMD, UMD and SystemJS. And here you can play with the tsc transpiler by yourself!

Let's see how it works. For example, here's the code:

import dog from './dog';
import audio from './audio';

export const bark = () => {
  audio.play(dog.bark())
}

It will not change if you build it with tsc with the option module set to 'esnext' , but if you build the code with the same tool but with the module option set to 'commonjs' , the code will look like this:

"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.bark = void 0;
const dog_1 = __importDefault(require("./dog"));
const audio_1 = __importDefault(require("./audio"));
const bark = () => {
    audio_1.default.play(dog_1.default.bark());
};
exports.bark = bark;

If we delve into what's happening here and remove the generated helpers, we can notice that the code we wrote using ESM has been transformed into code using CJS, and this is the root cause of all the errors!

This is where the confusion arises. Since you are using ESM in your source files, it seems logical to set the type to 'module' in package.json. But it's not that simple. In reality, Node.js will run the already compiled tsc code, which, as we have seen, does not use ESM, and you will encounter the error:

ReferenceError: require is not defined

The reverse situation is also possible. For example, if we build the code and it still contains ESM syntax, but we haven't set the type to 'module' in package.json, we will get the error mentioned at the beginning of the article:

SyntaxError: Cannot use import statement outside a module

All of this is further complicated by the fact that some packages are discontinuing support for CJS. One such package is chalk. Starting from major version 5, they stopped supporting CJS, and if you try to use require, you will encounter the error:

Error [ERR_REQUIRE_ESM]: require() of ES Module

Now, imagine a situation where you have TypeScript code:

import chalk from 'chalk'; // >= 5
import dog from './dog';

export const colorfulBark = () => {
  console.log(chalk.green(dog.barkToString()));
}

And you decided to build it with tsc with module option set to 'commonjs'. You will get this code:

"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.colorfulBark = void 0;
const chalk_1 = __importDefault(require("chalk")); // <-- require('chalk')
const dog_1 = __importDefault(require("./dog"));
const colorfulBark = () => {
    console.log(chalk_1.default.green(dog_1.default.barkToString()));
};
exports.colorfulBark = colorfulBark;

And when you attempt to run it, you encounter the error

Error [ERR_REQUIRE_ESM]: require() of ES Module

indicating that one of our modules (in this case, chalk) does not support CJS. This can be quite confusing because we don't have any require statements in our source code! It becomes particularly challenging to troubleshoot in a large project when examining the already bundled code.

In this case, there are two options:

1. Set type to 'module', which would also require setting module to 'esnext' in the tsconfig (and possibly break other things 😁).
2. Downgrade chalk to version 4.1.2, which is the latest version in the 4.x major release that still supports CJS. This means that the module confusion forces you to use older package versions, which is not ideal, of course.

I also want to note that setting type to 'module' is a very significant project-wide configuration that affects everything, so changing it is usually extremely difficult. For example, if you are using Jest with type set to 'module' and then suddenly decide to switch to commonjs for some reason, your top-level await in test files will stop working.

So, what should I do?

I can't give recommendations on already existing projects, because, as I said, changing the type field is usually very difficult and each case needs to be analyzed separately. Of course, it will be better if you can upgrade to ESM.

As for new projects, I would recommend starting them with type set to 'module'. This syntax is standard and modern. More and more public packages are dropping support for CJS. Additionally, type set to 'module' provides additional features like top-level await.

Of course, there is a caveat. A file extension must be provided when using the import keyword to resolve relative or absolute specifiers. Directory indexes (for example, ./startup/index.js) must also be fully specified. This can be a problem if you're using tsc because TypeScript doesn't modify import paths during transpilation. This issue can be resolved using a special tooling or simply by using the .js extension in imports. TypeScript will still understand that it refers to an appropriate TypeScript file (.ts), and after transpilation, the code will have a valid path. By the way, my IDE (VSCode) was even able to correctly suggest the path with the .js extension. And code navigation also works correctly.

As an alternative for TypeScript projects, you can consider using ts-node, but it needs to be run with the --transpile-only flag. Of course, you need to remember that ts-node is a different runtime from the standard Node.js, and it has its own interesting nuances.

Another solution to this problem could be bare specifiers combined with moduleResolution set to 'nodenext'. However, you'll also need to solve the issue of copying package.json files to the build folder and it’s important to preserve the directory structure.

Or you can just customize ESM specifier resolution algorithm with loaders API to make modules resolvable without extensions like CJS. But this feature is experimental (Node.js 20).

Nevertheless, for new JavaScript projects, I would still recommend using type set to 'module'. In the case of TypeScript, it's not as straightforward as we saw above, but I would still recommend using ESM and specifying the .js extension. Yes, it may seem a bit strange, but it's the best solution among the available options in my opinion.

We discussed the usage of module systems in Node.js environments. But what about browser environments? Usually, in browser environments, these issues don't arise because different tools like webpack are used, which inherently support both ESM syntax and CJS. The output is typically a bundle where all the code is simply concatenated into one file, eliminating the need for module systems (and thus avoiding related problems). webpack also provides a solution for splitting applications into files (chunks) for on-demand asynchronous loading, which is also similar to the of module system, but that's a topic for another article.

When it comes to newer tools like vite, it is built on ESM and uses script tags in the browser with the attribute type set to 'module'. vite’s performance is based on ESM. As far as I know, there are no alternatives to this approach, so there is no need to make a choice.

Conclusion

While writing this article, I came across numerous other articles on the topic of comparing module systems in JavaScript. However, all of these articles only scratch the surface in terms of examining the differences and similarities of these systems. In contrast, I made an effort to not only explore the module systems but also address the common challenges developers face and even proposed a few solutions. I hope you find this information useful in your projects.

Thank you for your attention, and see you next time!

References

1. Modular programming, viewed 19 Jun 2023, https://en.wikipedia.org/wiki/Modular_programming
2. IIFE, viewed 19 Jun 2023, https://developer.mozilla.org/en-US/docs/Glossary/IIFE
3. RequireJS, viewed 19 Jun 2023, https://requirejs.org/
4. ESM, viewed 19 Jun 2023, https://nodejs.org/docs/latest-v18.x/api/esm.html
5. UMD, viewed 19 Jun 2023, https://github.com/umdjs/umd
6. AMD, viewed 19 Jun 2023, https://en.wikipedia.org/wiki/Asynchronous_module_definition

QR code is a very cool thing. But what if I told you that you can also play them. Interesting? Then let's go!

Today I'm gonna talk about how I wrote a Flappy Bird web game and put it in a QR code. The task is not as simple as it seems at first glance. As a challenge, I want the whole game to be contained inside the QR code and in order to play user only need the QR code. That is, the option with a link to the game inside the QR code is not suitable for me. It is not interesting!

Most often, when you scan a QR code, the data from the decoder gets into the search bar of your default browser. Of course, there are other use cases, but for my game, this scenario seems to be the most suitable. So, the goal is to run the source code of my game from the browser search bar. But is it possible? Yes, it can be implemented with data URLs. You can test this feature by simply taking any valid HTML code, encode it in base64, prefix it with data:text/html;base64, and paste the resulting string into the browser search bar.

To reach my goal, I just need to encode the string obtained using the algorithm described above into a QR code. It sounds quite simple, but there is one not very pleasant circumstance here: it's impossible to encode an infinite amount of data into a QR code.

Limitations

According to the specification, there are 40 QR code versions (1 - 40). Each version has its own configuration and number of dots (modules) that make up the QR code. Version 1 contains 21x21 modules, version 40 has 177x177. From version to version, the size of the code increases by 4 modules per side.

Each version corresponds to a certain capacity. It's easy to guess that the more information that needs to be encoded, the higher version of the code is needed.

QR codes support several encoding modes:

Also, QR codes have a special mechanism for increasing the reliability of storing encrypted information. For codes created with the highest level of reliability, up to 30% of the surface can be damaged or overwritten, but they will retain information and be correctly read. The Reed-Solomon algorithm is used to correct errors.

The table below shows the maximum number of storable characters in each encoding mode and for each error correction level.

The base64 alphabet contains 64 characters and is divided into groups:

• Uppercase letters (indices 0-25): A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z
• Lowercase letters (indices 26-51): a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
• Digits (indices 52-61): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
• Special symbols (indices 62-63): +, /

In addition to these characters, the equal sign (=) is used for padding.

The appropriate encoding mode for base64 encoded data is byte. As for the error correction level, I think the M level will be enough, so I can expect to be able to encode 2331 characters, which is a little over 2 kilobytes. However, it should be noted that the base64 encoded string is about 30% longer than the source one.

Tools

For the more efficient development, it's necessary to optimize the process of generating a QR code. Also, it's necessary to perform some preprocessing of the source HTML code, namely minification, since I have a strict size limit.

For these purposes, a special NodeJS script was written:

import { minify } from 'html-minifier';
import { readFileSync, writeFileSync } from 'fs';
import { resolve, join } from 'path';
import { toFile } from 'qrcode';
import { execSync } from 'child_process';
import { fileURLToPath } from 'url';

const kb = (bytes) => (bytes / 1024).toFixed(2);

const __dirname = fileURLToPath(new URL('.', import.meta.url));

const input = readFileSync(resolve(__dirname, '../index.html'), { encoding: 'utf-8' });

console.log('Original size is', kb(input.length), 'KB', `(${input.length} bytes)`);

const minified = minify(input, {
  collapseWhitespace: true,
  minifyCSS: true,
  minifyJS: {
    mangle: {
      // variables declared at the top level 
      // are not minified by default
      toplevel: true
    }
  }
});

console.log('Minified size is', kb(minified.length), 'KB', `(${minified.length} bytes)`);

const outDir = resolve(__dirname, '../output');

execSync(`mkdir -p ${outDir}`);
writeFileSync(join(outDir, 'index.min.html'), minified);

const b64 = Buffer.from(minified).toString('base64');
const output = `data:text/html;base64,${b64}`;

console.log('b64 size is', kb(output.length), 'KB', `(${output.length} bytes)`);

writeFileSync(join(outDir, 'b64.txt'), output);
toFile(
  join(outDir, 'image.png'), 
  [{ data: output, mode: 'byte' }], // encoding mode
  { errorCorrectionLevel: 'm' } // errors correction level
);

console.log('Done!');

Thus, after running the script, I have a ready-to-use QR code at the output, as well as detailed information by code size, which will help me in further optimization.

Development

First, let's create a minimal valid HTML document:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Flappy bird</title>
  </head>
  <body>
  </body>
</html>

I would like the game to have textures as similar to the original ones as possible. However, the game shouldn't depend on external resources, which means that there is no possibility to download any extras (images, styles, etc). So, I will have to program texture drawing. There are many ways to draw on the web: box-shadows, various gradients, SVGs, canvas, etc. I decided to choose canvas, because it's pretty easy to draw pixel by pixel and it's shorter in code than css or multiple divs:

...
  <body>
    <canvas id="c" width="360" height="640"></canvas>
  </body>
...

I created a DOM node and set id attribute. Now, in code, I can simply refer to it as window.c or just c and there is no need to use methods to find DOM elements in the document like querySelector or getElementById, whose names are actually quite long and cannot be minified. By the way, I would like to draw your attention to this. When using canvas, various methods of CanvasRenderingContext2D are used and it makes sense to assign these methods to variables, because minifier cannot minify the properties (and methods) of an object. But it must be remembered that to assign it's needed to call bind method to pass this context, which in this case is canvas rendering context. Here's what I'm talking about:

let ctx = c.getContext('2d');

ctx.fillRect(...)
ctx.fillRect(...)
ctx.fillRect(...)

After minification, it will turn into something like this (whitespace characters are retained for clarity):

let a = c.getContext('2d');

a.fillRect(...)
a.fillRect(...)
a.fillRect(...)

While this code:

let ctx = c.getContext('2d');

let fillRect = ctx.fillRect.bind(ctx);

fillRect(...)
fillRect(...)
fillRect(...)

Turns into something like this:

let a = c.getContext('2d'), b = a.fillRect.bind(a);

b(...)
b(...)
b(...)

Profit from such an assignment will be, but not always. For each individual case, it's needed to count the lengths of the strings. For example, for the fillRect method, such an assignment is useful if this function is called more than 2 times.

Of course, there are other ways to assign a function, for example:

let fillRect = (...args) => ctx.fillRect(...args);

But this option will be longer after minification compared to the code where bind is used. Therefore, I decided to use the code with bind, since I could not find an option that would be shorter.

By the way, let is used everywhere in the code, because it is 2 characters shorter than const.

Textures

I've already said that I would like to use textures as close to the original as possible for my game. For example, I would like to see such a bird in the game:

At the same time, there is no way to request pictures from anywhere, so I assumed that the easiest way would be to store images in string variables right in the source code. But how to fit pictures into 2 kilobytes, given that there is also a game logic code?

You can see that in order to draw the texture above, it's only needed 5 colors. While popular image formats such as JPEG or PNG allow millions of colors to be encoded, this is achieved by a fairly high color bit depth. For example, JPEG color images store 24 bits per pixel, and PNG up to 48 bits. 

I do not need such a color depth, which means that I can solve this problem by developing my own palette. Let's imagine that a letter of the Latin alphabet has been assigned to each color, then the image above will look like this:

uuuuuuaaaaaauuuuu
uuuuaacccabbauuuu
uuuaccccabbbbauuu
uuacccccabbbabauu
uaccccccabbbabauu
uaaaaacccabbbbauu
adddddacccaaaaaau
adddddaccaeeeeeea
uaaaaaccaeaaaaaau
uuaccccccaeeeeeau
uuuaacccccaaaaauu
uuuuuaaaaauuuuuuu

legend:
u - transparent
a - #000
b - #fff
c - #f71
d - #eec
e - #f20

The size of such a picture is 204 bytes. However, just looking at this picture shows a huge potential for compression! The first thing that comes to mind is RLE. Simply put, algorithm replaces repeated characters with a character + number of repetitions: `aaaaa` → `a5`. In the case of the sequence above, the compression works quite efficiently - 32.35%. The disadvantage of this approach is that for non-repeating sequences, the algorithm works the other way: `abcde` → `a1b1c1d1e1`, although this can be optimized: `abcdeeeee` → `-4abcd5e` or `abcdeee` → `abcd3e`.

Let's look at another way. I assumed that there would be no more than 16 colors in the palette, then I can achieve 50% compression for ANY data set without much effort. Each character must be assigned a code. And in the resulting string, write not the character itself, but the result of the expression:

char((code(color1) << 4) | code(color2))
// char - getting char by its code; code - getting code by char

Then in 8 bits I will store information about 2 pixels. But there is one caveat. Symbol codes must be offset by 2 (i.e. start at 0b10). Why? In the ASCII character table, control characters go up to code 32 (32 is space character). I haven't found a way to print them on a Mac, and I'm also not sure if they can be used in a JavaScript code. Most likely, it's possible, but escaping is required. In general, to solve this problem, it's enough to add an offset of 2, and then the result of the code function will always be a number greater than 32, and hence the printable character.

As a result, using the first algorithm (RLE with single character optimization), I got:

u6a6u9a2c3ab2au7ac4ab4au5ac5ab3abau3ac6ab3abau3a5c3ab4au2ad5ac3a6uad5ac2ae6aua5c2aea6u3ac6ae5au4a2c5a5u7a5u7

And as a result of the second:

ÌÌÌ333ÌÌÌÌÃ5U4CÌÌÌÃUU4DCÌÌÃUUSDCCÌÃUUU4D4<Ì335U4DCÌ6ff5U333ÃffcU7wwsÃ33U7333ÌÃUUU7ww<ÌÃ5UU33<ÌÌÌ33<ÌÌÌ

And the difference was only 6 bytes. Of course, I can still try to encode the result of the second algorithm with RLE, but next I have to decode all of this with the script code, which also takes some space, and I decided that RLE suits me perfectly.

By the way, one could try to encode the source string with the Huffman algorithm, and even calculate the Huffman tree in advance, but in this case it's rather difficult to control the non-appearance of control non-printable characters, and the decoder implementation code is quite cumbersome compared to the RLE decoder code or bit sequences.

Thus, textures have been created:

let birdTexture = `a6u8a2c3ab2au6ac4ab4au4ac5ab3abau2ac6ab3abau2ac7ab4au2ac8a6uac7ad6auac5ada6u2ac6ad5au3a2c5a5u6a5`;
let wing1Texture = `a4u2ae4auae5a2e5auae3au3a3`;
let wing2Texture = `a5uae5a2e5aua5u`;
let wing3Texture = `a5uae5a2e4auae3au3a4`;
let pipeTexture = 'g6h4g4h9h3g4h4g9g4f9f3';
let widePipeTexture = 'g3' + pipeTexture + 'f3';

After minification, the size of this code will be about 220 bytes, which is quite acceptable.

But for now, these are just variables of type string. To turn them into images on screen, It's needed to do certain actions:

let draw = (t, x, y, w, i = 0, pw = 2, ph = 2) => {
  while (t.length) {
    let c = t[0], times = +t[1]; 
    // I hope that there are no more than 9 repetitions
    // but if even more, then I just write a5a5 instead of a10
    fillStyle(c);
    t = t.slice(times !== times ? 1 : 2);

    if (c === 'u') i += (times || 1);
    else for (let until = (times || 1) + i; i < until; i++) fillRect(x + (i % w) * pw, y + ((i / w) | 0) * pw, pw, ph);
  }
}

So what's going on here? The function takes the texture (one of those strings that we discussed above) as the first argument. Next come the x and y coordinates - this is the drawing offset relative to the upper left corner of the canvas. Since the texture is represented by a string, it's needed to specify w (width), this sets the amount of pixels to be drawn before moving to the "next line". The i argument is used for the purpose of optimization - if the texture starts with empty pixels 'u', then they can be omitted, and the i counter value is started from the number of such pixels. It's like getting rid of trailing zeros in a number. pw, py - pixel width and height, respectively. Since most of the pipe looks like this:

I can call draw just once and specify ph = height of the pipe, instead of N draw calls, where N is the height of the pipe in pixels / ph. Made for performance.

Code

The whole game (like any other AFAIK) will be in an infinite loop:

let tick = 0;

let setup = () => {
  vSpeed = flyUpSpeed; // at the moment the game starts, the bird flies up
  score = playing = 0;
  y = 308; // place the bird vertically in the center
  pipes = [[100, gate()], [788, gate()]]; 
  // initialize the first two pipes,
  // more about pipes above
}

let render = () => {
  ...

  tick++;
  requestAnimationFrame(render);
}

setup();
render();

The first step, of course, is to draw the background. I just fill it with #0ac color. Next comes the drawing of pipes:

pipes.map(pipe => {
  pipe[0] -= hSpeed; // move pipes to the left every render

  let [px, py] = pipe;

  draw('a2' + pipeTexture + 'a2', px, 0, 64, 0, 1, height);
  fillStyle('a');
  fillRect(px - 3, py - 32, 69, 284);
  draw(widePipeTexture, px - 1, py - 30, 66, 0, 1, 28);
  draw(widePipeTexture, px - 1, py + 222, 66, 0, 1, 28);
  fillStyle('i');
  fillRect(px - 3, py, 69, 220);

  ...
})

The memory contains information about only two pipes, because it simply won't fit on the screen anymore. The game is designed so that when the pipe with index = 0 goes off the screen, it is removed, and the player gets a point:

if (px < -64) {
  score++;
  bestScore = score > bestScore ? score : bestScore; // ternary operator is shorter than Math.max
  pipes = [...pipes.slice(1), [pipes[1][0] + 284, gate()]];
}

An information about pipes is stored as an array of [x, y] tuples, where x is the distance from the left edge of the canvas to the beginning of the pipe, y is the distance from the top of the screen to the end of the top pipe (then comes gap, and then the bottom pipe starts). The y for each pipe is generated at the time of creation by the gate function:

let gate = () => (Math.random() * 292 + 64) | 0;

The distances are calculated in such a way that the player cannot crash into a pipe with an index other than 0, so the collision check is carried out for only one pipe (index = 0):

let [[px, py]] = pipes; // take coordinates of pipe with index = 0

if ((px < 198 && px > 98 && (y < py || py + 188 < y)) || (y < 0 || y > 616)) {
  // game over
  setup();
}

By the way, as you have already noticed, all the constants are calculated in advance, because this way the code takes up less space.

After the pipes, a bird is drawn. It always has the same x, but y changes every render:

let gravityAcceleration = .5;
let flyUpSpeed = -12;

vSpeed += gravityAcceleration;
y += vSpeed;

...

draw(birdTexture, 164, y, 16, 5);

// draw animated wings above the bird
let wingsPhase = ((tick / 4) | 0) % 4;

wingsPhase % 2 
  ? draw(wing2Texture, 162, y + 10, 7, 1) 
  : !wingsPhase
  ? draw(wing1Texture, 162, y + 6, 7, 1) 
  : draw(wing3Texture, 162, y + 12, 7, 1);

...

c.onclick = () => { 
  // fly up on click
  vSpeed = flyUpSpeed;
}

Lastly, text is drawn to tell the player what he is playing at all, how many points he has scored and show the game over screen:

fillStyle('b');
fillText(`Score: ${score} | Best: ${bestScore}`, 26);

if (!playing) {          
  fillText(played ? 'Game over' : 'Flappy bird', 210, 32);
  fillText('Click to play' + (played ? ' again' : ''), 430);

  !played && fillText('QR code edition', 230, 12, 246);
}

I showed you almost all the code, however, I still omitted some things, but you can find the full code of the project and even play around on the GitHub project page.

Building

After code is completed, I can start building. Thanks to the fact that I took care of the tools in advance, now I only need to run:

npm i && npm run build

The script itself will create the output folder and put the result there, namely:

1. Minified HTML;
2. Data URL;
3. QR code PNG image.

Also script prints size details:

Original size is 3.82 KB (3907 bytes)
Minified size is 1.53 KB (1569 bytes)
b64 size is 2.06 KB (2114 bytes)
Done!

And you can scan the QR code right now:

or copy+paste the data URL into your browser search bar:

data:text/html;base64,PGh0bWw+PGhlYWQ+PHRpdGxlPkZsYXBweSBCaXJkPC90aXRsZT48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLGluaXRpYWwtc2NhbGU9MSxtYXhpbXVtLXNjYWxlPTEsdXNlci1zY2FsYWJsZT0wIj48L2hlYWQ+PGJvZHkgc3R5bGU9ImJhY2tncm91bmQ6IzAwMCI+PGNhbnZhcyBzdHlsZT0iaGVpZ2h0Ojk2JTtwb3NpdGlvbjpmaXhlZDt0b3A6NTAlO2xlZnQ6NTAlO3RyYW5zZm9ybTp0cmFuc2xhdGUzZCgtNTAlLC01MCUsMCkiIGlkPSJjIiB3aWR0aD0iMzYwIiBoZWlnaHQ9IjY0MCI+PC9jYW52YXM+PHNjcmlwdD5sZXQgaT1jLmdldENvbnRleHQoIjJkIiksdT0oaS50ZXh0QWxpZ249ImNlbnRlciIsYy5oZWlnaHQpLGU9e2E6IjAwMCIsYjoiZmZmIixjOiJmNzEiLGQ6ImYyMCIsZToiZWVjIixmOiIxNzAiLGc6IjFhMCIsaDoiMWQwIixpOiIwYWMifSxnPWkuZmlsbFJlY3QuYmluZChpKSx0PShhLGUsYz0xNix1PTE4MCk9PntpLmZvbnQ9YysicHggY291cmllciIsaS5maWxsVGV4dChhLHUsZSl9LG49YT0+aS5maWxsU3R5bGU9IiMiK2VbYV0sbD0iYTZ1OGEyYzNhYjJhdTZhYzRhYjRhdTRhYzVhYjNhYmF1MmFjNmFiM2FiYXUyYWM3YWI0YXUyYWM4YTZ1YWM3YWQ2YXVhYzVhZGE2dTJhYzZhZDVhdTNhMmM1YTV1NmE1IixmPSJhNHUyYWU0YXVhZTVhMmU1YXVhZTNhdTNhMyIscj0iYTV1YWU1YTJlNWF1YTV1IixvPSJhNXVhZTVhMmU0YXVhZTNhdTNhNCIsYj0iZzZoNGc0aDloM2c0aDRnOWc0ZjlmMyIsZD0iZzMiK2IrImYzIixoLG0scCxzLHYseD0wLHk9MCxrPTQsQT0uNSxhPS0xMixDPTAsRj0oKT0+MjkyKk1hdGgucmFuZG9tKCkrNjR8MCxSPShhLGUsYyx1LGk9MCx0PTIsbD0yKT0+e2Zvcig7YS5sZW5ndGg7KXt2YXIgZj1hWzBdLHI9K2FbMV07aWYobihmKSxhPWEuc2xpY2UociE9cj8xOjIpLCJ1Ij09PWYpaSs9cnx8MTtlbHNlIGZvcih2YXIgbz0ocnx8MSkraTtpPG87aSsrKWcoZStpJXUqdCxjKyhpL3V8MCkqdCx0LGwpfX0sUz0oKT0+e209YSxwPXY9MCxoPTMwOCxzPVtbNTA0LEYoKV0sWzc4OCxGKCldXX0scT0oKT0+e24oImkiKSxnKDAsMCwzNjAsNjQwKSx2JiYobSs9QSxoKz1tLHMubWFwKGE9PnthWzBdLT1rO3ZhclthLGVdPWE7UigiYTIiK2IrImEyIixhLDAsNjQsMCwxLHUpLG4oImEiKSxnKGEtMyxlLTMyLDY5LDI4NCksUihkLGEtMSxlLTMwLDY2LDAsMSwyOCksUihkLGEtMSxlKzIyMiw2NiwwLDEsMjgpLG4oImkiKSxnKGEtMyxlLDY5LDIyMCksYTwtNjQmJihwKyssQz1wPkM/cDpDLHM9Wy4uLnMuc2xpY2UoMSksW3NbMV1bMF0rMjg0LEYoKV1dKX0pLFtbZSxhXV09cyxlPDE5OCYmOTg8ZSYmKGg8YXx8YSsxODg8aCl8fGg8MHx8NjE2PGgpJiZTKCksUihsLDE2NCxoLDE2LDUpO3ZhciBhLGU9KHkvNHwwKSU0O2UlMj9SKHIsMTYyLGgrMTAsNywxKTplP1IobywxNjIsaCsxMiw3LDEpOlIoZiwxNjIsaCs2LDcsMSksbigiYiIpLHQoYFNjb3JlOiAke3B9IHwgQmVzdDogYCtDLDI2KSx2fHwodCh4PyJHYW1lIG92ZXIiOiJGbGFwcHkgYmlyZCIsMjEwLDMyKSx0KCJDbGljayB0byBwbGF5IisoeD8iIGFnYWluIjoiIiksNDMwKSx4KXx8dCgiUVIgY29kZSBlZGl0aW9uIiwyMzAsMTIsMjQ2KSx5KysscmVxdWVzdEFuaW1hdGlvbkZyYW1lKHEpfTtTKCkscSgpLGMub25jbGljaz0oKT0+e209YSx2PXg9MX08L3NjcmlwdD48L2JvZHk+PC9odG1sPg==

And play Flappy Bird QR code edititon! And the coolest thing is that the game does not need anything other than a QR code (well, device with a browser, of course).

And here's a screenshot of the resulting game. However, I recommend you to play, it's funny!

Thank you for reading!

⚠️ Alas, the standard iPhone camera does not understand the data URLs. It recognizes the QR code but says "no usable data found". I managed to recognize the code with the first application from the App Store, but in general there should be no problems with any other application.

🤓 At the very beginning, I told you about the versions of QR codes. So, resulting QR code version is 39.

References

1. qrcode, viewed 12 Jan 2023 <https://www.npmjs.com/package/qrcode>
2. QR Code Specification, viewed 12 Jan 2023, <https://www.labeljoy.com/qr-code/qr-code-specification/>
3. QR code, viewed 12 Jan 2023, <https://en.wikipedia.org/wiki/QR_code>
4. Data URLS, MDN, viewed 12 Jan 2023, <https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs>
5. Base64 Characters, viewed 12 Jan 2023, <https://base64.guru/learn/base64-characters> 

Hello! If you are a web developer or have ever had the pleasure of writing a frontend, you must know what CSS is. If you've ever written a front-end for a fairly large web service, you've probably come across the fact that when you open a file with styles which were written a year ago, you can't understand anything at all!

Understanding large CSS files is quite challenging. And different preprocessors do not improve the development experience, but rather make it more difficult. I highly recommend not using preprocessors in 2022. CSS has a lot of power and in my opinion preprocessors are not worth the build time added and the cognitive complexity added by the SASS/SCSS/etc syntax. The problem with large CSS files cannot be solved in any way except for adequate code separation.

Another common problem with CSS is the fact that sometimes it is very difficult to tell from the name of the class about appearance and meaning of the element to which it will be applied. 

And BEM methodology was once invented to solve both problems. I know that many people consider it obsolete and, to be honest, six months ago I thought the same way. However, you just need to understand the essence and you will immediately change your mind! BEM is not about naming, as it might seem, it is about the logic of splitting the interface into component parts, called BEM entities.

And actually if you follow the BEM methodology and some convention about splitting source code files, you can come to a utopian world of the future, where there are styles for ONE element in ONE file, and when reading the code, there is no reaction like this:

But what if we go further and consolidate such conventions not in words and in linters, but in the very essence of writing styles? That is what I propose to talk about today.

Main idea

You probably know what css-loader is and how it allows you to work with CSS modules. If this is not the case, then let me remind you what it is using the example of a React component:

import styles from './Button.css';

export const Button = ({ children }) => {
  return <button type="button" className={styles.Button}>{children}</button>;
}

Convenient, isn't it?

If the development is carried out using the BEM methodology, then it may look something like this:

import cls from 'classnames';
import styles from './Button.css';

// type: primary | secondary

export const Button = ({ children, type }) => {
  return (
    <button 
      type="button" 
      className={cls(styles.Button, {
        [styles.Button_type_primary]: type === 'primary',
        [styles.Button_type_secondary]: type === 'secondary'
      })}
    >
      {children}
    </button>
  );
}

In BEM, such entities are called modifiers. Usually, they are used to give a certain look to an element. In the example above, the button could change color depending on its type.

Also, it is not difficult to guess that in order to work with modifiers, we need some kind of auxiliary tool so as not to manually concatenate classnames. In the example above, the classnames NPM package serves as such a tool. Pay attention to popularity - 11M downloads/week.

Wait! But after all, if we have specific naming rules, can't we ourselves write a function by analogy with cls, which could include certain modifiers, depending on the options passed, but with a more convenient API for our case. Let's try:

import styles from './Button.css';

const cls = (base, mods) => {
  let names = Object.entries(mods).map(([modName, modVal]) => {
    return `${base}_${modName}_${modVal}`;
  });

  return names.concat([base]).join(' ');
}

// type: primary | secondary

export const Button = ({ children, type }) => {
  return (
    <button 
      type="button" 
      className={cls(styles.Button, { type })}
    >
      {children}
    </button>
  );
}

It looks cool! But it is inconvenient that you need to carry the cls function around with you. In addition, it is very difficult to foresee all scenarios for the use of such a function. For example, if the BEM modifier is boolean, then the value of the true modifier can be omitted and just a name can be used, such as 'Button_disabled'.

Well, meet!

Implementation

To get started, just watch a small demo:

In a nutshell, everything that I wrote about above is merged together, and TypeScript support has also been added.

All this is called functional BEM and you can learn more about the project here. All @fbem packages are open-source projects and distributed under the MIT license, which means that you can use them in your projects right now. 

The project is based on a special loader for webpack named @fbem/css-loader, which allows you to import special BEM functions from CSS files. A BEM function always has two arguments: modifiers object, where key is the name of the modifier and value is its value; the second one is an array of mixes (a term from the BEM methodology). It's just an array of strings that will be added to the end of the resulting classname.

@fbem/css-loader is very similar to css-loader (and actually a fork of it) and has almost the same set of options and functionality. You can even use it with different style preprocessors by simply chaining loaders together in webpack config. But be sure to pick up if you need them 😏.

As I wrote above, it is more convenient to work with CSS when it is adequately divided into files. Even more convenient when there is a rule "one file - styles for one DOM node".

For these purposes, a special package was developed, which contains only one function - compose. This function allows you to combine several BEM functions into one and to split styles into as many files as you want. Take a look:

import { compose } from '@fbem/utils';

import { cnButton as modDisabled } from './_disabled/button_disabled.css';
import { cnButton as modStyle } from './_style/button_style.css';
import { cnButton as base } from './button.css';

const cnButton = compose(base, modDisabled, modStyle);

cnButton({ style: 'flat', disabled: true }, ['mix']); // 'button button_style_flat button_disabled mix'

Conclusion

In this article I showed a method (and tools for implementing this method) of organizing styles in a project. More information can be found in the project's GitHub repository. I hope I managed to interest you in my experiments in optimizations of writing styles process. Also, I hope you enjoyed the article and would be grateful if you could share it with someone.

Thank you.

I started blogging instead of a practice diary in university. Then I just liked to write articles on different topics. Mostly technical. Here is my old blog. Now I want to change the format a bit, so I created this brand new blog.

If you have any suggestions, complaints or wishes, feel free to mail on: me@vladivanov.me.