Я задумывал этот блог как более серьезный по сравнению с моим первым блогом. В целях расширения охвата я принял решение писать статьи на английском языке. Однако, все же некоторую часть статьи лично мне проще сформулировать на русском, а затем перевести на английский. Таким образом, после каждой публикации в моей “кузне” остается довольно много материала, который можно было бы немного причесать и опубликовать, но, к сожалению, технической возможности сделать это до недавнего времени не было.

Итак, сегодня я расскажу о том, как я проапгрейдил свой блог, чтобы он начал поддерживать мультиязычность, а также расскажу о проблемах, с которыми столкнулся.

Теория

Минутка душноты, как обычно.

Интернационализация — это процесс разработки программных приложений, которые потенциально могут адаптироваться к различным языкам и регионам без инженерных изменений.

Локализация — это процесс адаптации интернационализированного программного обеспечения для определенного региона или языка путем добавления локальных компонентов и переведенного текста.

В этом проекте я занимался и тем, и тем.

Данные

Разработка (имеется ввиду этап, когда мы уже перешли к написанию кода) любой фичи в моем блоге начинается с типов. Будь то пропсы компонента, DTOs или модель базы данных. Все это описывается с помощью TypeScript. Такой подход обеспечивает довольно очевидный эффект - при изменении в одном месте что-то разваливается в другом и, обычно, остается только починить нужным образом, чтобы фича заработала.

Я веду разработку блога в монорепозитории, поэтому и api, и web-client сервиса лежат в одном Git репозитории. Также, у меня есть модуль shared, в нем описаны различные project-wide константы (например существующие роли, а теперь и поддерживаемые языки), а также DTO. В итоге, и контроллеры в API, и data-layer в React компонентах используют одни и те же типы. Хочу подчеркнуть, что shared модуль представляет собой просто папку, откуда просто импортируется то, что нужно. Не NPM пакет, не что-либо еще, а обычная папка c TS файлами.

Для обращения к БД я использую SQL query builder Kysely. Примерно так это выглядит:

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

Этот запрос достанет id статьи по ее slug. На мой взгляд запись выглядит довольно понятной и лаконичной, к тому же, Kysely подскажет возвращаемый тип (и даже для более сложных запросов с JOIN или подзапросами). А так как каждый контроллер знает какой тип он должен отдать на клиент получается, что весь проект, несмотря на то, что разворачивается каждое приложение по отдельности, составляет единую систему.

В плане подходов к разработке фичей в моем блоге, данный случай, конечно, не стал исключением. В первую очередь, для поддержки мультиязычности в структуру БД пришлось внести довольно большие изменения. Все, что может быть локализовано переехало в отдельную табличку, и в итоге у каждой Article может быть сколько угодно ArticleContent, но есть unique constraint для пары lang и article_id.

Я решил не заводить отдельную таблицу Languages, поэтому поле lang - это просто varchar, куда записывается двухбуквенный код языка по стандарту ISO 639-1. Я решил не делать этого, потому что для добавления языка недостаточно добавить запись в БД, это довольно объемная работа, в том числе и в коде.

После обновления схемы данных развалились почти все контроллеры, которые были на нее завязаны, я починил все ошибки и местами обновил также DTO. После обновления DTO посыпались ошибки уже со стороны клиентской части, они также были починены и на самом деле мультиязычные статьи к этому моменту были уже готовы. Хотя, в этом проекте предстояло еще много работы по переводу интерфейса, об этом расскажу далее.

Шрифт

Когда я придумывал этот блог, я хотел, чтобы он выглядел строго. Может быть даже как какое-нибудь печатное издание. Я перепробовал несколько шрифтов и мой выбор пал на Libre Baskerville.

Baskerville — это шрифт с засечками (serif), разработанный в 1750-х годах Джоном Баскервиллем (1706–1775) в Бирмингеме, Англия. Baskerville классифицируется как переходный шрифт, задуманный как усовершенствование того, что сейчас называют шрифтами старого стиля того периода.

Libre Baskerville — это веб-шрифт, оптимизированный для основного текста. Он основан на шрифте American Type Founder's Baskerville 1941 года, но имеет более высокую x-height, более широкие counters и немного меньший контраст, что делает его хорошо подходящим для чтения на экране.

Этот шрифт очень мне нравится и на мой субъективный взгляд очень хорошо подходит для моего блога. Однако, в ходе проектирования данной фичи было выяснено, что Libre Baskerville не поддерживает кириллические глифы. То есть при попытке отрендерить текст с русскими буквами шрифт фоллбэкнется на serif (скорее всего, это будет Times New Roman) и это будет выглядеть, мягко говоря, не очень:

Конечно, это никуда не годится, поэтому я стал искать пути решения этой проблемы. Я перепробовал с десяток бесплатных шрифтов, похожих на Libre Baskerville, однако мои поиски не увенчались успехом. Тогда я даже подумал о том, чтобы приобрести платную версию шрифта Baskerville на сайте Paratype. За два начертания мне пришлось бы выложить 60 долларов, плюс там есть дополнительные сложности типа увеличивающейся стоимости подписки в зависимости от просмотров страницы, а еще довольно странное требование “May not use the font to create content by visitors to your websites”. Это довольно странно, потому что в моем случае это требование как будто бы ограничивает использование шрифта в форме для написания комментариев.

В общем, довольно много сомнительных и непонятных моментов, да еще и деньги придется платить, причем 60 долларов это относительно много, это примерно полгода оплаты услуг за хостинг, поэтому и этот вариант я отмел.

В итоге не оставалось ничего другого кроме как взять Libre Baskerville, благо он распространяется под OFL, и дорисовать кириллические глифы. Я подумал, что это не очень сложно, к тому же некоторые буквы выглядят так же как и латинские и их можно просто скопировать. На самом деле это и правда несложно, но это довольно большой объем очень кропотливой работы. Конечно же, я понимаю, что я не прочувствовал на себе создание шрифта с нуля. У меня уже были готовые гайдлайны от авторов Libre Baskerville и даже некоторые буквы для сравнения. Честно говоря, думаю, что с нуля шрифт я бы не смог создать.

Так, потихоньку я рисовал букву за буквой. В итоге было нужно нарисовать 33 * 2 (заглавные + строчные) * 2 (regular + bold) = 132 буквы. Некоторые буквы я скопировал без изменений, некоторые сделал из других (например П легко сделать из Н, а Ж из двух К). Некоторые же пришлось прям почти с нуля рисовать (например Ф или Л), этим объясняется то, что данные буквы вышли чуть более кривыми, чем остальные. Хотя, по правде говоря, все буквы получились кривоватыми, это лучше чем фоллбэк на Times New Roman и в целом результат меня устроил.

Я использовал Glyphr Studio и, в целом, это довольно удобная программа, но иногда у нее течет память и она вылетает, так что приходилось сохранять каждый раз, когда очередная буква была нарисована. Увы, кое-что все таки приходилось рисовать дважды.

А Вам, уважаемые читатели, прямо сейчас совершенно бесплатно доступны два этих замечательных шрифта (лицензируется OFL):

- BlogBaskerville-Bold.ttf

- BlogBaskerville-Regular.ttf

- Лицензия

Интерфейс

С интерфейсом все куда проще. Я использую react-intl для интернационализации. В коде используются ключи, затем по ключу в зависимости от языка подставляется нужный перевод. Также, из коробки поддерживаются плюрализация и подстановка значений, а также форматирование времени, дат, чисел и так далее.

Но хочу рассказать о некоторых практиках, которые помогут сделать работу с переводами проще.

Первая рекомендация - это хранить переводы рядом с компонентом. Давайте рассмотрим на примере компонента ArticleStats (это компонент для отображения статистики статьи, Вы могли видеть его на главной, в сайдбаре на страннице каждой статьи, а еще в результатах поиска):

📦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 <- папка с переводами
 ┃ ┣ 📜ArticleStats.en.json
 ┃ ┗ 📜ArticleStats.ru.json
 ┣ 📜ArticleStats.css
 ┗ 📜ArticleStats.tsx

В файле ArticleStats.en.json лежат ключи в таком виде:

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

В итоге все файлики переводов для одного компонента лежат в одном месте, а воедино их легко собрать простым скриптом на Node.js. Затем этот один большой файл читается на сервере и в память загружаются сразу все переводы для всех языков, а на клиент при SSR отдаются ключи только для нужного языка. Хочу заметить, что все ключи префиксятся именем блока, это нужно для того, чтобы уменьшить вероятность возникновения коллизий.

Второе, что я мог бы посоветовать - это запретить использование чего угодно, кроме строковых литералов при указании ключей. Поясню. Чтобы получить строку в react-intl, вы должны отрендерить элемент FormattedMessage:

<FormattedMessage id="ArticleStats.published" />

или вызвать метод intl.formatMessage:

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

И иногда я видел варианты с шаблонными строками, тернарными операторами и это на самом деле все только усложняет.

Например, вместо:

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

Гораздо лучше написать:

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

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

Код стал чуть посложнее (хотя и не сильно), зато теперь такие вызовы можно искать хоть обычными регулярками, не говоря уже о запросах по AST (вот тут можно поиграться с этим). Статический анализ кода в данной ситуации очень полезен, потому что так у Вас будет возможность сразу узнать о том, какие ключи не используются, чтобы их удалить! Кода становится меньше, бандлы становятся тоньше и ничего лишнего - красота.

На самом деле, можно еще больше улучшить DX (не придется запускать странные скрипты и разработчик сразу будет узнавать о проблеме), написав кастомное правило для ESLint. Автофиксить его, скорее всего, не получится, но и поправить такое место будет нетрудно. В большинстве случаев подобные сложные выражения раскрываются в хэшмап, либо switch-case. Если же ключа два, то можно продолжить использовать тернарный оператор, просто снаружи, а не внутри.

Алгоритм

В первую очередь смотрим на query параметр lang , если он есть и его значение равно одному из поддерживаемых языков, то берется указанный язык, алгоритм останавливается. Иначе, смотрим на одноименную куку. Так же, если кука есть и ее значение равно одному из поддерживаемых языков, то устанавливается указанный язык. Если же и куки нет (либо указан неизвестный язык), мы попытаемся распарсить заголовок Accept-Language, если и это не удастся, либо в Accept-Language не указан ни один поддерживаемый язык, то выбирается английский (en).

После определения языка происходит “залипание” на него с помощью куки. После этого сменить его можно будет только явно перейдя на страницу с параметром lang.

SEO

Поисковой робот должен знать о том, что на моем сайте поддерживается мультиязычность. При запросе страницы без query параметров GoogleBot’у (или другому поисковому роботу), будет отдаваться версия на английском (он не передает куки и заголовок Accept-Language), а значит алгоритм будет фоллбэкаться на en.

Для того, чтобы сообщить язык текущей страницы используется атрибут lang у элемента html.

А для ссылок на другие страницы используется элементы link с атрибутом rel равным alternate. Выглядит это вот так:

<link rel="alternate" hreflang="en" href="https://vladivanov.me/"> <!-- на себя саму тоже нужна ссылка -->
<link rel="alternate" hreflang="en" href="https://vladivanov.me/?lang=en">
<link rel="alternate" hreflang="ru" href="https://vladivanov.me/?lang=ru">

Выкатка

Kysely умеет генерировать миграции, но в итоге и изменение структуры, и переливку данных я делал вручную прям в контейнере с БД на проде с помощью psql😁. Сначала я завел новую таблицу, завел индексы для поиска, сделал дамп таблицы Articles, потом накатил новую версию сервиса и уже потом дропнул старые ненужные колонки. Было немного страшно, хотя у меня вроде как есть еженедельные бэкапы от DigitalOcean, с другой стороны я никогда не пробовал из них восстанавливаться.

Вся фича с мультиязычностью была внесена под фичефлаг и обычные пользователи не могли ей воспользоваться, после тестирования и создания в админке версий для всех статей на русском, я вынес фичу из под фичефлага, но пока отключил определение языка по заголовку Accept-Language.

Сейчас вместе с этой статьей фича начала работать согласно описанию, в интерфейс была добавлена кнопка для переключения языка, а чуть позже я сделаю email рассылку для подписчиков. Это довольно значимое событие в истории развития моего блога.

Заключение

Это был крайне захватывающий проект, с учетом того, что он охватил весь спектр работ. А это и разработка, и администрирование БД и даже вопросы касательно дизайна (типографии). Я очень рад, что в моем блоге появилась мультиязычность, а еще я рад поделиться с Вами этим замечательным и ярким опытом.

Пишите в комментарии, если Вам интересно как работает мой блог, я готов рассказать Вам о любой его части.

Спасибо за внимание!

Если вы когда-нибудь имели удовольствие разрабатывать что-либо на JavaScript, думаю хотя бы раз в жизни вы сталкивались с чем-то типа:

SyntaxError: Cannot use import statement outside a module

(если нет, то все еще впереди! 😉)

В особенности сложно понимать что происходит, когда исходный код в процессе сборки подвергается транспиляции и одна модульная система превращается в другую.

Итак, сегодня я постараюсь рассказать про модульные системы JavaScript/TypeScript, как так получилось что их несколько и что лично я бы рекомендовал использовать в 2023 году.

Немного теории

Принцип модульности является средством упрощения задачи проектирования программного обеспечения (ПО) и распределения процесса разработки между группами разработчиков.

Именно необходимость разработки больших программных систем привела к появлению модульного программирования, когда вся программа разбивается на составные части, называемые модулями, причем каждый из них имеет свой контролируемый размер, четкое назначение и детально проработанный интерфейс (aka API)

Модуль — это последовательность логически связанных фрагментов, оформленных как отдельная часть программы. Во многих языках оформляется в виде отдельного файла с исходным кодом или поименованной непрерывной её части.

Конечно, принцип модульности не обошел стороной и JavaScript. Напротив, именно в JavaScript были реализованы сразу несколько подходов к разделению кода, но обо всем по порядку.

IIFE

Начнем, пожалуй, с IIFE, хоть это и не модульная система, а нативный механизм языка, я считаю, что для полноты картины нам нужно его рассмотреть. IIFE представляет собой функцию, которая объявляется и сразу же вызывается. Эта техника используется ради изоляции - переменные, объявленные в теле такой функции недоступные извне, что помогает избежать конфликтов имен и загрязнения глобального пространства имен. Пример такой функции можно увидеть ниже:

;(function () {
  const a = 5;

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

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

Если вы предпочитаете использовать JS без ;, то перед объявлением IIFE я рекомендую ставить ; как показано выше, чтобы выражение не интерпретировалось как вызов функции. Если же вы за ; повсюду, то таких проблем у вас не возникнет.

Кстати, IIFE может быть асинхронной, а это значит, что в теле такой функции допустимо использовать ключевое слово await, но это не совсем по теме этой статьи.

Несмотря на то, что IIFE дает удобный (и нативный) способ изоляции кода, он не дает удобного механизма разделения кода на файлы. Конечно, вы можете использовать сколько угодно тегов script на странице, однако на больших проектах очень сложно отслеживать зависимости модулей друг от друга. И хотя, с точки зрения определения модуля в программировании, которое я привел выше, модуль не обязательно должен представлять собой отдельный файл, практика показывает, что работать так значительно проще, поэтому со временем появились более мощные инструменты и подходы.

AMD

AMD (Asynchronous Module Definition) - это модульная система, предназначенная для использования в браузерной среде. AMD предоставляет механизм обнаружения и разрешения зависимостей модулей, что позволяет автоматически загружать и выполнять модули в правильном порядке.

AMD разрабатывалась группой разработчиков, которые были недовольны направлением, выбранным CommonJS. Фактически, AMD отделилась от CommonJS на раннем этапе своего развития.

Одной из главных особенностей AMD является возможность асинхронной загрузки модулей. Когда модуль запрашивается для загрузки, AMD загрузчик асинхронно загружает зависимости модуля, обеспечивая правильный порядок загрузки.

Ниже приведен пример как это можно использовать:

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

Здесь мы реализуем модуль sounds и явно говорим о его зависимостях. Одним из самых популярных инструментов, реализующих AMD является RequireJS. Приведу пример того, как он может использоваться:

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)

В то время как в браузерных окружениях использовалась AMD, в node-окружениях использовалась еще одна модульная система - CommonJS. Основное различие между AMD и CommonJS заключается в поддержке асинхронной загрузки модулей.

Если AMD в наше время встретить довольно трудно, то CommonJS буквально повсюду. Тут важно заметить, что CommonJS все еще является модульной системой Node.js по-умолчанию.

Ниже приведен пример кода с использованием CommonJS:

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

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

Для импорта модулей в CommonJS используется ключевое слово require. Это функция и она принимает путь (на самом деле не совсем путь, что достижимо благодаря механизму резрешения модулей) к модулю и возвращает экспортируемые значения этого модуля.

Любые свойства, добавленные в exports или присвоенные module.exports, становятся экспортируемыми значениями модуля.

В CommonJS модули загружаются синхронно и разрешаются во время выполнения. Когда модуль первоначально загружается, его код выполняется, и его экспортированные значения становятся доступными для импорта в других модулях.

В браузере нет встроенной функции require и доступа к файловой системе, поэтому CommonJS в браузере не поддерживается, однако можно получить схожее API, используя подход AMD и библиотеку RequireJS:

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

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

ES Модули (ESM)

И вот мы, наконец, добрались до первой модульной системы, которая описана в стандарте ECMAScript. ES модули появились вместе с ES6, в 2015 году. И да, вы все правильно поняли, на протяжении 20 лет в JavaScript не было стандартизованной модульной системы. Я думаю этот синтаксис также Вам знаком:

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

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

    dog.bark();
  });
}

Несмотря на стандартность, ES модули выключены по-умолчанию. В Node окружении вы должны использовать type: module в вашем package.json, либо .mjs расширения файлов. В браузерных окруженях для использования синтаксиса ESM внутри тега script необходимо установить атрибут type в значение module. Поддержка ES модулей впервые появилась в Node 12 под флагом --experimental-modules. В более старших версиях ES модули вышли из под флага.

Модульные системы на этом закончились, однако есть еще пара подходов, которые важно рассмотреть.

UMD

UMD (Universal Module Definition) - это шаблон или подход к созданию модулей, который позволяет модулям работать как в среде CommonJS, так и в среде AMD, а также сделать их доступными как глобальные переменные, если загрузчик модулей отсутствует.

Основная идея UMD заключается в создании модуля, который может автоматически адаптироваться к различным средам выполнения и загрузчикам модулей.

UMD использует условные конструкции, чтобы определить, какой из существующих модульных систем доступен, и в зависимости от этого выбирает соответствующий способ экспорта и импорта модуля.

Выглядит это примерно так:

(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
  };
}));

Если среда выполнения поддерживает AMD (проверка define), модуль определяется с использованием define и указываются зависимости для загрузчика модулей.

Если среда выполнения поддерживает CommonJS (проверка exports), модуль экспортируется с помощью module.exports, и зависимости разрешаются через require.

Если ни одна из проверок не прошла, модуль "экспортируется" путем присвоения его свойства глобальному объекту (root), который в данном случае представляет глобальное пространство имен.

SystemJS

SystemJS - это универсальный загрузчик модулей JavaScript, предназначенный для использования в браузере и среде выполнения Node.js. Он разработан с учетом поддержки и загрузки различных модульных форматов, таких как AMD, CommonJS, UMD и ES модули, позволяя разработчикам использовать разные форматы модулей в одном проекте.

Выглядит это примерно так:

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

Причем на месте dog.js может быть модуль, описанный в ЛЮБОМ формате из вышеперечисленных.

Но я бы сказал, что если у вас возникла потребность в использовании разных модульных систем в одном проекте, то скорее всего что-то не так с вашим проектом.

На самом деле, скорее всего вы не будете иметь дело ни с AMD, ни с UMD, ни с SystemJS. ESM и CJS же очень распространены и вы будете видеть их на самом деле вне зависимости от того, в каком окружении разрабатываете.

Бандлеры и транспиляторы

Материал, который мы сейчас рассмотрели не является сложным сам по себе. Думаю, не составит труда опредеделить используемый подход при просмотре исходного кода. Однако, в реальной разработке код который мы пишем не попадает в продакшен в неизменном виде. На бэкенде обычно достаточно транспилятора: самым распространенным сценарием кажется транспиляция TS кода в JS (конечно, есть решения, например ts-node или deno, но это тема для другой статьи). На фронтенде все еще сложнее - код проходит не только через транспилятор, но и через различные инструменты, называемые бандлерами, минификаторами и тд.

У транспиляторов (например, tsc) есть возможность генерировать код с использованием всех модульных систем, которые мы рассмотрели: ESM, CJS, AMD, UMD и SystemJS. А здесь Вы можете поиграться с этим самостоятельно. Например, вот такой код:

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

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

Не изменится, если собрать его с помощью tsc с настройкой module, установленной в 'esnext', однако если собрать код тем же инструментом, но с настройкой module , установленной в 'commonjs', то код примет такой вид:

"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;

Если разобраться что здесь происходит и откинуть сгенерированные хелперы, то можно заметить, что код, который мы писали с использованием ESM превратился в код c использованием CJS и это и есть корень всех ошибок!

Отсюда появляется путаница. Так как в исходниках вы используете ESM, кажется логичным установить type равный 'module' настройку в package.json, но не тут то было. Реально Node.js будет запускать уже собранный tsc код, который, как мы убедились, ESM не использует и вы получите ошибку:

ReferenceError: require is not defined

Возможна и обратная ситуация: например, например, мы собрали код без изменений, и в нем остался синтаксис ESM. Но настройку type равную 'module' мы не установили, тогда мы получим ошибку из начала статьи:

SyntaxError: Cannot use import statement outside a module

Все это осложняется тем, что некоторые пакеты прекращают поддержку CJS. Одним из таких пакетов является chalk. С 5 мажорной версии они перестали поддерживать CJS и при попытке сделать require вы получите ошибку:

Error [ERR_REQUIRE_ESM]: require() of ES Module

А теперь представьте ситуацию, что у вас есть TS код:

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

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

И вы решили собрать его с помощью tsc с module равной 'commonjs'. Вы получите вот такой код:

"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;

А при попытке запустить его - ошибку:

Error [ERR_REQUIRE_ESM]: require() of ES Module

которая говорит о том, что какой то из наших модулей (в данном случае chalk) не поддерживает CJS. И это очень запутанно, так как в исходном коде у нас нет никаких require! А в уже собранном коде бывает довольно сложно разобраться, если проект достаточно большой.

В данном случае помогут два варианта:

1. Установть type в значение 'module' в package.json, что также потребует установки module в значение 'esnext' в tsconfig.json (возможно, сломается что-то другое 😁).
2. Даунгрейднуть chalk до версии 4.1.2, в которой CJS еще поддерживался. То есть проблема различия модульных систем заставляет Вас использовать не самые новые версии пакетов, что, конечно же, нехорошо.

Вообще, хочу дополнительно отметить, что type, установленный в значение 'module' это очень серьезная project-wide настройка, которая влияет буквально на все, поэтому поменять ее, обычно, крайне трудно. Например, если вы используете jest с type равным 'module', а потом резко по какой-то причине решили перейти на type равный  'commonjs' у вас перестанут работать top-level await в тестах (которые, например могли бы использоваться для моков отдельных модулей).

И что же делать?

Я не могу давать рекомендации относительно уже существующих проектов, потому что, как я уже сказал, изменение настройки type, обычно, даётся крайне трудно и в каждом отдельном случае могут возникнуть разные проблемы. Но, конечно, я бы рекомендовал перейти на type равный 'module', если есть такая возможность.

Новые же проекты я бы рекомендовал начинать с type равным 'module'. Все больше публичных пакетов отказываются от поддержки CJS. К тому же, ESM дает дополнительные возможности, например top-level await.

Конечно, есть нюанс. При использовании ESM расширения файлов необходимы при импортах модулей ('./startup/index.js'). Также не поддерживается автоматическое разрешение импорта папки в index.js файл (directory index), то есть путь нужно указывать полностью.

Это проблема, если вы используете tsc, так как TypeScript не модифицирует пути импортов при транспиляции. Эту проблему можно решить специальным тулингом или просто использовать в импортах .js расширение. TypeScript сможет понять о каком файле (.ts) идет речь, а после транспиляции в коде будет валидный путь. Кстати моя IDE (vscode) даже смогла правильно подсказать путь с .js расширением.

Как альтернативу для TypeScript проектов можно рассмотреть ts-node, но запускать его необходимо с флагом --transpile-only. Конечно, нужно помнить, что это другой, отличный от стандартной node рантайм и у него есть свои не менее интересные особенности.

Еще одним решением этой проблемы могут быть bare specifiers в сочетании с настройкой moduleResolution равной 'nodenext', но тогда нужно еще решить проблему копирования package.json файлов в папку с билдом (причем структуру необходимо сохранить).

Но все же для новых JavaScript проектов я бы рекомендовал использовать type равный 'module' и только его. В случае с TypeScript не все так просто, однако я бы тоже рекомендовал использовать type равный 'module' и указывать .js расширения. Да, это немного странно, но это лучшее решение из тех, что есть, как по мне.

Выше мы рассмотрели вопросы использования модульных систем в node-окружениях. А как же быть в браузерных? Обычно, в браузерных окружениях таких проблем не возникает, так как используются различные инструменты типа webpack, который сам по себе поддерживает и ESM синтаксис, и CJS. На выходе обычно мы имеем бандл, в котором весь код просто сконкатенирован в один и никаких модульных систем (а значит и проблем с ними там нет). Webpack также предоставляет решение для разбиений приложения на файлы (чанки) с целью асинхронной загрузки по требованию, что тоже есть модульная система, но это тема для отдельной статьи.

Если говорить о более новых инструментах, например Vite, то он построен на ESM и использует в браузере script с атрибутом type равном 'module'. Быстродействие Vite построено на ESM. Насколько мне известно, альтернативы этому нет, поэтому выбирать не приходится.

Заключение

Пока я писал эту статью я нашел в интернете множество других статей на тему сравнения модульных систем в JavaScript. Однако, все эти статьи лишь поверхностно рассматривают различия и сходства этих систем. Я же постарался рассмотреть не только модульные системы, но и проблемы с которыми обычно сталкиваются разработчики и даже предложил несколько решений. Надеюсь, вам это будет полезно в ваших проектах.

Спасибо за внимание и до встречи!

Ссылки

1. Modular programming, просмотрено 19 июня 2023, https://en.wikipedia.org/wiki/Modular_programming
2. IIFE, просмотрено 19 июня 2023, https://developer.mozilla.org/en-US/docs/Glossary/IIFE
3. RequireJS, просмотрено 19 июня 2023, https://requirejs.org/
4. ESM, просмотрено 19 июня 2023, https://nodejs.org/docs/latest-v18.x/api/esm.html
5. UMD, просмотрено 19 июня 2023, https://github.com/umdjs/umd
6. AMD, просмотрено 19 июня 2023, https://en.wikipedia.org/wiki/Asynchronous_module_definition

QR коды - очень крутая штука. Но что если я скажу вам, что в них можно еще и поиграть. Интересно? Тогда поехали!

Итак, сегодня я расскажу о том как я написал игру flappy bird и поместил ее в QR код. Задача не такая простая как кажется на первый взгляд. В качестве челленджа мы хотим, чтобы вся игра содержалась внутри QR кода и для того чтобы поиграть нам был нужен только QR код, то есть нам не подходит вариант с ссылкой на игру внутри QR кода. Это неинтересно!

Чаще всего, когда вы сканируете QR код данные из декодера попадают в поисковую строку браузера. Конечно, есть и другие сценарии использования, однако я пока предлагаю остановиться на этом. Значит наша задача заключается в том, чтобы передать исходный код нашей игры с через строку браузера. Но можем ли мы так сделать? Конечно, можем и помогут нам в этом Data URLs. Мы можем проверить работоспособность данного метода просто взяв любой валидный HTML код, закодировав его в base64 и добавив вначале префикс data:text/html;base64,. Далее нам нужно просто получившуюся строку закодировать в QR код. Звучит довольно просто, но здесь есть одно не очень приятное обстоятельство: мы не можем закодировать в QR код бесконечное количество данных.

Ограничения

По спецификации QR коды делятся на версии. Номера версий варьируются от 1 до 40. Каждая версия имеет особенности в конфигурации и количестве точек(модулей) составляющих QR-код. Версия 1 содержит 21×21 модулей, версия 40 — 177×177. От версии к версии размер кода увеличивается на 4 модуля на сторону.

Каждой версии соответствует определенная емкость с учетом уровня коррекции ошибок. Чем больше информации необходимо закодировать и чем больший уровень избыточности используется, тем большая версия кода нам потребуется.

QR код поддерживает несколько режимов кодирования:

Также, QR-коды имеют специальный механизм увеличения надежности хранения зашифрованной информации. Для кодов созданных с самым высоким уровнем надежности могут быть испорчены или затерты до 30% поверхности, но они сохранят информацию и будут корректно прочитаны. Для исправления ошибок используется алгоритм Рида-Соломона.

В таблице ниже показано максимальное количество сохраняемых символов в каждом режиме кодирования и для каждого уровня исправления ошибок:

Алфавит base64 содержит 64 символа и разделен на группы:

• Заглавные буквы (индексы 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
• Строчные буквы (индексы 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
• Цифры (индексы 52-61): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
• Специальные символы (индексы 62-63): +, /

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

Помимо этих символов, используется знак равенства (=) в качестве заполнителя.

Самый оптимальный режим кодирования для моей задачи - это побайтовый. Что касается уровня исправления ошибок я думаю M уровня будет достаточно, поэтому мы можем рассчитывать на то, что сможем закодировать 2331 символов, это чуть больше 2 килобайт. Однако, следует помнить, что закодированная в base64 строка длиннее исходной примерно на 30%.

Инструменты

Для удобства разработки необходимо оптимизировать процесс генерации QR кода. Также, необходимо произвести некоторую предобработку исходного HTML кода, а именно минификацию, так как у нас есть строгое ограничение по размеру.

Для этих целей был написан специальный скрипт на NodeJS:

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: {
      // переменные на верхнем уровне 
      // по-умолчанию не минифицируются
      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' }], // режим кодирования
  { errorCorrectionLevel: 'm' } // уровнь исправления ошибок
);

console.log('Done!');

Таким образом, после запуска скрипта мы имеем на выходе готовый QR код, а также детализацию по размеру кода, что поможет нам в дальнейшей оптимизации.

Разработка

Для начала создадим минимальный валидный HTML документ:

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

Я хотел бы чтобы в игре были как можно более адекватные текстуры, однако мы договорились не загружать ничего дополнительно, поэтому придется программировать рисование текстур. Можно было бы развлекаться с div, box-shadow, различными градиентами или SVG, но все эти подходы достаточно многословны и особо нет эффективных способов минифицировать такой код. Поэтому я решил выбрать canvas:

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

Я создал DOM элемент и установил атрибут id.

Теперь в коде я могу просто обратиться к нему как window.c или просто по имени c и нет никакой необходимости в использовании методов поиска DOM элементов в документе по типу querySelector или getElementById, имена которых на самом деле достаточно длинные и не поддаются сокращению. Кстати, хотел бы обратить внимание на этот момент. Мы будем использовать canvas, то есть для рисования мы будем использовать различные методы CanvasRenderingContext2D, и есть смысл присваивать эти методы в переменные, потому что минифицировать свойства объекта мы не можем, однако для присваивания нам необходимо вызвать bind , чтобы передать this контекст, коим в данном случае является контекст рендеринга canvas. Вот о чем я говорю:

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

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

После минификации даст что-то типа такого (проблельные символы оставлены для понятности):

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

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

В то время как такой кусок кода:

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

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

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

Превратится во что-то типа такого:

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

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

То есть профит от такого присвоения есть, но не всегда. Для каждого отдельного случая нужно считать длину строк. Например, для метода fillRect такое присвоение имеет смысл только если этот метод вызывается в коде 2 или более раз.

Конечно, есть и другие способы присвоения функции, например:

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

Но такой вариант будет длиннее после минификации по сравнению с кодом, где используется bind. Поэтому я решил использовать код с bind, так как не смог найти вариант, который был бы короче.

Кстати, повсеместно в коде используется let , потому что он на 2 символа короче const 🙂.

Текстуры

Я уже говорил о том, что хотел бы использовать как можно более похожие на оригинал текстуры для своей игры. Например, примерно такую птицу я бы хотел видеть в игре:

При этом у нас нет возможности загрузить картинки через интернет, поэтому я посчитал, что самым коротким способом будет хранить изображения в переменных типа string прямо в исходном коде. Но как уместить картинки в 1.6 килобайта с учетом того, что есть еще и код игры?

Можно заметить, что для того, чтобы нарисовать текстуру выше нам нужно всего 5 цветов. В то время как популярные форматы изображений такие как JPEG или PNG позволяют кодировать миллионы цветов, что достигается достаточно высокой разрядностью цвета. Например, цветные изображения JPEG хранят 24 бита на пиксель, а PNG до 48 бит. Поэтому вариант с тем чтобы просто закодировать картинку в base64 сразу отпал.

Такая глубина цвета нам не нужна, а значит решить эту проблему можно с помощью разработки собственной палитры. Давайте представим, что каждому цвету мы назначили букву латинского алфавита, тогда изображение выше примет вид:

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

legend:
u - transparent (не знаю почему u, видимо потому что undefined)
a - #000
b - #fff
c - #f71
d - #eec
e - #f20

Размер такой картинки - 204 байта. Однако, только посмотрев на эту картинку виден огромный потенциал для сжатия! Первое, что приходит на ум - это RLE. Если коротко, то суть алгоритма заключается в замене повторяющихся символов на символ + кол-во повторов: `aaaaa` -> `a5`. В случае с последовательностью выше сжатие работает достаточно эффективно - 32.35 %. Минус такого подхода в том, что при неповторяющихся последовательностях алгоритм работает в другую сторону: `abcde` -> `a1b1c1d1e1`, хотя это и поддается оптимизации: `abcdeeeee` -> `-4abcd5e` или `abcdeee`  ->  `abcd3e`

Давайте рассмотрим другой способ. Допустим цветов у нас будет не больше 16, тогда можно особо не напрягаясь достигнуть сжатия 50% для ЛЮБОГО набора данных. Каждому символу необходимо присвоить код. И в результирующую строку записывать не сам символ, а результат выражения:

char((code(color1) << 4) | code(color2))
// char - получения символа по его коду
// code - получение кода по символу

Тогда в 8 битах мы будем хранить информацию о 2 пикселях. Но есть один нюанс. Коды символам нужно присваивать с 2 (0b10). Почему? В таблице ASCII символов до кода 32 идут служебные символы. Я не нашел способа их напечатать на Mac, а также не уверен относительно того можно ли использовать их в скрипте. Скорее всего, можно, но потребуется экранирование. В общем, для решения этой проблемы достаточно добавить смещение 2 и тогда в результате функции code будет всегда получаться число больше 32, а значит и печатаемый символ.

В результате с помощью первого алгоритма (RLE с оптимизацией единичных символов) я получил:

u6a6u9a2c3ab2au7ac4ab4au5ac5ab3abau3ac6ab3abau3a5c3ab4au2ad5ac3a6uad5ac2ae6aua5c2aea6u3ac6ae5au4a2c5a5u7a5u7

А в результате второго:

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

И разница составила всего 6 байт. Конечно, результат второго алгоритма можно попробовать еще прогнать через RLE, но надо помнить о том, что раскодировать это все тоже придется кодом скрипта, который тоже занимает какое то место и я решил, что RLE меня вполне устраивает.

Кстати, можно было бы попробовать закодировать исходную строку алгоритмом Хаффмана, и даже заранее вычислить кодовое дерево, но в таком случае довольно трудно контроллировать непоявление служебных непечатаемых символов, а код реализации декодера достаточно громоздкий по сравнению с кодом декодера RLE или битовых последовательностей.

Таким образом, в игре появились текстуры:

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

После минификации этот код будет весить примерно 220 байт, что вполне приемлемо.

Но пока что это всего лишь обычные строки. Для их превращения в изображения тоже нужно проделать определенные действия:

let draw = (t, x, y, w, i = 0, pw = 2, ph = 2) => {
  while (t.length) {
    let c = t[0], times = +t[1]; 
    // Повтороений не должно быть больше 9
    // То есть вместо записи a10 можно записать a5a5
    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);
  }
}

Итак, что же здесь происходит? Первым аргументом мы передаем текстуру - одну из тех строк, которые мы рассмотрели выше. Далее идут координаты x и y - это смещение рисования относительно левого верхнего угла canvas. Так как текстура у нас представлена строкой необходимо указать w (ширину), это позволит вовремя переносить рисование на “следующую строку”. Аргумент i тоже заведен с целью оптимизации - если текстура начинается с пустых пикселей ('u'), то их можно не указывать, а счетчик i сразу перенести на кол-во таких пикселей. Благодаря этому мы можем избавляться от 'u' как мы избавляемся от незначащих нулей в числе. pw, py - ширина и высота пикселя соответсвтенно. Так как бОльшая часть трубы выглядит таким образом:

Мы можем вызвать draw всего один раз и указать ph, равный высоте трубы, вместо N вызовов draw, где N высота трубы в пикселях / ph. Сделано для быстродействия.

Код

Вся игра у нас (как и любая другая, насколько мне известно) будет крутиться в бесконечном цикле:

let tick = 0;

let setup = () => {
  vSpeed = flyUpSpeed; // птица взлетает в самом начале
  score = playing = 0;
  y = 308; // начальное положение - центр экрана
  pipes = [[100, gate()], [788, gate()]]; 
  // инициализируем первые 2 трубы,
  // про трубы чуть дальше раскажу подробнее
}

let render = () => {
  ...

  tick++;
  requestAnimationFrame(render);
}

setup();
render();

Первым делом, конечно, надо нарисовать фон. Я просто заливаю его цветом #0ac (цвета используем трехбуквенные). Я думал насчет генерации фона, но не придумал как уместить этот код в наш размер, поэтому просто залил. Далее идет рисование труб:

pipes.map(pipe => {
  pipe[0] -= hSpeed; // двигаем трубы каждый рендер

  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);

  ...
})

В памяти содержится информация только о двух трубах, потому что больше на экран просто не влезет. Игра спроектирована так, что при уходе трубы с индексом равным 0 за экран, она удаляется, а игрок получает очко:

if (px < -64) {
  score++;
  bestScore = score > bestScore ? score : bestScore; // тернарный оператор короче, чем Math.max
  pipes = [...pipes.slice(1), [pipes[1][0] + 284, gate()]];
}

Информация от трубах хранится в виде массива кортежей [x,y], где x - расстояние от левого края canvas до начала трубы, y - расстояние от верхнего края экрана до конца верхней трубы (затем идет разрыв, куда должна пролететь птица, а потом начинается нижняя труба). y для каждой трубы генерируется в момент создания функцией gate:

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

Расстояния рассчитаны таким образом, чтобы игрок не мог врезаться в трубу с индексом, отличным от 0, поэтому и проверка на столкновение проводится только для одной трубы:

let [[px, py]] = pipes; // берем координаты только первой трубы

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

Кстати, как вы уже заметили, все константы заранее посчитаны, потому что так код занимает меньше места.

После труб рисуется птица. У нее всегда один и тот же x, а вот y постоянно изменяется:

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

vSpeed += gravityAcceleration;
y += vSpeed;

...

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

// над птицей рисуем анимированные крылья
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 = () => { 
  // взлет вверх при клике
  vSpeed = flyUpSpeed;
}

Ну и в конце рисуем текст, чтобы сказать игроку во что он вообще играет, сколько очков набрал и показать экран проигрыша:

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);
}

Мы рассмотрели почти весь код, однако, кое что я все же опустил, но вы можете найти полный код проекта и даже поиграться самостоятельно на странице проекта на Github.

Сборка

После того как наш код дописан можно приступить к сборке. Благодаря тому, что мы позаботились об инструментах заранее нам нужно всего лишь запустить:

npm i && npm run build

Скрипт сам создаст папку output и поместит туда результат, а именно:

1. Минифицированный HTML;
2. Data URL;
3. PNG-картинку с QR кодом.

А также, выведет детализацию по размерам:

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!

А вы можете прямо сейчас отсканировать QR код:

или сразу скопировать data-url в свой бразуер:

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

И поиграть в Flappy Bird QR code edititon! А самое крутое это то, что для игры не нужно ничего кроме QR кода (ну и устройства с браузером, конечно).

Также, приложу скриншот с игрой. Однако, я рекомендую Вам попробовать поиграть самим!

Спасибо за внимание!

⚠️ Увы, но стандартная камера айфона не понимает data-url. Она видит QR код, но говорит “no usable data found” 😟. У меня получилось распознать код первым приложением из App Store, а вообще и с любым другим приложением проблем быть не должно.

🤓 В самом начале мы обсуждали версии QR кодов. Так вот, у нас получился QR код 39 версии (предпоследней).

Ссылки

1. qrcode, просмотрено 12 января 2023 <https://www.npmjs.com/package/qrcode>
2. QR Code Specification, просмотрено 12 января 2023, <https://www.labeljoy.com/qr-code/qr-code-specification/>
3. QR code, просмотрено 12 января 2023, <https://en.wikipedia.org/wiki/QR_code>
4. Data URLS, MDN, просмотрено 12 января 2023, <https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs>
5. Base64 Characters, просмотрено 12 января 2023, <https://base64.guru/learn/base64-characters> 

Привет! Если Вы веб разработчик или когда либо имели удовольствие писать фронтенд Вы должно быть знаете что такое CSS. Если Вы когда нибудь писали фронтенд для достаточно большого сервиса Вы наверное сталкивались с тем, что открывая файл со стилями годовалой давности непонятно ничего от слова совсем!

Разбираться в большом CSS файле достаточно трудно. Особенно, если этот файл использует препроцессоры, например, SCSS, SASS и другие. К и так не всегда понятным с первого взгляда селекторам добавляются переменные, миксины и самое страшное - вложенности!

Если вы наконец разобрались с тем, что описано в стилях, то нам предстоит разобраться еще в том как эти стили применяются. К сожалению, здесь тоже работает то же соотношение: разобраться в стилях тем сложнее, чем больше файл со стилями и чем больше в этих стилях используется различных наворотов.

Проблем добавляет еще и то, что иногда по названию класса элемента очень трудно сказать о том, что это за элемент вообще, как он выглядит и какое место занимает в интерфейсе. Для решения этой проблемы когда-то была придумана методология БЭМ. Многие люди считают ее устаревшей и я, честно признаться еще полгода назад считал так же. Однако, нужно просто понять суть и вы тут же измените свое мнение! На самом же деле БЭМ не только про нейминг, как могло бы показаться, он про логику разбиения интерфейса на составные части, называемые БЭМ сущностями, а также их переиспользование.

Если следовать БЭМ методологии и некоторому соглашению о разбиении файлов исходного кода, можно прийти в утопический мир будущего, где почти всегда в ОДНОМ файле стили для ОДНОГО элемента, а читая код не возникает примерно такой реакции:

Но эта статья на самом деле не совсем про БЭМ. Что если я скажу вам, что даже с использованием вышеописанных практик есть место для улучшений опыта разработки?Именно об этом я и предлагаю сегодня поговорить.

Идея

Вы наверное знаете что такое css-loader и как он позволяет работать с CSS модулями. Если же это не так, то позвольте показать что это такое на примере React компонента:

import styles from './Button.css';

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

Удобно, неправда ли? Вы буквально импортируете класснеймы и привязываете их к нужным элементам в интерфейсе.

Если разработка ведется с использованием БЭМ методологии, то это может выглядеть примерно так:

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>
  );
}

В БЭМ такие сущности называются модификаторами. Обычно, их используют, чтобы задать определенный вид элементу. В примере выше кнопка могла бы менять цвет в зависимости от того, какой у нее type.

Также, нетрудно догадаться, что для работы с модификаторами нам необходим некий вспомогательный инструмент, чтобы не заниматься конкатенацией классов вручную. В примере выше в качестве такого инструмента выступает npm пакет classnames.

Подождите! Но ведь если у нас есть конкретные правила именования не можем ли мы сами написать функцию по аналогии с cls, которая могла бы включать определенные модификаторы в зависимости от передаваемых опций. Давайте попробуем:

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>
  );
}

Выглядит круто! Но неудобно, что нужно повсюду таскать за собой cls функцию. К тому же, очень трудно предусмотреть все сценарии применения такой функции. Например, Если БЭМ модификатор булевый, то значение модификатора true можно опустить и использовать просто имя, например Button_disabled.

Ну что ж, встречайте!

Реализация

Для начала просто посмотрите небольшое демо:

По сути все то, о чем я писал выше объединено воедино, а сверху еще и добавлена поддержка TypeScript.

Все это называется functional BEM и вы можете узнать о проекте подробнее здесь https://github.com/yungvldai/fbem. Все пакеты @fbem являются open-source проектами и распространяются под лицензией MIT, а это значит, что вы можете использовать их в своих проектах прямо сейчас!

В основе проекта лежит специальный лоадер @fbem/css-loader для webpack, который позволяет импортировать из CSS файлов специальные БЭМ-функции. У БЭМ функции всегда два аргумента: объект модификаторов, где ключ - имя модификатора, а значение - его значение; второй - массив миксов (термин из методологии). Проще говоря, это просто массив строк, которые будут добавлены в конец результирующего класса.

@fbem/css-loader очень схож с css-loader (и на самом деле его форк) и имеет почти тот же набор опций и функционал. Вы также можете использовать его с различными препроцессорами с помощью чейнинга лоадеров в конфиге webpack (но подумайте действительно ли они вам нужны 😏).

Как я писал выше, с CSS гораздо удобнее работать, когда он логично разбит на несколько файлов. В идеале в одном файле должны быть стили только для одного DOM элемента (конечно, есть сложные сценарии, когда по ховеру стили должны применяться к ребенку, но таких случаев сильно меньше, чем случаев, когда вам нужно просто применить какие-нибудь стили без всякой логики).

Для этих целей в @fbem предусмотрена специальная функция compose в пакете utils. Эта функция позволяет комбинировать несколько БЭМ-функций в одну:

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'

Заключение

В этой статье я постарался показать метод (и инструменты для реализации) организации стилей в проекте. Больше информации о @fbem вы сможете найти на странице проекта на Github. Я надеюсь Вам было интересно узнать о моих наработках, а также надеюсь Вы поделитесь этой статьей с кем-нибудь 😉.

Спасибо!

P.S. Этот блок написан с использованием @fbem.

Я начал вести блог вместо дневника практики в университете. Потом мне просто понравилось писать статьи на разные темы. Чаще технические. Здесь Вы можете найти мой старый блог. Сейчас я хочу немного сменить формат, поэтому я создал новый блог (этот).

Если у Вас есть какие-либо предложения, жалобы или пожелания, пожалуйста, пишите на me@vladivanov.me.