DEV Community: Aleksei Berezkin

Typique — A zero-runtime CSS-in-TS library that doesn’t fight RSC

Aleksei Berezkin — Wed, 07 Jan 2026 07:20:24 +0000

GitHub repo: https://github.com/aleksei-berezkin/typique/

It all started with React Server Components (RSC). Before they entered the picture, most CSS-in-JS libraries lived peaceful lives: once you wired them into a framework, things mostly just worked. RSC changed that landscape by drawing a hard, non-negotiable boundary between client and server components — a line that only zero-runtime solutions were allowed to cross. This should have been their golden age, right?

It wasn’t.

Instead, it became clear that “supporting every major bundler” means chasing a target that never stands still. Despite extraordinary dedication from maintainers, projects like Vanilla Extract and Linaria are overwhelmed by integration and compatibility issues. The most sobering moment for me was seeing Pigment CSS — a project many believed in, backed by MUI’s expertise — being paused for exactly the same reasons.

Digging deeper didn’t bring relief; it only exposed deeper layers of the problem. Over time, it started to feel like this wasn’t something that could be fixed by integrating more tightly with bundlers. The solution had to come from a different direction — something fundamentally orthogonal to bundlers themselves.

What bundlers already understand

Every modern frontend toolchain already has support for one thing:

It works everywhere, across bundlers and build pipelines.
It magically vanishes from the output without effort.
It requires no extra parsing or transformation.

That thing is TypeScript types.

This observation is the foundation of Typique. Styles live in the type system, while only what truly belongs at runtime — class names and CSS variable names — exists as plain constants. By the time your code reaches a bundler, everything is already in its final, ordinary TypeScript form. Removing types is not Typique’s responsibility; bundlers have been doing that part reliably for years.

What Typique is

Typique is not a conventional library that processes your code after it’s written. Instead, it works as tooling that collaborates with you while you write styling code, guiding you toward correct CSS and unique names. Technically, it’s a TypeScript plugin that does two things:

It integrates with your IDE to provide completion, validation, and quick fixes for class and CSS variable names.
It uses data TypeScript has already parsed and evaluated to read types and emit plain CSS.

This is what sets Typique apart from previous approaches. There are no bundler plugins, no framework hooks, and no fragile integration layers — just TypeScript and an IDE with a proper language service support, such as VS Code or WebStorm. Everything else follows naturally from that.

The workflow

After setup, it usually goes like this. You create a variable that follows the naming conventions, and Typique steps in: via auto-completion it suggests a unique name and inserts the necessary syntax to start writing your CSS:

Next, you define the CSS itself, which may end up looking like this:

import type { Css } from 'typique'
import { space } from './my-const'

const titleClass = 'title-1' satisfies Css<{
  paddingTop: `calc(2 * ${typeof space}px)`
  '& > code': {
    backgroundColor: '#eee'
  }
}>

By the moment you finish typing it, the CSS file is already generated. You can immediately include it in your HTML template, entry point, or root component:

<html>
<head>
  ...
  <link href="./typique-output.css" rel="stylesheet">
</head>
...
</html>

Validation

If a classname doesn’t match its context or collides with an existing one, Typique underlines it and suggests a fix:

Less boilerplate in TSX

In TSX, you don’t even need to introduce a separate constant. Classnames can be written directly in class / className props, with the same completion and validation:

export function Button() {
  return <button className={ 'button' satisfies Css<{
    //                        ^
    //           Completion appears here
    border: 'none'
    padding: `calc(${typeof space}px * 2)`
  }> }>
    Click me
  </button>
}

CSS vars

CSS variables work the same way as classes: you declare a variable following the conventions, get a suggested name via completion, and then reuse it both in styles and at runtime:

import type { Css, Var } from 'typique'

const sizeVar = '--size' satisfies Var
//              ^
// Completion appears here
const roundButtonClass = 'round-button' satisfies Css<{
  //                     ^
  //        Completion appears here
  [sizeVar]: 32
  borderRadius: `calc(${typeof sizeVar} / 2)`
  height: `var(${typeof sizeVar})`
  width: `var(${typeof sizeVar})`
}>

What’s more?

There are many small features that smooth out the workflow: array and object notation, fallbacks, command-line generation, and more. See the full documentation in the README.

Tradeoffs

Solving hard problems usually means introducing new constraints at a different level. In practice, it’s a matter of believing that the new problems are smaller than the old ones — and in this case, I do.

Editor-centric

Typique works well in VS Code and mostly well in WebStorm. In theory, it should work in any IDE that relies on the TypeScript language service, since that’s exactly where Typique plugs in. In practice, less common IDEs may have corner cases or rough edges.

TypeScript-aligned

Because name uniqueness is scoped to a TypeScript project, using Typique requires a basic understanding of what a TypeScript project actually is (here’s a short reminder), and how a workspace may be split into multiple TS projects. Files that belong to an ambiguous project can cause issues — though there are well-established ways to handle this.

Explicit syntax

To stay bundler-independent, Typique needs three things to exist explicitly in your code:

the styles,
the class or CSS variable name,
and the syntactic glue that connects them.

Most previous CSS-in-JS/TS tools only require the first one, so Typique’s syntax can look verbose by comparison. It is more explicit — but that explicitness is intentional, and not necessarily final. I believe that there’s room for refinement here, especially with community feedback.

AI-friendliness

Typique plays well with AI-assisted completion tools such as Copilot or Windsurf. If they guess a class or CSS variable name incorrectly, fixing it is trivial — Quick Fixes handle that immediately.

With agent-generated code, things look different. When an agent touches dozens of files at once, applying Quick Fixes manually doesn’t scale. The obvious next step here is a CLI tool that scans the project and fixes all invalid names in one pass — something agents could run periodically to clean things up.

Final thoughts

I didn’t expect Typique to turn into this, to be honest. What started as a thought experiment ended up as a full, production-ready tool — with real constraints, real tradeoffs, and real users in mind.

That said, it’s still early. The core is here, the hard parts are solved, but how this project evolves should be shaped by feedback, not guesses. If you’re curious, skeptical, or excited — all of that is useful. Some possible next steps are outlined in the Plans section, but none of them are set in stone.

If you’re thinking about using Typique in your project and want to talk it through, I’m very open to that. Early adopters tend to influence projects the most — and I’d like this one to grow in the right direction.

Thanks for reading — and for making it this far.

Cover artwork by FONG on Unsplash

Stop Memorizing, Start Scripting: My Journey to cli-bits

Aleksei Berezkin — Tue, 16 Sep 2025 04:58:03 +0000

Photo by Gabriel Heinzer on Unsplash

For as long as I can remember as a developer, I’ve been told:

Master the command line — it unlocks a whole new level of productivity.

I always neglected that advice, thinking it was meant for people with extraordinary memory. How can a normal person memorize all the ls arguments? How do you remember the order of parameters in find? And how on earth do you get used to the quirky syntax of bash?

About a year ago, I read The Pragmatic Programmer, 20th Anniversary Edition, which once again strongly urged me to master the command line. Since I otherwise liked the book, I decided to give the shell one more try. Quickly I discovered two fascinating things that completely changed my attitude toward it:

You don’t have to memorize everything. Instead of fixating on specific commands, focus on your workflow. What routine operations do you repeat day to day? Maybe you’re searching for certain files, or opening a browser with a specific URL. Script that once, and forget the internals.
You don’t have to learn bash syntax. Write your scripts in your favorite language. These days most languages can run in interpreter mode with just a proper shebang line. If your language of choice doesn’t support it — compile your utilities instead.

Under the impression of these two discoveries, I started building a small collection of scripts I use in my everyday work — cli-bits. I’m happy to share it. Use it as inspiration to create your own scripts; and if you happen to find some of mine useful as they are, that would make me even happier. Let’s see what’s inside!

Note: The utilities are written primarily for macOS, but many should also work on Linux. The JS scripts may also run on Windows, though they haven’t been tested there.

gitb — print the current Git branch

Trivial yet very useful — this was the first script I wrote for the collection. I use it as a part of pipelines, like pulling from the corresponding remote branch:

gitb | xargs git pull origin
# Or:
git pull origin $(gitb)

youtrack — open a bug tracker issue

I use YouTrack a lot. One day I realized I kept typing YouTrack URLs by hand, composing them from https://youtrack.jetbrains.com/issue/ and the current feature branch name, which is named after the issue. So I wrote the youtrack command which automates this for me:

~/my-project $ gitb
ABC-1234
~/my-project $ gitb | youtrack

The util reads from stdin, extracts the issue name, and opens the corresponding URL — in this case https://youtrack.jetbrains.com/issue/ABC-1234. Of course, the same approach can be applied to GitHub, Jira, or any other bug tracker.

lastDown — print the N most recently downloaded files

Downloading files has always been a mess for me. I had to remember the names and paths of my downloads, but if I chose a destination each time, it interrupted my browsing and I lost track of why I was on the page in the first place. After years of this hassle, I adopted the following approach:

Always download to the default folder (~/Downloads on most systems)
Use scripts to query and move recently downloaded files

lastDown takes care of the “query” part of this routine:

~/Pictures $ lastDown 2
/Users/me/Downloads/PXL_20250404_190924.jpg
/Users/me/Downloads/PXL_20250404_191358.jpg

Looks like I downloaded a couple of photos I took during the Web Developer Day celebration 🙂 Note that the paths are absolute — no relative-path confusion possible.

moveHere — move files to the current directory

This is the second part of the downloading routine:

~/Pictures $ lastDown 2 | moveHere
~/Pictures $ ls
PXL_20250404_190924.jpg   PXL_20250404_191358.jpg

Both files were moved to the current directory — ~/Pictures in this case. The downloading riddle is solved!

trash — move files to the Trash

I’ve always feared rm because of its unforgiving irreversibility. It feels too harsh, especially since most systems already have a Trash bin. Strangely, though, there’s no standard utility to move files there — so I wrote this simple one myself. It supports passing files either as arguments or via a pipe.

~/Pictures $ trash PXL_20250404_*

Using it is much less stressful than rm — any mistake is reversible.

getLine — select line(s) from stdin

I often list a lot of files with ls or find, and sometimes I only need a few of them. I could try to adjust the command arguments, but I don't remember them, so I wrote a getLine util to select lines by number:

~/logs $ ls
log_2025-09-03.log
log_2025-09-04.log
log_2025-09-08.log
log_2025-09-12.log
(...and many more files)
~/logs $ ls | getLine 1
log_2025-09-03.log
~/logs $ ls | getLine 1 3
log_2025-09-03.log
log_2025-09-04.log
log_2025-09-08.log

The indices are one-based to match less -N. Negative indices are supported as well.

lless — select a line and open the file

This is simply a shortcut for getLine + less. The utility interprets the first argument as a line number and passes any remaining arguments directly to less.

~/logs $ ls | lless 2 -S

This opens the 2nd file from the ls listing in less, log_2025-09-04.log in the previous example, passing the -S option which turns off lines wrapping.

today — or tomorrow, or yesterday

It’s a simplified version of date, which outputs the current date, or a date relative to it by a given offset. I use it for organising downloaded logs.

~ $ date
Mon Sep 16 06:50:52 CEST 2025
~ $ mkdir $(today -1) && cd $(today -1)
~/2025-09-15 $ lastDown 3 | moveHere

This moves last three downloaded files to a freshly created 2025-09-15 directory.

codeDebug — open a project in VS Code and debug the TS service

As you probably know, you can open a project with the code command:

~/my-project $ code .

This opens my-project in VS Code. Sometimes I need to debug the TypeScript language service, which requires setting the TSS_DEBUG variable. I found it convenient to script this so I can open a project in TS server debug mode with a single command:

~/my-project $ codeDebug .

Now I'm ready to connect to the node process with the debugger and start exploring TypeScript intricacies.

What's more?

There are some additional commands to enumerate, quote, and search specific files. It’s not rocket science, nor a framework — just small, practical bits I use daily.

I hope you see it the same way now. May this approach save you friction and keep your head clear for actual work!

Setting up partial SSR for a React + TypeScript + webpack app from scratch

Aleksei Berezkin — Fri, 10 Jan 2025 22:27:59 +0000

Artwork: https://code-art.pictures/

Do we really need a manual SSR setup in the era of Next.js and Vite?

It's a fair question. Indeed, in blogs and on social networks, Next.js is definitely the “current thing,” while SSR (server-side rendering) done manually might seem too low-level. However, not every app needs a framework, and even if it does, it might turn out that Next.js doesn't support your favorite CSS-in-JS library. In such cases, we have no choice but to write some SSR manually. Fortunately, it's not that complicated, and I'd be happy to show you how.

Tutorial overview

This tutorial focuses on building a React application and prerendering it with SSR. It uses an initial setup created from this repo, which provides a simple, extensible, and up-to-date React + TypeScript + webpack example. For details on the setup, refer to the previous post in this series.

Full code

The full code for this tutorial is available in this repo. You can copy and paste it to use as is or follow along with the blog post.

Components versions

This tutorial has been tested with the following versions:

Node.js 22
React 19
TypeScript 5.7
webpack 5.97

It should generally work with earlier versions, but some minor adjustments might be needed.

1. What kind of SSR are we doing here?

Broadly, we can define three approaches to implementing SSR in an app:

1.1. No SSR at all

In this approach, the client receives a nearly empty HTML page, typically something like this:

<html>
<head>
  <title>My Blog</title>
</head>
<body>
  <div id="app-root">Loading...</div>
</body>
</html>

The client-side code is responsible for rendering the entire app. A typical entry point might look like this:

const container = document.getElementById('app-root')
const root = createRoot(container)
root.render(<App/>)

1.2. Full SSR

In this approach, the client receives fully rendered HTML. This requires a server that fetches all user-dependent data (e.g., from a database or an API) and renders it. Since static page hosting cannot support this, you need a server worker to handle the rendering.

<html>
<head>
  <title>My Blog</title>
</head>
<body>
  <div id="app-root">
    <h1>My Blog</h1>
    <nav><ul><li><a href="#">Home</a></li>...</nav>
    <main>
      <article class="user-post">
        <h2>A Trip To Venice</h2>
        <p>...</p>
      </article>
      ...
    </main>
    <footer>(c) Me</footer>
  </div>
</body>
</html>

On the client side, you typically perform hydration:

const container = document.getElementById('app-root')
hydrateRoot(container, <App/>)

1.3. Partial SSR

Partial SSR falls somewhere between the first two approaches. Simply put, it involves rendering only the unchanged parts of the page — those that don't depend on the user. This unchanged part may include the app header, navigation, user-unaware menus, footer, and so on. Because the rendered HTML is always the same, it can be served statically.

The partially prerendered HTML page might look like this:

<html>
<head>
  <title>My Blog</title>
</head>
<body>
  <div id="app-root">
    <h1>My Blog</h1>
    <nav><ul><li><a href="#">Home</a></li>...</nav>
    <div class="loader">...</div>
    <footer>(c) Me</footer>
  </div>
</body>
</html>

As you can see, the <main> section with the actual content was not rendered. Instead, a loading indicator is displayed.

The client entry point performs hydrateRoot(), similar to the fully rendered example. The actual content, replacing the loader, is rendered to the page once hydration is complete.

This is the exact kind of SSR we are going to implement.

2. The example

Our example is the traditional React hello-world — a counter with “Increase” and “Decrease” buttons. It features user-dependent data — the current counter value, which it stores in local storage. The app has 2 pages: / and /about — so we can have some fun with the router.

2.1. App

src/App.tsx

import { useEffect, useState } from 'react'
import { Link, Route, Switch } from 'wouter'

export function App() {
  return (
    <>
      <h1>React SSR Demo</h1>
      <Switch>
        <Route path="/"><Index /></Route>
        <Route path="/about"><About /></Route>
      </Switch>
    </>
  )
}

wouter is a replacement for react-router. Not only is it smaller in the bundle, but doing SSR with it is much easier.

src/App.tsx (continuation)

function Index() {
  const [cnt, setCnt] = useState<number | undefined>(undefined)

  useEffect(() => {
    if (cnt == null)
      setCnt(Number(
        localStorage.getItem('my-demo-cnt') ?? '0'
      ))
    else
      localStorage.setItem('my-demo-cnt', String(cnt))
  }, [cnt])

  function update(delta: number) {
    if (cnt != null) setCnt(cnt + delta)
  }

  return (
    <main>
      <p>Counter: { cnt ?? '⏳' }</p>
      <button onClick={() => update(-1)}>Decrement</button>
      <button onClick={() => update(1)}>Increment</button>
      <p><Link href='/about'>About</Link></p>
    </main>
  )
}

Before the effect initializes the cnt, the hourglass emoji is displayed instead of the actual counter. This serves as a loading indicator.

src/App.tsx (continuation)

function About() {
  return <main>An app demonstrating ReactSSR</main>
}

2.2. Entry point

src/entry-client.tsx

import { createRoot } from 'react-dom/client'
import { App } from './App'

const container = document.getElementById('app-root')!
createRoot(container).render(<App/>)

2.3. Template

index.html
The template is shortened; see the full code here

<html>
<head>
  <title>React SSR TS Demo</title>
</head>
<body>
  <div id="app-root"><!--html-placeholder--></div>
</body>
</html>

Note: The comment inside the app root div serves as a placeholder to easily replace it with the rendered app in the SSR step. To retain it during rendering, we need to set removeComments: false in HtmlWebpackPlugin configuration in webpack.config.mjs.

3. Running and building the app

3.1. Running for development

The following script runs the app in development mode:

package.json

{
  "scripts": {
    ...
    "start": "webpack serve --port 3000",
    ...
  }
}

And this is the main view of the app:

3.2. Building for production

The following script builds the app for production. This version is for Linux and macOS:

package.json

{
  "commands": {
    ...,
    "build@webpack": "NODE_ENV=production webpack",
    ...
  }
}

For Windows, the command would be: set NODE_ENV=production && webpack.

After you run it, you will see the generated files in dist. Let's take a closer look at dist/index.html. You'll notice that webpack has inserted the link to the compiled JS file. The <div id="app-root"> remains intact and still contains the comment:

dist/index.html

The file is shortened and formatted for readability

<html>
<head>
  <title>React SSR TS Demo</title>
  <script defer="defer" src="main.202c97ca5eeaf2a49f5a.js"></script>
</head>
<body>
  <div id="app-root"><!--html-placeholder--></div>
</body>
</html>

It's a working build with full client rendering (as described in section 1.1). We can preview it with the following command:

{
  "scripts": {
    ...
    "preview": "serve dist",
    ...
  }
}

The result should look exactly the same as in development.

4. The SSR script

This script reads dist/index.html, renders two pages, / and /about, and outputs them as files:

/ path to dist/index.html (rewrites the file)
/about to dist/about.html

ssr/entry-ssr.tsx

import path from 'node:path'
import fs from 'node:fs'
import { renderToString } from 'react-dom/server'
import { Router } from 'wouter'
import { App } from '../src/App.js'

const indexHtml = String(fs.readFileSync(path.join('dist', 'index.html')))

for (const route of ['/', '/about']) {
  const appHtml = renderToString(
    <Router ssrPath={route}>
      <App/>
    </Router>
  )
  const prerendered = indexHtml
    .replace('<!--html-placeholder-->', appHtml)

  const fileName = `${route === '/' ? 'index' : route}.html`
  fs.writeFileSync(path.join('dist', fileName), prerendered)
}

Notes:

We imported App with the .js extension. This is because we intend to run it in Node.js as an ESM module, which requires extensions for user files. TypeScript understands that .js is used here to correctly resolve the import in the compiled code, and behind the scenes, it substitutes it with .tsx during development.
We use relative directories because we plan to compile the file with tsc. This means the actual path will change, and import.meta.directory will not match the directory of the source file. Relative directories, however, are interpreted in the context of the Node.js working directory, which we intend to run from the project root path.

5. Running the SSR script

Basically, our task is to run the TypeScript file in Node.js. Here are the three most popular options to achieve this:

With ts-node
With tsx
Compile TS to JS and run it as a regular Node.js application

I prefer the last option because it guarantees that your tsconfig.json will be read as is, and it makes fixing problems much easier.

To compile and run, we need the following scripts:

package.json

{
  "scripts": {
    ...
    "build@tsc": "tsc",
    "build@ssr": "node out/ssr/entry-ssr.js",
    ...
  }
}

We also need the following options to be set in tsconfig.json:

"module": "ESNext", "target": "ESNext" — make sure to leave ES syntax and ESM imports unchanged.
"moduleResolution": "bundler" or "nodenext" — in a more complex setup, you might need different resolution settings for bundling and running SSR. For our example, both option will work because they are very similar.
"outDir": "out" — put compiled files in the out directory. Without this setting, TypeScript will put .js files in the src directory, next to .ts(x) sources, which works but reduces the clarity of your directory structure.

Let's compile the SSR script:

npm run build@tsc

Now you can observe that the compiled files have appeared:

/out
  /src
    App.js
    entry-client.js
  /ssr
    entry-ssr.js

We are finally ready to run the compiled SSR script:

npm run build@ssr

If everything runs smoothly, you should observe the following changes in the dist directory:

dist/index.html (updated)
The file is formatted and shortened for readability

<html>
<head>
  <title>React SSR TS Demo</title>
  <script defer="defer" src="main.202c97ca5eeaf2a49f5a.js"></script>
</head>
<body>
  <div id="app-root">
    <h1>React SSR Demo</h1>
    <main>
      <p>Counter: ⏳</p>
      <button>Decrement</button>
      <button>Increment</button>
      <p><a href="/about">About</a></p>
    </main>
  </div>
</body>
</html>

Wow, it seems like it's exactly our application! And it even correctly displays our improvised loading indicator!

dist/about.html
The file is formatted and shortened for readability

<html>
<head>
  <title>React SSR TS Demo</title>
  <script defer="defer" src="main.202c97ca5eeaf2a49f5a.js"></script>
</head>
<body>
  <div id="app-root">
    <h1>React SSR Demo</h1>
    <main>
      An app demonstrating ReactSSR
    </main>
  </div>
</body>
</html>

This page doesn't contain any user data, so it was rendered completely.

5.1. Alternative: running SSR as CJS

If you don't have problems running your SSR script as ESM, just skip this section.

Strictly speaking, our script was already running “mostly CJS” because react-dom is only shipped as CJS as of this writing (early 2025). However, all our scripts were in ESM. This should normally work in a recent Node, but if you run into problems because of this, you may compile and run the scripts as CJS. You need the following changes for this:

Remove "type": "module" from package.json
In tsconfig.json, make the following changes:
- "module": "CommonJS"
- "moduleResolution": "node"
In the build@ssr script in package.json, add the --experimental-require-module flag. This flag requires Node 22. It is needed because wouter is only shipped as an ES module, and to require it into your scripts, you need this flag. The command should look like this:

{
  "scripts": {
    ...
    "build@ssr": "node --experimental-require-module out/ssr/entry-ssr.js"
    ...
  }
}

Now remove the dist directory and rebuild everything. You will probably see a warning in the console saying that loading ES modules with require() is experimental; that is expected as of this writing (2025). The result should be the same: two prerendered pages in the dist directory.

6. Tweaking `src/entry-client.tsx`

Currently, our client is performing a full render even when running against prerendered pages. While this may seem to work fine, it can result in a performance penalty for larger applications.

To address this, we need to adjust the client entry point to use hydrate() for prerendered pages while keeping a full render for development. Here are a few approaches to achieve this:

Create separate entry points for development and production.
In the client entry point, check if the container is empty — use render() if it is and hydrate() otherwise.
Use webpack's DefinePlugin to pass compile-time values to your app.

I prefer the last option because it doesn't overly complicate the setup while making the dev/prod separation explicit.

webpack.config.mjs

// ...
import { default as webpack } from 'webpack'

const prod = process.env.NODE_ENV === 'production'

export default {
  // ...
  plugins: [
    // ...
    new webpack.DefinePlugin({
      IS_PROD: prod,
    }),
  ],
  // ...
}

entry-client.tsx

// ...

declare const IS_PROD: boolean

const container = document.getElementById('app-root')!

if (IS_PROD)
  hydrateRoot(
    container,
    <Router>
      <App/>
    </Router>
  )
else
  createRoot(container).render(
    <App/>
  )

Let's take a look at how the compiled JS looks in development:

main.a5e563be581a740e1cfc.js

const container = document.getElementById("app-root");
if (false)
  {}
else
  (0,react_dom_client__WEBPACK_IMPORTED_MODULE_1__.createRoot)(container).render(
    // ...
  );

As seen, webpack removed the code from the production branch.

And this is how the fragment looks in production:

main.d12874e81a77454f00b2.js
The fragment is formatted for readability

const V = document.getElementById("app-root");
(0, o.hydrateRoot)(V, (0, a.jsx)(A, {
  children: (0,a.jsx)(U, {})
}))

As seen, the minifier replaced the if statement with only the truthy branch body. This ensures that the production build doesn't have any overhead from development.

Congratulations, we’re finally done! 🎉

Hope it wasn’t too hard to follow. You now have a Partial SSR setup that’s lightweight, flexible, and doesn’t rely on frameworks. Thanks for staying with me throughout this journey!

7 Practical Tips to Minimize Your JavaScript Bundle Size

Aleksei Berezkin — Mon, 30 Dec 2024 06:56:24 +0000

Artwork: https://code-art.pictures/

Why Bother?

It might be surprising these days, but internet traffic is still an issue in many scenarios. Mobile networks often have limited data plans, device batteries are not infinite, and, most importantly, the user's attention while waiting for your site to load is limited. That's why bundle size still matters. Here are seven tips for you to consider.

1. Don't Transpile to ES5

In 2020, I was maintaining a promotional app for a local social network. It was a typical React + TypeScript + webpack application targeting ES5. When webpack 5 was released, I decided to upgrade. Everything went smoothly; I monitored error analytics and user feedback, and there was nothing unexpected. Only after a week did I accidentally discover that my bundle contained arrow functions — it was a new webpack feature.

Here's an excellent article about the state of ES5. Key takeaways:

Many libraries already contain ES6+ code, meaning bundles with them are not ES5-compatible.
Most of the world's popular sites are not ES5-compatible — your site might not need it either.
If you are certain you still need ES5 compatibility, you must include the libraries in your build process.

2. Know and Use Modern JavaScript Language Features

Here are some features that allow you to write better and more compact code.

2.1. Generators

Generators are an efficient way to traverse nested structures:

type TreeNode<T> = {
    left?: TreeNode<T>
    value: T
    right?: TreeNode<T>
};

function* traverse<T>(root: TreeNode<T>): Generator<T> {
    if (root.left) yield* traverse(root.left)
    yield root.value
    if (root.right) yield* traverse(root.right)
}

2.2. Private Class Fields

Minifiers know for certain that these fields cannot have external usages, even in exported objects, and are free to shorten their names.

Source

export class A {
  #myFancyStateObject
}

Bundle

export class A{#t}

This won't work, of course, with TypeScript private fields, because the knowledge that they are private disappears once tsc has done its job.

2.3. Modern APIs

Have you heard about Promise.withResolvers() or Map.groupBy()? These APIs are not widely available at the time of this writing, but will be soon. Take a moment to familiarize yourself with them now and be ready to adopt them in a couple of years.

Tip: How to Discover New JavaScript APIs

There are countless blogs and podcasts, but I find the best “newsletters” are new .d.ts files in the TypeScript repository. Just open, for example, es2024.collection.d.ts and enjoy 🙂

3. Avoid Code Duplication

Do you notice the repeated pattern?

const clamp = (min, val, max) =>
  Math.max(min, Math.min(val, max))
const x = clamp(0, v1, a.length - 1)
const y = clamp(0, v2, b.length - 1)
const z = clamp(0, v3, c.length - 1)

Repeated code not only increases the bundle size but also makes it harder to understand what each part does. This often leads developers to write new code instead of identifying and reusing existing utility functions, further bloating the bundle.

There's already a wealth of excellent material on this topic, so rather than retelling it, I recommend a classic: Refactoring by Martin Fowler. It covers not only simple examples like the one above but also complex cases such as coupled hierarchies and repeated designs.

Now, let's improve our small example. It seems clamp is often used to limit parameters to array index ranges, so we can create a shortcut:

const clampToRange = (n, {length}) =>
  clamp(0, n, length - 1)
const x = clampToRange(v1, a)
// ...

This change makes it explicit that n is probably intended to be an integer, which isn't currently checked. It also highlights an unhandled edge case: empty arrays. By making this small deduplication, we also discovered two potential bugs 🙂

4. Avoid Overengineering

I don't remember the exact source of this saying, but I think it's spot on:

Overengineering is solving a problem that you don't have.

In the world of web development, I've observed two main types of overengineering.

4.1. Over-generalization

Consider this code. Paddings are multiples of 4px, and background colors are shades of blue. This is probably not a coincidence, and if so, it could indicate possible duplication. But do we really have enough information to extract the generic Button component, or are we overengineering?

CSS

.btn-a {
    background-color: skyblue;
    padding: 4px;
}
.btn-b {
    background-color: deepskyblue;
    padding: 8px;
}

JSX

<button className='btn-a' onClick={handleClick}>
    Show
</button>
// ...
<button className='btn-b' onClick={handleSubmit}>
    Submit
</button>

This advice does somewhat conflict with “Avoid duplication.” Over-deduplicating code can lead to overengineering. So, where do you draw the line? Personally, I use the magic number “3”: once I see three places with a similar pattern, it might be time to extract the generic component.

In the case of our blue buttons, I believe the best solution would be to use CSS variables, at least for padding, rather than creating a new component.

4.2. Using Improper Framework

Yes, I'm talking about what we love — Next.js, React, Vue, and so on. If your app doesn't involve a lot of interactivity at the level of DOM elements, or isn't dynamic, or is very simple, consider other options:

Static site generators — you can start with some curated lists.
- Beware: some of them use React or other frameworks under the hood. If your goal is bundle minimization, try something different.
Content management systems, like WordPress.
Vanilla — especially useful in two cases:
- The app is very simple.
- The app doesn't manipulate much DOM but instead, for example, paints something on a canvas. I have a project exactly like this.

5. Avoid Dated TypeScript Features

The current goal of TypeScript is mainly type-checking JavaScript, but it wasn't always this way. Back in the pre-ES6 days, there were many attempts to create “better JavaScript,” and TypeScript was no exception. Some features date back to those early days.

5.1. Enums

Not only are they difficult to use properly, but they also transpile into quite verbose structures:

TypeScript

enum A {
  x, y
}

JavaScript

var A;
(function (A) {
    A[A["x"] = 0] = "x";
    A[A["y"] = 1] = "y";
})(A || (A = {}));

The official TypeScript Handbook recommends using simple objects instead of enums. You may also consider union types.

5.2. Namespaces

Namespaces were a pre-ESM modules solution. Not only do they increase the bundle size, but since namespaces are intended to be global, it becomes really hard to avoid naming conflicts in large projects.

TypeScript

namespace A {
  export let x = 1
}

JavaScript

var A;
(function (A) {
    A.x = 1;
})(A || (A = {}));

Instead of namespaces, use ES modules.

Note: Namespaces are still useful, however, for writing type definitions for global libs.

6. Don't Neglect Small Optimizations

Each of these small tricks can save you several to dozens of bytes in the bundle. If applied consistently, they can bring a visible result.

6.1. Use Truthy / Falsy Properties

For example, an empty string is falsy. To check if it's defined and non-empty, you can simply write:

if (str) {
  // str is non-empty
}

6.2. Allow Non-strict Comparison Sometimes

I believe using == to coerce null to undefined, or vice versa, is totally justified.

if (value == null) {
  // value is null or undefined,
  // but not 0 or ''
}

6.3. Use Nullish Coalescence, Logical OR, and Default Parameters to Substitute Default Values

// Replaces null, undefined and '' with 'e'
const v1 = str || 'e'

// Replaces null or undefined with ''
const v2 = str ?? ''

function doSth(str = '') {
  // str is '' if not passed
}

6.4. Use Arrow Functions for One-liners

Instead of this:

function randomInt(bound) {
  return Math.floor(Math.random() * bound))
}

Write this:

const randomInt = bound =>
  Math.floor(Math.random() * bound)

6.5. Don't Use Classes for Very Simple Objects

Instead of this:

class User() {
  #name: string
  constructor(name: string) {
    this.#name = name
  }
  getName() {
    return this.#name
  }
}

Write this:

type User = { name: string }
const user = {
  name: 'John Doe'
} satisfies User

You may also freeze the object to protect its properties from changes.

7. Regularly Inspect Bundles

For each bundler, there are tools to visualize its content, such as webpack-bundle-analyzer for webpack and vite-bundle-analyzer for Vite. Tools like these help you identify common issues with your bundle:

A library takes up a disproportionate amount of space — maybe it's time to migrate or upgrade?
Two similar libraries are used in different parts of your project — can you consolidate and use only one?
A large file exists in your bundle but is only accessed by a page that 0.5% of users visit (e.g., a license text) — perhaps you can partition the bundle using dynamic import()?

In addition to these tools, it's a good idea to occasionally read through bundles manually to spot irregularities. For example, you might find ES5 helpers in an ES6+ bundle or CJS helpers in an ESM project due to TypeScript misconfiguration. These problems might not be caught by automated tools but can still increase loading time and potentially cost you your most valuable asset — the user's attention.

Thank you for reading. Happy coding!

Fluent Streams: A Library for Rich Iterables Manipulation

Aleksei Berezkin — Fri, 13 Dec 2024 05:59:45 +0000

Artwork: https://code-art.pictures/

Imagine a library that:

Like Ramda, provides many useful functions for iterables manipulation
Reads familiar, like standard Array iterative methods
Doesn't try to replace JavaScript built-ins like Array, Set, or the iteration protocol
Like Java Streams, includes Optional to clearly distinguish between “no value” and “undefined as a value”
Is compact in terms of bundle size

I couldn't find one that fits all these needs, so I created my small library — fluent-streams.

Talk is Cheap. Show Me the Code

Top 3 Words in a Text

const words = ['Lorem', 'ipsum', /* ... */]

stream(words)
  .groupBy(word => word.toLowerCase())
  .map(([w, {length}]) => [w, length])
  .sortBy(([, length])  => -length)
  .take(3)
  .toArray()

// => ['ut', 3], ['in', 3], ['dolor', 2]

Coprime Integers

// Endless stream of 2..999 integers
const randomInts = continually(() => 
  2 + Math.floor(Math.random() * 998)
)

randomInts
  .zip(randomInts)
  .filter(([a, b]) => gcd(a, b) === 1)
  .distinctBy(([a, b]) => a < b ? `${a},${b}` : `${b},${a}`)
  .take(10)

// => [804, 835], [589, 642], [96, 145], ...

Streams can be endless, as shown, but you can limit them to the first n items using the take(n) method
A stream can be reused multiple times, even in parallel. This is because streams are stateless and only store a reference to the input. The state is created only when the stream spawns an iterator.

Generate a Deck of Cards

const deck = streamOf('♠', '♥', '♣', '♦')
  .flatMap(suit =>
    streamOf<string | number>(
      'A',
      ...range(2, 11),
      'J',
      'Q',
      'K'
    ).map(rank => `${rank}${suit}`)
  )

// => 'A♠', '2♠', '3♠', ...

And Play Hold'em Poker!

const playersNum = 2

const [flop, turn, river, ...hands] = deck
  .takeRandom(3 + 1 + 1 + playersNum * 2)
  .splitWhen((_l, _r, i) =>
    i === 2             // flop
    || i === 3          // turn
    || i >= 4           // river
      && i % 2 === 0    // ...players' hands
  )

// flop = ['3♦', '9♣', 'J♦']
// turn = ['4♣']
// river = ['7♦']
// hands = ['J♠', 'Q♥'], ['10♠', '8♥']

First player has a pair of Jacks on the flop, while the second player gets a straight, but only on the river. Who will win?

This Must Be Cheap

Everything above can be achieved with only native data structures. However, code written with Fluent Streams reads nicer. While making code more readable is a perfectly valid goal, the cost of achieving it should be low in terms of cognitive load, bundle size, and performance.

And that’s exactly the case with Fluent Streams! Here’s why:

No learning curve: The API feels familiar, resembling standard Array methods. It’s easy to add and just as easy to remove.
No reinvention: The library doesn’t create new data structures or protocols — it builds on JavaScript’s already robust features.
Minimal bundle impact: At just near 9 kB minified, it’s lightweight. If your project already includes React and its satellite libraries, which weigh hundreds of kilobytes, this addition is hardly noticeable.
Lazy processing: The library processes items lazily, which can reduce memory usage and improve efficiency in long pipelines by avoiding unnecessary intermediate data copying.

Caveats

The library is shipped untranspiled to ES5. This decision is driven by the desire to maintain a small bundle size, which is achieved by leveraging ES6+ features that enable iteration with very concise code — most notably generators. However, only widely supported language features are utilized.

If you are still transpiling to ES5, you can use the library by transpiling it yourself and adding polyfills. Be aware, though, that this will increase the bundle size, so it’s not recommended. Instead, this might be the perfect occasion to revisit your build configuration and embrace modern JavaScript features.

Have Fun Coding!

Migrating from react-router to wouter

Aleksei Berezkin — Fri, 29 Nov 2024 10:45:08 +0000

Artwork: https://code-art.pictures/

Why migrate to wouter?

react-router adds about 30 kB (minified) to your bundle, while wouter requires less than 4 kB. Although the react-router team has made significant efforts in version 7 to optimize its bundle size, it still feels excessive if your primary task is simply switching between a few routes.

Moreover, implementing server-side rendering (SSR) with wouter is straightforward. In contrast, with react-router v7, SSR is only easy when you use it as a framework. If you prefer to use it as a library, the process is unclear since it's not documented — an omission that's both surprising and frustrating, to be honest.

Why stay with react-router?

react-router is a mature library with a large and active community. If your project involves complex routing scenarios, react-router is more likely to provide the tools and support you need.

Hint: If you decide to stick with react-router, be sure to upgrade from v6. Version 7 is about twice as efficient in terms of bundle size.

1. Updating deps to wouter

npm uninstall react-router react-router-dom
npm i wouter

If you're already on react-router v7, you probably don't have react-router-dom.

2. Updating Routes to Switch

Update imports
Change <Routes> to <Switch>
In your routes, move elements from element property to <Route>'s children

Before

import { BrowserRouter, Route, Routes } from 'react-router'

function App() {
  return (
    <Routes>
      <Route path='/' element={<Index/>} />
      ...
    </Routes>
  )
}

After

import { Route, Switch } from 'wouter'

function App() {
  return (
    <Switch>
      <Route path='/'>
        <Index/>
      </Route>
      ...
    </Switch>
  )
}

3. Updating Links

Just update imports. wouter has the same API here

Before

import { Link } from 'react-router'

After

import { Link } from 'wouter'

4. Updating navigation

Update imports
Change useNavigate() to useLocation()
Change navigate() to setLocation()

Before

import { useNavigate } from 'react-router'

function MyComponent() {
  const navigate = useNavigate()

  function navToAbout() {
    navigate('/about')
  }

  // ...
}

After

import { useLocation } from 'wouter'

function MyComponent() {
  const [, setLocation] = useLocation()

  function navToAbout() {
    setLocation('/about')
  }

  // ...
}

5. Implementing SSR

I don’t know how to implement SSR with react-router v7 🙂 That’s why, in this step, we’ll implement it from scratch using wouter — it’s surprisingly simple. All you need to do is wrap your app in a <Router> component:

entry-server.js

import { renderToString } from 'react-dom/server'
import { Router } from 'wouter'

function prerenderApp() {
  return renderToString(
    <Router ssrPath='/'>
      <App />
    </Router>
  )
}

entry-client.js

import { hydrateRoot } from 'react-dom/client'
import { Router } from 'wouter'

hydrateRoot(
  document.getElementById('app-root'),
  <Router>
    <App />
  </Router>
)

We are done!

Now run your favorite bundle analyzer (e.g., webpack-bundle-analyzer or vite-bundle-visualizer) and enjoy the results!

[ShowDEV] Speech exercises for kids / [RU] Логопедические упражнения для детей

Aleksei Berezkin — Wed, 24 Jul 2024 11:51:46 +0000

https://aleksei-berezkin.github.io/hard-letters/

My kid doesn't speak Russian, anything interesting for me here?

Of course! Please see the last section

Immigration Hurdles

You probably know that after the tragic events that began in February 2022, many people fled their home countries. This includes me and my Russian-speaking colleagues.

Immigration is challenging; with kids, it's even harder. You have to do many things by yourself that you normally delegated to someone else. For example, speech professionals usually help kids with correct pronunciation, but it's hard to find such professionals in another country.

The Problem with Hard Letters

Wise people removed hard letters from their languages. There are no rolling R's or hard L's in English, French, and German. Unfortunately, they exist in Russian, and many kids struggle to learn them. Besides the lack of speech therapists, there isn't enough speech practice to reinforce learning. There are some practice videos on YouTube, but we exhausted them very quickly.

One day, after watching a video for the 10th or 20th time, my son told me he was tired of repeating the same words again and again and asked if we could just watch some cartoons instead. At that moment, I thought: maybe I can use my web development skills to help.

What Do Kids Need for Practice?

At first, I thought of generating videos with MidJourney or similar tools. However, I quickly realized that was overkill. We don't even need a video here. What my son needs is just a simple slideshow with nice photos and someone reading the words aloud. Nice background music would add a playful feeling. After a very short Google search, I found that all these components exist and are free.

The Components

Synthesized Speech

It's not new, but I didn't use it before. Making your browser speak is very simple:

const msg = new SpeechSynthesisUtterance(text);
msg.lang = 'ru-RU'
msg.pitch = 1.1   // 0.1 to 2
msg.rate = 0.85   // 0.1 to 10
// Depending on your system you may have multiple voices
msg.voice = speechSynthesis.getVoices()[0]
msg.volume = 1
window.speechSynthesis.speak(msg);

Make sure the document is focused to hear the sound. This is always the case if the user has to click or tap something before the browser starts speaking.

Pixabay — Often Overlooked Free Pics Service

Of course, I first tried famous services like Unsplash and Pexels. However, they have very strict initial limitations per access token — 50 and 200 API requests per hour, respectively. After googling a bit more, I found Pixabay. Its collection is also impressive, with about 4 million photos, and the initial limit is 100 API requests per minute.

Background Music with SoundCloud

You just insert an iframe into your HTML — and that's it! You don't even need to keep its original size. Its layout is responsive and adapts to smaller sizes.

Their API is glitchy, though. I needed to add some workarounds to make it work consistently. And make sure the track or playlist you selected is free; otherwise, there will be a delay before it starts to play.

Finally

I never thought that it was possible to do something for my kids with my web development skills. This app is not rocket science; it's trivial. However, it's one of the most satisfying things I've ever done. Watching my son's speech progress is priceless.

Now I'm wondering how many more things are yet possible!

Images used in this post

Creating a Material Spinner with Pure and Simple CSS

Aleksei Berezkin — Sun, 23 Jun 2024 19:47:28 +0000

Everyone has seen it hundreds, if not thousands of times, and it seems like this loader is very easy and natural. However, if you try to create it from scratch, you'll find it surprisingly challenging. The first problem is simply understanding the motions involved.

Rotation and... what?

After observing it for a while, you may notice there are two motions, simple rotation, and something weird happening with the arc ends. Let's remove the first and slow down the second:

Much clearer now. First, the arc's beginning moves forward, then its end catches up with the beginning. But how is this possible to achieve?

SVG circle and `stroke-dasharray`

The solution relies on the SVG stroke-dasharray property. When applied to an SVG element, such as <circle>, it converts the solid stroke into a dashed one. For example, stroke-dasharray: 10px 20px 30px 40px means the first dash is 10px, the next is a 20px gap, then a 30px stroke, then a 40px gap. This pattern repeats until the full circle is complete:

You might have noticed a usability issue, though: the value items are the arcs lengths in user-space pixels. It can be in some other CSS unit such as % or em, but this is still obscure because we humans measure arcs and angles in degrees. We understand 90° but not 90px.

Fortunately, it's easy to fix this issue by calculating the --1deg custom property, which represents the length of one degree, and using it as a unit:

circle {
  --r: 47px;
  --1deg: calc(2 * pi * var(--r) / 360);

  stroke-dasharray:
    calc(40 * var(--1deg))
    calc(80 * var(--1deg));
}

The result resembles the trace of helicopter blades:

We now have a convenient tool to define arc ends in human-readable units — degrees. The next picture shows the animation phases of the spinner and their corresponding arc values.

Conventions:

Gaps are shown in light gray; these are not actual gaps but are used to make them visible.
The first and last arcs are not to scale, they are slightly more than 2° for the same reason.

Now we are ready to write it in CSS. Note the additional leading zero, which is needed to skip the initial stroke and start with a gap.


@keyframes dash-anim {
  0% {
    stroke-dasharray:
      0
      0
      calc(2 * var(--1deg))
      calc(358 * var(--1deg));
  }
  50% {
    stroke-dasharray:
      0
      calc(35 * var(--1deg))
      calc(290 * var(--1deg))
      calc(35 * var(--1deg));
  }
  100% {
    stroke-dasharray:
      0
      calc(358 * var(--1deg))
      calc(2 * var(--1deg));
  }
}

circle {
  animation: dash-anim 5000ms ease-in-out infinite;
}

This renders the already familiar slow arc animation:

Fix the jumping arc, or tolerate it?

Because the arc cannot cross the origin of stroke-dasharray, there's a noticeable “jump” between 100% and 0% phases. It is theoretically possible to fix this:

@keyframes dash-anim {
  /* ... */
  100%: {
    /* ... */
    transform: rotate(2deg);
  }
}

Unfortunately it doesn't work very smooth in Firefox — there is annoying blinking in the 0%/100% phase. However, a 2° jump is not that significant. The jump is barely noticeable at full speed and can be safely tolerated.

Implementation notes

stroke-dashoffset

If you inspect the MUI implementation, you will notice they use a 2-component stroke-dasharray together with a negative stroke-dashoffset. The latter effectively functions similarly to a leading zero in stroke-dasharray, creating the leading gap. However, I'm using stroke-dasharray with a leading zero because I find it easier to understand.

The following fragment shows the same animation rewritten with stroke-dashoffset, like in MUI:

@keyframes dash-anim {
  0% {
    stroke-dasharray:
      calc(2 * var(--1deg))
      calc(358 * var(--1deg));
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 
      calc(290 * var(--1deg))
      calc(358 * var(--1deg));
    stroke-dashoffset: calc(-35 * var(--1deg));
  }
  100% {
    stroke-dasharray: 
      calc(2 * var(--1deg))
      calc(358 * var(--1deg));
    stroke-dashoffset: calc(-358 * var(--1deg));
  }
}

You may also notice that they do not bother to adjust the stroke-dasharray values that exceed the full circle. For example, in the 50% phase, only 35° of a 358° gap will be visible, and everything else will be trimmed away.

Precalculated values

The MUI spinner doesn't use CSS variables and calculations — all values are precalculated. You may do the same if you target older browsers. The following code represents the same animation given r: 47px.

@keyframes dash-anim {
  0% {
    stroke-dasharray: 2px 293px;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 238px 293px;
    stroke-dashoffset: -29px;
  }
  100% {
    stroke-dasharray: 2px 293px;
    stroke-dashoffset: -293px;
  }
}

Totally cryptic!

Material Web Components

The official Google implementation of the Material spinner is much more sophisticated. It doesn't contain any SVG; instead, its arcs are made with two empty containers using border-radius: 50%, along with four rotation animations. This complexity pays off — the result looks very clean and smooth, and it runs perfectly in all browsers.

And finally

It's time to complete our spinner: speed it up, reintroduce rotation, and let's spice it up with a blurry shadow and fancy colors!

Show DEV: Interactive Mandelbrot Set Visualization

Aleksei Berezkin — Sat, 13 May 2023 05:59:23 +0000

https://mandelbrot.run/

Source: https://github.com/aleksei-berezkin/mandelbrot

The Mandelbrot set is one of the best known mathematical fractals. With very simple equations, it plots convoluted and beautiful curves, which is why visualizing it is a popular programming task. However, don't be misled — the seemingly trivial formulas hide a wealth of complexity 😉 It is the story of striving for performance and precision.

The math

The fractal is plotted on a complex plane. Each pixel color depends on if/when the $z$ diverges:

\begin{align} z_0 &= 0 \newline z_{n+1} &= z_n^2 + x_0 + {y_0}i, \end{align}

where $x_0$ and $y_0$ are pixel coordinates on a screen. We may rewrite $(2)$ to more familiar real numbers, having substituted $z_n = x_n + y_ni$ :

\begin{align} x_{n+1} &= x_n^2 - y_n^2 +x_0 \newline y_{n+1} &= 2x_n y_n + y_0 \end{align}

The $z$ is said to diverge when the following condition is met:

\begin{align} |z_n| &> 2 \newline \iff \sqrt{x_n^2 + y_n^2} &> 2 \newline \iff x_n^2 + y_n^2 &> 4, \end{align}

because subsequent items will inevitably grow to infinity. The pixel color is coded in the following way:

If the $z$ never diverges, the color is black
If the $z$ diverges at iteration $n$ , the color is some function of $n$

So, let's write some JavaScript?

It's quite easy to write several dozen simple JS lines to get it working. But if you try, you quickly discover where the real problems are:

When zooming into the set, the required number of iterations rapidly grows, causing your animation to first lose smoothness and then freeze
At a certain level of zoom, the JS number (64-bit floating point) becomes too imprecise, and the picture becomes pixelated

How to approach these? Let's see!

1. Parallel workers

These days, even inexpensive smartphones have several CPU cores, and utilizing them for computation-heavy tasks is a must. For web-based tasks, you can take advantage of the multiple CPU cores by running parallel workers. Additionally, there is an API that suggests the optimal number of workers to use.

For my case, I divide the whole picture into approximately 8*workersNumber rectangles, and shuffle them for better load balance. This picture shows different workers' tasks with different hues:

2. From JS to Webassembly

Webassembly (WASM) is the format for binary instructions that browsers can execute very effectively. You can write WASM programs with an assembly-like language or compile to WASM from a high-level language. I chose AssemblyScript, which is very similar to JS and TS and is well documented.

As a low-level format, raw WASM lacks convenient data structures such as arrays and even strings, and requires manual memory management, which can be quite complex. Much of WASM compilers can emulate these features for you, but of course, that comes at a cost — each additional feature consumes valuable CPU. That's why, if you strive for performance, it's better not to use these features. That's exactly what I did. Here's a function which reads the rendered value of a pixel directly from memory:

function loadRendered(xy: u64): u32 {
  const y = (xy >>> 32) as u32;
  const x = xy as u32;
  return load<u32>(4 * (y * canvasW + x));
}

Is it TS? Or maybe C? 🙂

3. From number to arbitrary-precision arithmetic

That's the image of 10^14 zoom when used only 64-bit floating point numbers:

Looks like an UFO trace from early 90s game 🙂

To address this problem we need to extend the width of a number which is known as arbitrary-precision arithmetic. Unfortunately, there's no such thing in WASM standard library, so I implemented my own heavily fitted for the problem.

Very generally, a number consists of multiple 32-bit “digits”:

             |  integer | fractional part
             |  part    | 
-------------+----------+----------------------------
32-bit items |  digit0  | digit1  digit2  digit3  ...
bits         |  0-31    | 32-63   64-95   96-127

In fact that's similar to how we write fractional numbers, but “digits” are not 10-based but 2^32-based instead. Or, 2-based, if we think of every bit as a “digit”; the decimal values of such 2-based “digits” are: 2^31, 2^30, ..., 2, 1, (decimal separator), 1/2, 1/4, ...

Here is the example:

decimal =   10.5
hex     =    a.8
binary  = 1010.1

And another:

hex      = c.8000_0000_8 (width = 3)
decimal  = 12
           + 1/2    (bit 32)
           + 1/2^33 (bit 64)
         ≈ 12.5000000001

Arithmetic operations

Operations work the same way we were taught in primary school. For example, the addition:

  a0 a1 a2 ...
+ b0 b1 b2 ...
  ============
  c0 c1 c2 ...

Note: the overflow (carry-out from c0) is discarded because it's not needed for the task.

How to write the code for this with arbitrary width? Well, there are two ways:

Operands in memory: use loops

Each number is stored in consecutive memory cells, and we may use indexed loops to access digits:

function add(a: u32, b: u32, c: u32, width: u32) {
  let carryOver: u64 = 0;
  for (let i: i32 = width - 1; i >= 0; i--) {
    let x: u64 = (load<u32>(a + i) as u64)
               + (load<u32>(b + i) as u64)
               + carryOver;
    carryOver = x >>> 32;
    store<u32>(c + i, x as u32);
  }
}

Operands are local vars: unroll loops

const width = 3
let a0: u64, a1: u64, a2: u64,
    b0: u64, b1: u64, b2: u64,
    c0: u64, c1: u64, c2: u64,
    carryOver: u64;
// ...
carryOver = 0;

c2 = a2 + b2;
carryOver = c2 >>> 32;
c2 &= 0xffffffff;

c1 = a1 + b1 + carryOver;
carryOver = c1 >>> 32;
c1 &= 0xffffffff;

c0 = a0 + b0 + carryOver;
c0 &= 0xffffffff;

Note: although digits are 32-bit, variables are 64-bit to retain carry-over.

Which is faster?

The approach with unrolled loops is faster (15-20% for my case). However, it requires having the separate code for each width. Happily, when the code is almost the same, you can easily generate it. I generate computations for width up to 12. I doubt anyone zooms deeper, but if you do, please file an issue 😉

Now, the fixed image. Indeed an UFO but much nicer 🙂

3. WASM vectorization

“Single instruction, multiple data” (SIMD) or “vectorization” is simply when your CPU executes the same instructions against multiple variables at once. In WASM you work with 128-bit vectors that contain 2 to 16 data items (“lanes”) depending on their size. For example, if your data items are 8-bit integers, one vector contains 16 lanes. In my case, data items are 64-bit (floating-point or integer), so I'm able to compute series for 2 pixels at once.

Here's the example. First, non-vectorized code for 64-bit float:

for (let i: u32 = 0; i < maxIterations; i++) {
  const xSqr: f64 = x * x;
  const ySqr: f64 = y * y;
  if (xSqr + ySqr > 4) {
    // Diverged
    break;
  }
  // Compute next (x, y) ...
}

Now the vectorized version:

for (let i: u32 = 0; i < maxIterations; i++) {
  const xSqr = v128.mul<f64>(x, x);
  const ySqr = v128.mul<f64>(y, y);
  const g4 = v128.g<f64>(v128.add<f64>(xSqr, ySqr), FOUR);

  if (!point0DivergedAt && v128.extract_lane<u64>(g4, 0)) {
    point0DivergedAt = i;
  }
  if (!point1DivergedAt && v128.extract_lane<u64>(g4, 1)) {
    point1DivergedAt = i;
  }
  if (point0DivergedAt && point1DivergedAt) {
    // Both diverged
    break;
  }
  // Compute next (x, y) ...
}

How faster did it get?

Floating-point arithmetic became exactly 2x faster. BigNumber got only 15–20% faster, and I don't know why, honestly. Perhaps my code has a problem that I cannot spot, but I hope to find it someday.

4. Optimization: filling same-color rectangles

Note how many same-color areas there are in the following example:

Computing almost same series for each pixel seems ineffective. Is it possible to optimize it? Happily, yes. With this optimization, rendering is coded as a recursive process of painting nested rectangles. The first rectangle is the whole render task given to the worker. Then, the recursive algorithm goes like this:

Render only the contour of the current rectangle + mid point; or, for small rectangles, only corners + mid point
- If all pixels are of the same color:
  - Fill the entire rectangle with that color
- Otherwise:
  - If the current rectangle is still not too small, split the current rectangle into two and recursively render each one
  - Otherwise, render all pixels of the current rectangle as usual

Here's the same image with fast-filled rectangles outlined:

This enormously boosts performance, especially for “stable” parts of the image, i.e., parts that do not reveal too much color variability.

Conclusion: is it finally fast enough?

The issue with the Mandelbrot set is that, as the iteration count and the BigNumber width constantly increase, it is not possible to eliminate lags, but only to postpone them. Optimizations allow you to explore it more deeply, but inevitably there will come a point where the required amount of computations exceeds any CPU power. This means that there will always be a room for optimizations, but at present, I seem to have exhausted all available options. Or, am I wrong? Can you suggest anything to improve? And thank you for reading!

3 Reasons Your Site May Be Not GDPR-Compliant

Aleksei Berezkin — Mon, 24 Apr 2023 10:06:32 +0000

Note: I'm not a law professional. Well, not even an amateur. And this article is not a legal advice. However, I believe these examples may be a good practical introduction to the large and complex topic of GDPR-compliance.

GDP... what?

It was a buzzword some time ago, and still is a discussed thing. Very briefly,

GDPR is a EU law which applies to all websites and apps used in EU
GDPR prohibits personal data collecting without explicit user consent. Personal data examples:
- Name
- IP address
- Cookie, local storage property, or any other tool to recognise a unique user
GDPR also prohibits transferring user's personal data outside EU without their consent

Do you have ideas how your site can possibly violate these? Let's see!

1. Google Analytics

Google Analytics is a great tool... which sets cookies to tell apart unique users, and this is impossible to turn off. Which means, to use Google Analytics, you need to show a banner and ask user consent.

What should I do if I don't want to display any banners?

You can switch to a different analytics provider. I have tried several:

All of them are, or can be configured to be, GDPR-compliant. My choice is Telemetry Deck. It’s simple, convenient, lightweight in terms of user bandwidth, and offers the option to upgrade to a paid plan if your app takes off one day.

How can I identify unique users without cookies, local storage, but without showing an annoying banner?

You can't. If you need to recognize individual users for any reason, you must obtain their consent.

2. Google Fonts

What? Is it just a convenient fonts API? Yes, but this API collects user's IP address and may use it for analytics purpose. Some time ago the German court sentenced some site operator to a fine of 100 € for using Google Fonts.

What to do?

If you need several fonts, you may just host them. If you need many, and cannot host them, then you need user consent.

3. Hosting provider

This part is tricky. Much of US-based hosting providers (including e.g. CloudFlare, and GitHub Pages) record your IP-address in their logs. For this, you need a user consent.

However, this example is different from fonts and analytics because, according to providers' statements, this is required for their normal operation and troubleshooting. Unfortunately this topic is not actively discussed on internet, and there is no well-known judicial precedent so far.

What should I do?

At a minimum, you should disclose the data collection practices of your hosting provider in your Privacy Notice.
For GitHub Pages, it seems possible to achieve full GDPR compliance with a corporate account.
Consider using EU-based hosting providers like Statichost.
If your hobby app suddenly becomes popular and starts generating revenue, I recommend seeking legal advice. The more popular you become, the higher the chance of attracting attention from regulatory authorities.

Is this really a concern for my small site or pet projects?

The law is strict — it applies to any organization or individual running a site accessible in the EU. However, there is no well-known precedent where a hobby project owner has been fined. Overall, it seems the intention is to reduce the use of U.S.-based Big Tech products within the EU to protect residents from being tracked by foreign entities.

That said, complying with the law is always the safest choice. Moreover, protecting user privacy — something we often lack these days — is undoubtedly a worthwhile engineering effort.

Code Art — abstract artworks for your creations

Aleksei Berezkin — Tue, 25 Oct 2022 11:13:36 +0000

Have you ever searched internet to find a cover for your post? I did! Artists created quite a few of beautiful images, but whenever I see a nice pic I may wish slightly different color, or font, or angle, or some other effect...

Is it possible to make a software generating artworks? Yes, and here is it!

https://code-art.pictures/

Usage

Just open the app, or click “↻” — and you get new artwork
Do you need the file? No problem, click “Download” button and you have it
Do you want tweaking the image? There's a comprehensive menu under “Options” button. You may change size, font, color, angle and much other effects.

How does it work?

Glad you asked. Here's the repo. The app is powered by WebGL2 which I learned from WebGL2 Fundamentals. Just like any other WebGL app, much of its work is the scene data preparation which consists of several steps:

Rasterize textures
Generate several sets of scene parameters (font, angle, scroll position etc)
Estimate the expected pic fill ratio for each params set. I experimented a lot, and found out the more text visible on pic, the better it looks
Of generated params set, pick one yielding the greatest fill ratio
Compute scene vertices
Upload the data to GPU, and render the scene

To render UI I use Svelte. To parse JS files I use Acorn JS running in Web Worker.

Can I use images in my posts?

Of course! Please don't remove watermarks though, or give explicit credit near the image, thank you.

Have anything to say?

You are welcome. Feel free to write a comment or file an issue.

5 Unexpected Things About TypeScript

Aleksei Berezkin — Tue, 22 Feb 2022 21:09:17 +0000

Code on cover pic: MUI

Seems like TypeScript won among other statically typed languages for web. Does it mean it’s flawless? No; instead some of its features are at least unexpected. Let’s look at them closely.

1. TypeScript doesn’t provide 100% type safety

This code is not typesafe:

const a: number[] = []
const x: number = a[0]
console.log(x) // undefined!

Literally number[] type means: for any index there’s an item of type number. Which is not possible, of course! The following type would be correct for array: (number|undefined)[], but no-one actually writes like this because it reads very verbose. Instead, developers try just keeping in mind that any array indexing may produce undefined, and only tuples are really typesafe.

2. TypeScript is not the different web language

TypeScript acts in a space beyond and invisible to web. When you write TS code, you actually create 2 programs:

One runs in a browser, and it’s JavaScript program
Another runs only within TS compiler, and it’s completely gone once your bundle is ready

This means two things:

To write a good TS code you need to know JS on the first place
Writing on TS doesn’t mean you are expected to write like on some “traditional” backend language like Java or C#—with classes and OOP. Idiomatic TS looks just like JS—with objects and functions.

3. TypeScript typing is a duck typing

These two types are 100% compatible in TS:

type Point = {
  x: number,
  y: number
}
type Coords = {
  x: number,
  y: number
}

You may assign a var of a first type to a var of another, and that’s totally fine:

const p: Point = {x: 1, y: 2}
const c: Coords = p

It works the same way with interfaces and classes.

This is referred to as “structural typing”. Its antonym is “nominal typing” which would interpret Point and Coords as completely different and incompatible types.

That was especially surprising for me (I’m from Java world), and I was trying first to mimic nominal typing with brands; however shortly I discovered it’s easier to change a bit my mental model, and start thinking in structural types. Indeed, just like vars are aliases to values, types are aliases to objects’ shapes.

4. TypeScript has exceptionally rich type system, but you are not supposed to use its full power

TypeScript type system is Turing complete which means it can implement any logic, for example, computing Fibonacci sequence. Does that mean your types need to be that complex? I don’t think so.

My impression is that TypeScript’s complexity is caused by JS libs created years before TS got popular — Lodash, Ramda, Redux, and many many more. These libs were designed without keeping static types in mind, that’s why their typings, created afterwards, are very challenging to understand. Good code is a code easy to read — that’s why you’d better keep your types simple.

5. There’s no TypeScript standard

Unlike C, Java, JavaScript, or Python there’s no formal document which describes how TypeScript must work. This means it’s nearly impossible to make an alternative yet compatible TypeScript implementation, and we are bound to the official Microsoft implementation for years.

What does all these mean? Well… not that much. Any technology has its limitations, and there’s not a single perfect thing in the world. TypeScript is special because it got very popular even with all these drawbacks—which are quite serious IMO. But whether we like it or not, we are bound to TypeScript, and understanding its weaknesses is crucial for writing a good code.

DEV Community: Aleksei Berezkin

Typique — A zero-runtime CSS-in-TS library that doesn’t fight RSC

What bundlers already understand

What Typique is

The workflow

Validation

Less boilerplate in TSX

CSS vars

What’s more?

Tradeoffs

Editor-centric

TypeScript-aligned

Explicit syntax

AI-friendliness

Final thoughts

Stop Memorizing, Start Scripting: My Journey to cli-bits

gitb — print the current Git branch

youtrack — open a bug tracker issue

lastDown — print the N most recently downloaded files

moveHere — move files to the current directory

trash — move files to the Trash

getLine — select line(s) from stdin

lless — select a line and open the file

today — or tomorrow, or yesterday

codeDebug — open a project in VS Code and debug the TS service

What's more?

Setting up partial SSR for a React + TypeScript + webpack app from scratch

Do we really need a manual SSR setup in the era of Next.js and Vite?

Tutorial overview

Full code

Components versions

1. What kind of SSR are we doing here?

1.1. No SSR at all

1.2. Full SSR

1.3. Partial SSR

2. The example

2.1. App

2.2. Entry point

2.3. Template

3. Running and building the app

3.1. Running for development

3.2. Building for production

4. The SSR script

5. Running the SSR script

5.1. Alternative: running SSR as CJS

6. Tweaking src/entry-client.tsx

Congratulations, we’re finally done! 🎉

7 Practical Tips to Minimize Your JavaScript Bundle Size

Why Bother?

1. Don't Transpile to ES5

2. Know and Use Modern JavaScript Language Features

2.1. Generators

2.2. Private Class Fields

2.3. Modern APIs

Tip: How to Discover New JavaScript APIs

3. Avoid Code Duplication

4. Avoid Overengineering

4.1. Over-generalization

4.2. Using Improper Framework

5. Avoid Dated TypeScript Features

5.1. Enums

5.2. Namespaces

6. Don't Neglect Small Optimizations

6.1. Use Truthy / Falsy Properties

6.2. Allow Non-strict Comparison Sometimes

6.3. Use Nullish Coalescence, Logical OR, and Default Parameters to Substitute Default Values

6.4. Use Arrow Functions for One-liners

6.5. Don't Use Classes for Very Simple Objects

7. Regularly Inspect Bundles

Fluent Streams: A Library for Rich Iterables Manipulation

Talk is Cheap. Show Me the Code

Top 3 Words in a Text

Coprime Integers

Generate a Deck of Cards

And Play Hold'em Poker!

This Must Be Cheap

Caveats

Have Fun Coding!

Migrating from react-router to wouter

Why migrate to wouter?

6. Tweaking `src/entry-client.tsx`

SVG circle and `stroke-dasharray`