DEV Community: Sergey Nikitin

We migrated 70,000 tests from Jest to Vitest. Yes, in 2 months

Sergey Nikitin — Thu, 08 Oct 2026 13:05:24 +0000

YOU got it right. We migrated 70,000 tests (reads: 70 thousand) from Jest to Vitest. The logical question would be: how? And here is where the story begins.

I work as a software engineer in the Frontend Developer Experience team at Miro. Our ownership covers various parts of the platform. One of the major focuses for us is frontend infrastructure and tooling – everything that makes the product teams at Miro fast and productive. 2026 was indeed a pivotal year for us: we were finally able to kill Angular.js (I know, right), switched from Prettier to Oxfmt, got rid of ESLint in favor of Oxlint, we are running the CI typechecking with TypeScript 7 and much more. But look, you are here to read about unit-tests! In this article, I will cover how we migrated the main Miro frontend application unit testing harness from Jest to Vitest.

The beginning

The main Miro application is constantly evolving and sits now at ~6 million LoC. At this scale, the regular approaches and tooling stop functioning. How can I tell? Here are some facts about our CI state, unit-test jobs specifically:

We run 6 CI runners in parallel just for unit-tests. Each runner takes up to 20 minutes to finish
For Jest 30 the average speed is ~13 tests per second, even with SWC as the code parser
25% of all runs are failing because of memory leaks, i.e. the CI runners are dying with OOM errors
We had to apply specific patches for Jest core packages to maintain a better worker pool (were never accepted upstream)
Migrating from Jest 29 to Jest 30 (yes, the first major release in 3 years) gave us only around 5% speed and memory improvements

This does not look bright, and it has a big impact on the new releases for our application. But what could we do about that?

Lurking through the Slack messages, I found a few threads where we actually discussed if we want to migrate away from Jest. Back in November 2023, one of my colleagues wrote:

Although I’ve spent some time also exploring an alternative (vitest) but I’ve found that in practice the extra set of vitest specific configurations and replicating our current build might be too risky, without knowing how much speed benefits we get now that we’re relying on @swc/jest

At that moment, the scale of the problem was manageable – we just started to run the unit-tests in parallel on CI, compensating for the waiting time with the compute power from extra runners. Worked pretty well.

In July 2024, another colleague of mine made a remark regarding the unit-test tooling one more time:

I expect higher returns from better test selection (e.g. not running 35k unit tests each time). The cost of switching to vitest (for example) is high and unclear what the improvement is

Fair enough! 6 runners for 35,000 tests in parallel took just around 7 minutes each. With job durations like this, we had much bigger problems to solve, think of end-to-end tests, for example.

The problem

Fast-forward to March 2025. We started facing more and more issues with the Jest stack for testing. Let me give just one example that triggered me to explore the alternatives to Jest. Apparently, our engineers reported that with the VSCode Jest extension, multiple versions of fb-watchman (Jest’s in-house filesystem watcher library) were installed, which led to CPU saturation and, as a result, the inability to use their laptops. We figured out how to fix it with watchman: false. At that moment, Ahmed, a Principal engineer in the Frontend Developer Experience team, had enough:

I want to say maybe it's time to switch to vitest, but that's a massive effort…

We had a conversation regarding this, but I had no capacity to lead the migration right away. We also saw a lot of traction regarding the AI models and how they rapidly evolve for more and more complex problems. All signs were to wait for a bit. And this is how we landed in 2026.

Now you may ask: “Sergey, why did you decide to explore the migration again, considering all the facts you just mentioned?” Don’t get me wrong, we are not solving problems of this scale just because it’s cool. We need to understand what we want to achieve. I will start from the facts first:

The main Miro application is a monorepo, that includes both web and native parts. It is managed by yarn and NX. At the beginning of 2026, we had 800+ packages in our codebase. The largest code share is located in the web core, which accounts for around 20% of the codebase. We also had ~70,000 unit-tests (doubled in 2 years, imagine that) and the unit-tests jobs were taking up to 20 minutes on average to finish, which made them the slowest CI jobs in our pipeline, even worse than building the application and running the e2e tests on the new version!

Now, we can already see a few pain points we are fighting against. I can compile the whole list for you:

CI runners memory limit. 25% of the runs are failing because of memory leaks
Even with the SWC parser, Jest is slow, at 13 tests/sec for us (we use JSDOM and canvas mock for testing)
The TypeScript compatibility is not excellent. There are still API methods that infer the any type.
There is no proper ESM support, no mock hoisting. We add the spying code and mock factories between the top-level imports, so the import statements are downleveled to require() and can pick the mocked implementation.
Because of the previous point, we still transform the code to CommonJS. This means we are not testing what we are delivering to our customers (we deliver the ESM bundles).
The test coverage report is inaccurate. The packages do not share the instrumentation outside of each project root directory. This effectively means that there is missing cross-package coverage.
No test isolation. The jest workers in the pool are not spawned for each module; rather, they are recycled once a worker hits the memory limit.
There are no guardrails for the test fixtures to prevent leaking into the production bundle (funny spoiler: some teams actually used the test fixtures in the production code, intentionally)
Let's be real, it took Jest 3 years to release a new major version. We have opened a few issues on GitHub, but we did not see any traction around it.
Not only us, did I mention the incompatibility with other popular libraries? Prettier, for example.

I can go on and on, but I think this is already impressive.

Now, you cannot just take 70k tests and rewrite them with a random testing framework (imagine you could!). You also have to educate hundreds of product engineers, and the scale of the change would be massive. And also, how about all the custom plugins, matchers, and supporting dependencies? Think of jest-axe, jest-when, React Testing Library, and others. The answer to all of this is – we are looking for a Jest-compatible api. Compatible enough so we won’t turn our monorepo into chaos.

Where to migrate?

Now, the market research gave us two alternatives: Rstest and Vitest (versions as of March 2026):

RStest v0.9.8 (https://rstest.rs)

Part of Rstack toolchain, so we can reuse the Rspack configuration from our application
Modern ESM-based syntax (think of import attributes and more explicit mocking syntax)
Integration with Rsdoctor for debugging

Vitest v4.1.6 (https://vitest.dev)

Wide community adoption
Type safety and ESM-first
Test isolation and rich, comprehensive api

You can guess Vitest won, but why? I did my homework: I created two branches and migrated around 10k tests to each of the frameworks. Then I tried to execute the tests in different modes. Here are the results (the values are tests per second, the bigger, the better):

	Jest	Vitest	Rstest
Local run	14.7 t/sec	16.8 t/sec	7.6 t/sec
Local run with coverage	5.9 t/sec	8 t/sec	2.9 t/sec
CI run	12.9 t/sec	13 t/sec	OOM
CI run with coverage	5 t/sec	8.6 t/sec	OOM

You can already notice that Rstest failed to run on CI, mainly because of bad memory management in the worker pool. Keep in mind that it was pre-1.0 version and the runner is under active development, so the hopes were low (I encourage you to try the latest version and explore the current state of things). In the meantime, migrating this small test subset showed a huge difference in memory consumption for Vitest – more than 10GB less memory used on the runner compared to the same group of tests in Jest 🚀.

Just to be honest here, the speed and RAM consumption were indeed among the main factors. And although the research did not show any meaningful speed improvements, we decided to execute the migration as we saw opportunities to optimize Vitest configuration and try to make it faster. It also covers other pain points we were targeting to solve. Yes, we have a front-runner, and we are now coming to a plan!

The plan

As I said already, the Miro web application is a monorepo orchestrated by NX and Yarn. It combines the web core monolith, holding ~20% of all the code. Other parts are: 800+ packages and the part for native applications. And since the native part has its own CI and release pipeline, we decided to leave it out of scope.

On a separate note, the application accepts 60+ merges into the main branch on a daily basis. And as much as I wanted to “just” ask the AI agents to migrate everything in one go, it was not possible for us to execute. I decided to go with a gradual rollout:

Run both Jest and Vitest on separate runners on CI in parallel. As the migration goes, reallocate the runners depending on the share of migrated tests
Start with packages. This way, we will be able to deliver the meaningful parts, and it is easy to discover which tests should go to Jest and which to Vitest.
Use AI agents to migrate the tests. We create a skill for the agents in the repo, so the agents have all necessary context. After each migration phase, we update our patterns not mentioned in the skill files.

The last bit is the most powerful. Now, the agents learn and remember new patterns. This makes the migration faster and produces fewer hallucinations with each iteration. This also makes the migration more consistent – the agents apply the same patterns they saw before. Not only that, once completed, you will end up having a huge list of very specific code examples the agents found in the tests – an amazing source of insights to reflect on. It can easily open the room for follow-ups, good practices, and knowledge sharing.

Act 1 - Infrastructure

I started with infrastructure for Vitest. The basics include having the very first version of Vitest config to reuse in the application.

Then we added the compatibility bridges. Think about shared mocks and helpers that create the fake data. During the time of migration, we do not want to duplicate such files. Hence, we added the shim globalThis.jest = vi in Vitest config. And globalThis.vi = jest in Jest. Yes, the api is not 100% compatible, but this was enough in our case.

Now the whole idea of migration was built around a gradual switch package by package. Each package runs the scripts via the CLI commands, think of it as having a command miro-scripts test. It took me to add the runner’s opt-in argument, so we can distinguish which test runner to spawn. Looks like this: miro-scripts test --runner=vitest in the package.json file.

It was not just a local story. This flag allowed us to see how to run these tests on CI runners. As we specialized the runners per tool, we combined all Vitest projects into one pool of runners, and the rest was for the remaining Jest projects.

Finally, we adjusted the observability metrics in order to track the progress and test distribution. We added the extra runner label for test-related Prometheus metrics, which made it possible to visualize the migration.

Act 2 - First steps

Now we were all set to start the actual migration. All guardrails were there, the CI picked up all the tests, so we were not losing quality. The only missing part was the test coverage for Vitest, but we agreed to handle it after the transition.
I started with small packages. This allowed us to keep the pull-requests size manageable. This way I could:

Review the changes more precisely (as I said, in the later stages, the built context was so rich that it could hardly produce off-track changes)
Form the foundation of the AI skill. First instructions, patterns, and polyfills were missing in the config
Convince teams and build trust. We, as a Frontend Developer Experience team, knew we needed to modernise the tech stack. But it was not obvious for the product teams. I made sure to be vocal about the migration and tried to iterate on the reasoning behind the change
Start collecting issues. For example, there were some extensions in VSCode that tried to guess the test framework used in the repo by the root-level config. With both Jest and Vitest configs at the root, it gave priority to Vitest, which at that time had only a fraction of packages with completed migration – just one of those things that I could only assume at the beginning.

Once the first version of the AI skill was ready, I made sure to focus on the community work, presenting on it internally and explaining how each team could DIY their own migration. The skill is in the repo, just ask your agent to migrate the packages under your ownership! ✨

Act 3 - Goes well

We started off strong with the migration. The first 90 packages went pretty well. At this moment, we built the needed Vitest plugins to cover parts of Jest configuration and added a decent number of global polyfills. I intentionally did not ask the AI agents to mirror the Jest config – nobody touched it for years, and it absorbed so much legacy, I did not want to port it to Vitest and started from scratch. I also tried to run the migration based on ownership, i.e. in a single pull-request I would only transform tests for the single owning team. Unfortunately, this did not work as expected. We have so many cross-package helpers and fixture generators, so it was never a single team, rather a few owners here and there. But that was still acceptable to us.
At that point, I felt so confident that I decided to take one of the biggest packages in our repo (apart from the web monolith). ~600 test files all at once, a true battle test for the migration flow. BOOM, we landed it in the main branch! It was a huge milestone and proof we could continue.
On another side, we kept working with the frontend community and were very transparent about the effort. As a result, we started receiving positive feedback about the progress in general and how smoothly the migration was going.

Act 4 - It couldn’t be that easy

Although the mechanical migration was progressing well, our responsibility never changed – stable CI processes. Not only did we need to migrate the code, but we also needed to follow the metrics. Unfortunately, the metrics started showing a coming disaster.
The CI runner started consuming more and more memory. I was confused! My initial research gave me the signal that Vitest consumed much LESS memory, but we were around 50% of the way through the migration, and it was getting only worse?! We had to pause everything until we figured it out. Imagine my mental state at that time: we were in the middle of a transition. I couldn’t roll everything back, but I also could not move on. What do I do now? Did I fail?!
I was buried in the problem for days until I came to the realization:
Each package in the repository is defined as a Vitest project (for simplicity, I will use the terms package and project interchangeably). Turns out, Vitest projects do not share the transformation cache! Every project builds up the cache with a unique identifier under the hood. If packages are heavily interconnected, Vitest spawns a Vite server for each package and transforms the same module graph again and again. So 10 linked packages will transform the same modules 10 times. Now scale it up to 800 packages, and you will get it. And in my initial research, I only used the subset of the tests inside a single Vitest project, thus, I could not actually see it coming.
The solution is to run fewer projects, not by ignoring some of them, but rather by merging the projects into a single instance. Fortunately, most of the packages in our application have the default shared Vitest config with no overrides. So it was easy to write a project discovery script that would combine all packages with default configuration into a single project. By doing this, we were able to run only 60 Vitest projects that actually account for 400 packages (59 custom projects + 1 project that includes the remaining files).
I will give you a sneak peek with the numbers:

Metric	Before	After	Delta	% Change
Heap Memory	8,770 MB	5,024 MB	-3,746 MB	-42.71%
Total Memory	21,403 MB	18,564 MB	-2,839 MB	-13.26%
Total Duration	1059.83s	611.06s	-448.77s	-42.34%
Transform Time	10756.03s	4327.69s	-6428.34s	-59.76%
Setup Time	1495.36s	1277.27s	-218.09s	-14.58%
Import Time	13452.26s	6984.71s	-6467.55s	-48.08%
Tests Time	257.29s	262.76s	+5.47s	+2.13%
Environment Time	344.18s	371.06s	+26.88s	+7.81%

Curious readers may ask: why did Environment time and Test time increase? Imagine you run 10 Vitest workers in parallel. And only a single main process that runs Vite to transform the import tree. Before the change, the workers would just hang and wait when the main process transforms the same modules again and again. Once we merged the projects, the transformation time dropped significantly. Now the workers do not wait, they run more tests, which causes CPU saturation and system pressure in general. This effectively results in slower worker performance. But since the actual test run takes only a fraction of the overall test execution process, the degradation is negligible.

That being said, combining all standard projects into a single instance made an outstanding impact on the performance and confirmed my assumption. The most important thing is that we can now continue with migration!

Act 5 – Closer to the goal

The next 60 pull-requests were just mechanical. The AI agent has built up the comprehensive skill context. My job was to check the bad-looking and non-trivial changes. Then also hear the feedback from the reviewers, since I cannot in this world know each and every unit-test in the Miro application.
One nice cherry on top was the fact that with the Jest → Vitest migration, we started noticing some test fixtures that had accidentally leaked into our production bundle (remember point 8?). The logical question would be: how? How did we detect this, and how did the test data leak into the production bundle?

The first part was easy for us – we build the web application with Rspack with no overrides or patches in the config to support Node.js modules. In fact, Vitest uses the NodeJS api under the hood (it is a Node library in the end). As a result, Rspack would fail to build the application once any part of Vitest is imported in the dependency graph.

How does it usually happen for us?

Barrel files. Every package in the repository exports its API via the barrel file index.ts. Although it would work fine in small projects, barrel files give nothing but pain as the application gets bigger. Barrel files, and especially star exports (export * from ‘./foo.ts’) are hard to tree-shake, and you never know what exactly is being exported. Accidentally, some test shapes were exported transitively as well.
Some teams actually used test helpers to create artificial users and accounts in the production code. These were edge cases but still happened.

The Vitest migration clearly highlighted such cases and made us improve the codebase. This gave us approximately a 4MB cut from the full production build.

Act 6 - One-shotting the web core

We had migrated all packages at that point, and the AI agents now had a definitive playbook on how to run the migration. Now it was time for the final boss: the web core monolith. 1,800 test files, 16,500 tests. I realized it was too risky to run the migration during business hours – engineers merge pull-requests once every 10 minutes. I would spend more time resolving the conflicts. I decided to handle it during the weekend (no worries, I took two days off to compensate!)
On Saturday, I told the AI agent to run the migration. The result: 1,985 files changed, +22,776 / -19,998 lines diff. This pull-request tagged each and every team for review, but my plan was to merge it right away with an admin override approval. It wasn’t perfect, but it was decent enough. The rest we could fix later with smaller PRs during business hours. It took me an entire day to look at the changelog!
I clicked the Bypass rules and merge button and waited for the main branch CI to complete. I could finally go to sleep. We made it.

Act 7 – Aftermath breakthrough

I don’t want to give the impression that the transition was perfectly smooth. Once we completed the mechanical work, we had to clean up the configs, revert the hybrid setup, and start removing Jest dependencies. But this is fine. The bigger problem (ironically) was that Vitest is a much more reliable tool than Jest. It has its own timeout for module imports, it catches unhandled errors, it races the duplicated vi.mock blocks. All of this actually made a small subset of tests more flaky. We spent some time stabilizing the tests, exploring the actual cause, and working with the owners to see how we could address it. A fractional chunk of tests (think of 27 test cases) was completely skipped for the sake of CI stability.

But one question still stood out in my mind – we were able to speed up the run and save memory by merging the projects. Could we merge everything into a single Vitest project?
One of the advantages of the transition to Vitest is that we were able to drop tons of legacy configurations. This made all custom Vitest configs look like this:

import { defineProject, mergeConfig } from 'vitest/config';
import defaultCfg from '@shared/config/vitest/shared.config.js';

export default mergeConfig(
    defaultCfg,
    defineProject({
        test: {
            setupFiles: ['./setupVitest.ts']
        }
    })
);

Only the setup script is what makes us create the custom configs. Why does that matter? If the setup file is the only difference, maybe I can detect which test file is running and call the setup script relative to that file!

There is no documentation around it. The only hint I got is this page, which explains the interface for the expect api. Apparently, expect.getState: () => MatcherState, and then MatcherState has the field testPath - the absolute test path, which is exactly what we are looking for.

Now I quickly spun up the shared setup script, which takes the test path, derives the package the test is located in. and then dynamically executes the setup script attached to that specific test file. Here is the idea:

import { existsSync } from 'node:fs';
import { relative, resolve } from 'node:path';
import { expect } from 'vitest';

const repoRootDir = '%repo_root_path%';

const absoluteTestPath = expect.getState().testPath;
const relativeTestPath = absoluteTestPath ? relative(REPO_ROOT_DIR, absoluteTestPath) : '';

// you can manipulate the path to find the right location here
const vitestProjectRootDir = fetchProjectDirForTestFile(relativeTestPath); 

const setupFile = vitestProjectRootDir ? resolve(repoRootDir, vitestProjectRootDir, 'setupVitest.ts') : '';

if (setupFile && existsSync(setupFile)) {
    await import(setupFile);
}

You can make this script project-agnostic and execute it for each test file. Doing this, we were able to merge ALL 800+ Vitest projects in our application into a single test run. No transformation overhead, no cache duplications. To give you an idea of how impactful it was, I will give you a sample:

Metric	Before	After	Delta	% Change
Heap Memory	5,238 MB	1,857 MB	-3,381 MB	-65%
Total Memory	22,460 MB	17,450 MB	-5,010 MB	-22.3%
Total Duration	865.64s	588.82s	-276,82s	-32%
Test speed	12.6 t/sec	19 t/sec	+6.4 t/sec	+50%

Finally, we found the source of the speed ✨ And this concluded our road to landing Vitest in our main Frontend application.

Results

Active migration time	About 80 days (May 4 to July 20)
Merged pull requests	97
Lines added/removed	+87,701 / -78,946
Net lines	+8,755
Files touched	9,328

Notice we have added almost 9,000 net lines of code. The actual net is much lower, because we moved from globally injected api (think jest, it, describe, etc.) to locally imported objects (import {describe} from ‘vitest’). Plus, code formatting gave some diff. Now to the technical details:

The test runs are 50% faster than they were with Jest (13 t/sec to 19 t/sec)
Vitest consumes 30% less memory on the CI runners
Vitest mocks are type-safe i.e. they inherit the signature from the mocked object, allowing engineers to write better unit-tests.
ESM-first. The mocks are hoisted automatically, which gives again the better experience for the engineers.
Production bundle saved around 4MB, the test fixtures were pulled out from the production barrel files
Real test isolation – each test file is being run on an isolated worker in the pool, ensuring tests do not interfere with each other
Accurate test coverage. allowExternal: true allows us to collect the test coverage, dropping the project boundary. We collect the full picture.
We collected the test polyfills from all files, generalised them, and stored them in a shared configuration. Not only did it simplify the tests, but we also made sure engineers have a consistent experience with the polyfilled api’s
The migration AI skill was transformed into the unit-tests creation skill. Now it gives the agents the common patterns from our codebase, which enabled better test generation

The total model usage during this period cost around $7,000. To put this into perspective, I estimated the annual savings from the migration on CI runners at approximately $75,000. We should also account for more application releases: as I mentioned at the beginning, we started facing more and more memory issues for Jest runs. Add here the faster feedback loop during the local development as well, which is, to be fair, hard to estimate. All of this made the investments a huge win for us.

Lessons learned

In 2026 here at Miro, we keep experimenting with large-scale migrations. Our goal is to provide engineers with the best-in-class tooling and infrastructure. We have already made a transition from Prettier to Oxfmt, from ESLint to Oxlint, from Webpack to Rspack. It was just about time to switch from Jest to Vitest. Each journey results in lots of artifacts for future improvements. And lessons learned along the way. Here are some of them:

Set a clear goal. Be specific about what you want to accomplish. Research the market and find the tools that can move you towards the goal. Experiment with a subset of the codebase to be able to estimate the scale and feasibility, and to get a feel for the planned work.
Plan the execution. Sometimes you just need to make a big bang migration. Sometimes you can be more gentle and have a gradual rollout. For Vitest, I made a safe bet to iterate and build up the context for the AI agents. It worked pretty well, and at some point we were able to one-shot the remaining tests.
Be specific in the prompts with AI agents. Give a deterministic way to reproduce the result. Set the constraints. It was not possible to run the subagents in parallel because Vitest takes so much memory in our case. I asked to run the migration sequentially, so it did not ruin my workstation.
Build trust. People resist change. My goal was to give the reasoning behind the change, acknowledge the struggle to understand where to use which runner, and help to adopt the new tooling.
You can not plan for everything. There are always issues you could not possibly expect during the preparation. You need to accept it and not be afraid to pivot and look up for the solution.
The scale of change does not matter at this point. With Fable 5, or Sol, AI can execute any volume of change. If you can formalise what needs to be done, if you can create a context for the agent, if you can give a deterministic reproduction – the implementation part is extremely democratised.
Trust the CI. Some changes during the migration were trivial. Others touched the production logic. I worked with the code owners to understand if the change I am introducing is legit. But at the end of the day, you have to build the release quality gates that are trustworthy, and a rollback process so fast, so even if you end up having a bad day, you can easily fix the mistake.

To wrap it up

We have completed the migration of our main frontend application from Jest to Vitest. The transition took 70,000 tests to transform (75,000 as of the last merged pull-request date). It took us just a bit over 2 months to execute. We used Opus 4.8 and Fable 5 (once it was released) to drive the migration.

Migration to Vitest gave us space and resources to grow further, modernised our codebase, and allowed us to start writing type-safe unit-tests. It also caught the test data leaks into the production bundle and actual production bugs.

This project paid off in all areas we were targeting. It also built a story of how useful the AI agents can be if done right.

Special credits go to Evgeny Evsyukhin, who has heavily contributed to the migration as well as the observability infrastructure around Vitest. I want to also mention Ivan Voronin, Ahmed El Gabri, Frederico Estrela, Vinicius Kiatkoski Neves, and my beloved Frontend Developer Experience team for making the migration possible. I also want to give a shoutout to Ben Makuh for proofreading and helping me refine this article.

PS: Since we created this Jest to Vitest migration skill, I thought it would be nice to create an open-source version as well. It can be a good foundation for your own contextual migration skill. Feel free to use and contribute here.

Axios timeout for chunked responses

Sergey Nikitin — Wed, 07 Oct 2026 22:02:33 +0000

ALRIGHT, this was an interesting one. I use Axios in one of my pet projects. Basically, the project is a Telegram bot that transforms voice messages into text. I know that Telegram now has this feature for premium subscribers, but this is not something we are about to cover in this article. Here I want to talk about the tricky way the Axios timeout works.

Let's start with the simple HTTP server (I use Express as an example) and a single API endpoint, which takes 10 seconds to resolve:

import { createServer } from 'node:http';
import express from 'express';

const api = express();
// I have an API endpoint which takes 10s to resolve
api.post('/regular', (_, res) => {
    setTimeout(() => res.status(200).send({}), 10000);
});

const server = createServer(api);
server.listen(3000);

If we deep dive into the documentation, we will find that Axios supports the timeout property, and it works quite well:

import axios from 'axios';

const start = new Date().getTime();

try {
    console.log('Start request');
    await axios.request({
        method: 'POST',
        url: 'http://localhost:3000/regular',
        timeout: 5000
    });
    console.log('Request was successful');
} catch (err) {
    console.error(err);
}

const end = new Date().getTime();
const requestTime = Math.floor((end - start) / 1000);
console.log(`Request took ${requestTime}s,`, 'should be 5s!');

// Start request
//
// AxiosError: timeout of 5000ms exceeded
//     at RedirectableRequest.handleRequestTimeout (/axios-streaming-timeout/node_modules/axios/lib/adapters/http.js:630:16)
//     at RedirectableRequest.emit (node:events:513:28)
//     at Timeout.<anonymous> (/axios-streaming-timeout/node_modules/follow-redirects/index.js:169:12)
//     at listOnTimeout (node:internal/timers:569:17)
//     at process.processTimers (node:internal/timers:512:7) {
//   code: 'ECONNABORTED',
//
// Request took 5s, should be 5s!

The problem

If it works fine, what is the problem then, you ask me. Here is the thing: as I said, I have a Telegram bot that converts voice messages into text. It basically decompresses the voice file into a WAV buffer and sends the data to one of the cloud providers. As a result, I receive text recognition for that specific voice message.

In fact, one of the providers I use implements the streaming API. The intention is to show the text recognition for the user in real time while it gets processed (Which is quite cool, huh). You receive chunks of text data, and you have a choice to wait until you can combine the whole message, or send it out to the user so they see the early results. On a code level, it actually resolves the request promise, so you can handle the chunk of data. With the following chunks, it is being resolved again and again until the final chunk is received and the request is finished.

If you read this, you can already see the unexpected side effect of this approach. Axios resolves the request promise with the first chunk received. Essentially, this means that Axios resets the timeout, and the request time is not controlled in any way. For example, I have a timeout of 10 seconds for my bot recognition engine. And I could see in the logs that requests were taking 30, 45, 50 seconds, and even more. With the first chunk received, Axios stops counting the timeout frame and considers the request resolved. To illustrate this, I created a new endpoint in the Express server:

import { createServer } from 'node:http';
import express from 'express';

const api = express();
// I now have an API endpoint that sends one chunk of the response each second
api.post('/chunk', (_, res) => {
    res.writeHead(200, {
        'Content-Type': 'text/plain',
        'Transfer-Encoding': 'chunked'
    });

    const intervalId = setInterval(() => {
        console.log('Keep sending chunks');
        res.write(JSON.stringify({ foo: 'bar' }) + '\r\n');
    }, 1000);

    setTimeout(() => {
        console.log('Finalize the request');
        clearInterval(intervalId);
        res.end();
    }, 10000);
});

const server = createServer(api);
server.listen(3000);

Now, if I call the new endpoint, I will experience rather unexpected behavior:

import axios from 'axios';

const start = new Date().getTime();
try {
    console.log('Start request');
    await axios.request({
        method: 'POST',
        url: 'http://localhost:3000/chunk',
        timeout: 5000
    });
    console.log('Request was successful');
} catch (err) {
    console.error(err);
}

const end = new Date().getTime();
const requestTime = Math.floor((end - start) / 1000);
console.log(`Request took ${requestTime}s,`, 'should be 5s!');

// Start request
//
// Keep sending chunks 1
// Keep sending chunks 2
// Keep sending chunks 3
// Keep sending chunks 4
// Keep sending chunks 5
// Keep sending chunks 6
// Keep sending chunks 7
// Keep sending chunks 8
// Keep sending chunks 9
// Finalize the request
//
// Request was successful
// Request took 10s, should be 5s!

The request was supposed to take 5 seconds maximum, but it actually took 10 seconds and was successful in the end. Imagine if it hangs for several minutes! Obviously, users are not in favor of waiting that long for voice recognition, and they stop using the bot. But how can we fix it?

AbortSignal to the rescue

At first glance, one solution would be to wrap the request in my custom cancellation function, so once, say, setTimeout() triggers the handler, we reject the promise and fall into an unhappy flow. BUT. Fortunately, there is a better way! Let me introduce you to AbortSignal and AbortController.

AbortSignal is a built-in JavaScript signal implementation, which is widely adopted to control the execution and cancellation of other APIs in the language. The interface itself is fairly simple. Basically, it only contains a couple of static methods:

AbortSignal.abort() returns the instance of AbortSignal which is already aborted.
AbortSignal.timeout(timeout: number) returns the signal that will be aborted in the timeframe you specify in the parameters.

As I said, the implementation is pretty simple and does not give us much flexibility. For more complex cases, AbortController comes in handy.

AbortController is a wrapper around the AbortSignal, and it has one huge benefit — the abort() function. This means you get granular control over the signal execution. You can invoke it manually whenever you need to. Here are some examples:

DOM event listeners support the AbortSignal, so we can unsubscribe from all the events in one go:

// Create an abort controller instance. It contains the signal and abort function
const { signal, abort } = new AbortController();

const saveBtn = document.getElementById('save-btn');
const printBtn = document.getElementById('print-btn');
const backBtn = document.getElementById('back-btn');

// Add the signal to the event listener
saveBtn.addEventListener('click', saveHandler, { signal });
// Add the signal to another event listener
printBtn.addEventListener('click', printHandler, { signal });

// Abort the signal when we navigate back
backBtn.addEventListener('click', () => abort(), { signal });

In this specific (pretty simplified) example, once we click the Back button, we trigger the abort() function and hence send out the abort signal. As a result, we have unsubscribed from all three event listeners. Easy as that!

As JavaScript developers, we spend most of the time handling API requests. And the good news here: the fetch() method supports AbortSignal as well.

// Create abort controller instance. It contains the signal and abort function
const { signal, abort } = new AbortController();

try {
    await fetch('http://localhost:3000/regular', {
        method: 'POST',
        signal
    });
} catch (err) {
    console.error(err);
}

const backBtn = document.getElementById('back-btn');
// Now we abort the fetch request once we click on the back button
backBtn.addEventListener('click', () => abort());

If the request is in the pending state, clicking the Back button will lead to an error in the console DOMException [AbortError]: This operation was aborted. This is one good example of how to implement the timeout for the fetch() interface in your application.

For more information and engine support, you can read the MDN articles about AbortSignal and AbortController.

Combining with Axios

Now that we are familiar with the interfaces we are going to use, I want to draw your attention to one more thing. If we go back to Axios, we will quickly realize that Axios supports AbortSignal as well. This was amazing news for me, as I did not need to write my own custom logic around the request cancellation.

In my implementation, timeout is the only thing that matters, so I can even use AbortSignal directly without having to invoke the AbortController instance — it supports the timeout as I showed above. The fix for my issue is pretty simple:

import axios from 'axios';

const start = new Date().getTime();
try {
    console.log('Start request');
    await axios.request({
        method: 'POST',
        url: 'http://localhost:3000/chunk',
        timeout: 5000,
        signal: AbortSignal.timeout(5000) // Add the timeout signal in the config
    });
    console.log('Request was successful');
} catch (err) {
    console.error(err);
}

const end = new Date().getTime();
const requestTime = Math.floor((end - start) / 1000);
console.log(`Request took ${requestTime}s,`, 'should be 5s!');

// Start request
//
// Keep sending chunks 1
// Keep sending chunks 2
// Keep sending chunks 3
// Keep sending chunks 4
//
// CanceledError: canceled
//     at EventTarget.abort (/axios-streaming-timeout/node_modules/axios/lib/adapters/http.js:192:54)
//     at [nodejs.internal.kHybridDispatch] (node:internal/event_target:737:20)
//     at EventTarget.dispatchEvent (node:internal/event_target:679:26)
//     at abortSignal (node:internal/abort_controller:314:10)
//     at Timeout._onTimeout (node:internal/abort_controller:120:7)
//     at listOnTimeout (node:internal/timers:569:17)
//     at process.processTimers (node:internal/timers:512:7) {
//   code: 'ERR_CANCELED',
//
// Request took 5s, should be 5s!

I have used the static method AbortSignal.timeout(5000) to cancel the request if it takes longer than 5 seconds. I could do it with AbortController as well, but this requires a couple more lines of code. For instance:

import axios from 'axios';

// Create an abort controller instance. It contains the signal and abort function
const { signal, abort } = new AbortController();

// Abort after 5 seconds
setTimeout(() => abort(), 5000);

try {
    await axios.request({
        method: 'POST',
        url: 'http://localhost:3000/chunk',
        timeout: 5000,
        signal
    });
} catch (err) {
    console.error(err);
}

As you can see, this approach requires creating an instance of AbortController and creating the timeout manually, so I would recommend using the AbortSignal.timeout() method directly in such a simple case.

The last observation to keep in mind is that, since we introduced the AbortSignal, it makes the usage of the Axios timeout property redundant. The race condition appears to be in favor of AbortSignal all the time. And since it covers the same capability, I believe we can safely remove the timeout property for good.

await axios.request({
    method: 'POST',
    url: 'http://localhost:3000/chunk',
    signal: AbortSignal.timeout(5000) // Abort any request by 5 sec timeout
});

The outcome

Users hate to see errors in their applications. But even more, they hate to feel the application is not responding, stuck in some in-between state, and does not give feedback if something goes wrong. I can not control the time the cloud provider takes to transform the audio buffer into text, so I show the error message when it takes longer than a reasonable time.

Axios timeout property works just as well with a regular API. But if you face the streaming API endpoint and want to limit the request execution time, keep in mind that the timeout property won't work as you would expect. One of the options to solve this is to try using the native JS AbortSignal implementation to ensure the timeout is applied for any kind of request. In the meantime, I have filed the issue report in the Axios repository, asking to clarify the timeout behavior in the documentation.

You can check the source code for this article in my repository on GitHub. The code is tested on Axios v1.5.0.

Adapting One Old UI Components Library To Work In TypeScript Code

Sergey Nikitin — Sun, 08 Aug 2021 19:48:18 +0000

THE first public version of TypeScript appeared more than 7 years ago. Since that time it grew up and brought many incredible features for developers. Today it slowly becomes a standard in the JavaScript world. Slack, AirBnB, Lyft, and many others add TypeScript into their tech stack. Teams use TypeScript for both browser applications and NodeJS services. There are always pros and cons to this decision. One disadvantage is that many NPM packages are still written as JavaScript modules. We experienced this issue as well when decided to migrate our applications to TypeScript. We had to implement type definitions for our internal UI components library. We wanted to get a tool, that could serve developers as additional documentation. We also wanted to collect everything engineers can use while working with the JS library, in one place. I am going to tell you what steps did we take to achieve the desired solution.

Type definitions

You can describe all data that are being exported by a particular JavaScript module. The TypeScript analyzer will pick it up and will handle the package in a way you defined it in the type definitions file. The approach is close to C/C++ declaration files. Here is a simple example, imagine you have a trivial JS module:

// sample.js

export const pageSize = 25;
export const pageSizes = [25, 50, 100];
export const getOffset = (page, pageSize) => page * pageSize;

one simple `sample.js` module might look like this

You can use the sample.js module in TypeScript code without any problems. But guess what? The analyzer would not be able to run autocomplete and infer types properly. If we want to rely on help from smart tools, we need to manually describe the API provided by our JS module. Usually, it is pretty straightforward to do:

// sample.d.ts

export const pageSize: number;
export const pageSizes: number[];
export const getOffset: (page: number, pageSize: number) => number;

standard way to declare types for TypeScript is to create an appropriate `.d.ts` module

Note that definition files have priority over JavaScript modules. Imagine you removed export const pageSizes = [25, 50, 100] from the sample.js module. TypeScript would still think it exists, and you will get a runtime error. It is a known tradeoff to keep definition files in sync with real JavaScript code. Teams try to update type definitions as soon as possible to provide a smooth experience for other developers. In the meantime, this approach allowed the TypeScript codebase to raise gradually without having to rewrite the whole JavaScript ecosystem.

There are many examples of how to write type definitions. Most of the time you will meet simple cases and thus would be able to find something similar in the repository called DefinitelyTyped, where developers store definitions for NPM packages. You can also learn more about the type definitions feature in the official documentation. It is not a part of this article.

Our JavaScript library

In our company, we develop an internal UI components library. We use it in our products from the beginning, and the current production version is 12. You could only imagine how much effort it would take to rewrite such a big thing. In the meantime, we write new features using the TypeScript language. The problem is, every time one team goes to implement a new code, they write a small copy of the UI library definitions. Well, this does not sound like a good process, and we decided to have a separate package with complete type definitions for our UI components. Key points here are:

We would be able to import this package during the new repository initialization. This will allow controlling the version and simplify the refactoring during the version update.
We would stop copy-pasting the same code again and again.
Type definitions is a great documentation source. I bet developers would prefer to select the method from IntelliSense suggestions rather than go to the web page with all API descriptions and copy the method name.

So what is wrong?

Now you may ask me, what is wrong with our library? The thing is that we inject some global variable to interact with the exposed API. In addition, we want to import some constant pre-defined values (icons, table cell types, tag colors, etc.) that can be used by the UI components. They usually come in form of constant identifiers that help to style components.

For example, we can style a button with one of the types:

// lists/button.ts

export enum ButtonType {
  Primary = "ui-primary",
  Secondary = "ui-secondary",
  Danger = "ui-danger"
}

depending on the value, the button will be rendered in a specific size and color palette

We came to an idea to store all library-specific values in one place. So this project became not just type definitions for the UI library, but a real package! It should represent the exact library state at some specific version. And this is interesting - how can we implement this? Let's state what we want to achieve as the result:

We want the global variable ui to be accessible without having to import anything.
We want our UI components definitions to be available without having to import anything as well.
We want to use predefined constants and objects for UI components by importing them from our types package. There should not be any conflict to assign some type from the library in this case.

Sounds like a small deal, right? Let's write some .d.ts file with type definitions and... Oh, wait, you can't put real code (constants, enumerable lists, and other stuff) in the .d.ts file! Sounds reasonable. Let's create a regular .ts file and put all these enums there. Then we... well, how can we apply globals in the .ts file?! Meh...

We did not find an example of how to do that, really. StackOverflow is flooded with the .d.ts vs .ts concept war. We had nothing but digging into TypeScript documentation and finally introduced the code that meets our requirements.

Start from the scratch

First things first. We write interfaces and enums as usual. I am going to provide code examples in a simplified matter, so we would focus on the approach, not the particular code features. Imagine we have a notification dialog, so we write something like this:

// interfaces/notification.ts

import { ButtonType } from "../lists/button";

export interface NotificationButtonConfig {
  text: string;
  type?: ButtonType;
}

export interface Notification {
  info(text: string, buttons?: NotificationButtonConfig[]): void;
  warning(text: string, buttons?: NotificationButtonConfig[]): void;
  error(text: string, buttons?: NotificationButtonConfig[]): void;
}

simple notification API allows assigning a text message and buttons

Where ButtonType values are from enum we saw already:

// lists/button.ts

export enum ButtonType {
  Primary = "ui-primary",
  Secondary = "ui-secondary",
  Danger = "ui-danger"
}

we highlight a button according to the type

Then let's take a look at the simple case. We don't import anything, as the UI components expose the global variable, and we want to call a notification:

// example/application/moduleNoImport.ts

ui.notification.info("Document has been saved!");

we call a global API to show the notification dialog without custom button configuration

What do we need to do to make it available? We are going to enrich the global namespace with the ui variable:

// index.ts

import { UiLib } from "./interfaces/ui";

declare global {
  let ui: UiLib;
}

we simply add a new variable into the global namespace

UiLib here describes everything our UI library exposes into the global scope. In our example, we have a list of methods that show different kinds of notifications:

// interfaces/ui.ts

import { Notification } from "./notification";

export interface UiLib {
  notification: Notification;
}

all the notifications API is collected under the Notification interface

This is almost it. Lastly, we adjust the package configuration. We tell TypeScript to emit type declarations by adjusting the tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "dist/",
    "outDir": "dist/es"
  }
}

always emit declaration files

We now control how TypeScript emits the output. We also specify a path to our types in package.json:

{
  "main": "dist/es/index.js",
  "types": "dist/index.d.ts"
}

don't forget to set up a build step for your package to compile TypeScript files

Alright, then we install the package in our project. Finally, we specify the package path in the project's tsconfig.json (since we don't use the default @types folder) to see that it works!

Using the values

Now let's go deeper. What if we want to create a notification with some specific button? We want to be able to write something similar to this example:

// example/application/moduleWithImport.ts

import { UiCore } from "ui-types-package";

const showNotification = (message: string): void =>
  ui.notification.info(message, [
    { text: "Sad!", type: UiCore.ButtonType.Danger }
  ]);

we want to show notifications with the button of Danger type

Note here and below UiCore is a namespace that contains all the enums, configs, interfaces our UI library operates with. I think it is a good idea to collect everything under some namespace, so you would not think of names for each interface. For instance, we have a Notification interface. It sounds quite abstract, and it takes a while to understand the exact object behind the naming. In the meantime UiCore.Notification clearly describes where it comes from. Having a namespace is just an optional but convenient way to handle such things.

Right now we can't import UiCore from the library as we don't export anything. Let's improve our code and form the namespace:

// namespaces/core.ts

import * as notificationInterfaces from "../interfaces/notification";
import * as buttonLists from "../lists/button";

export namespace UiCore {
  export import NotificationButtonConfig = notificationInterfaces.NotificationButtonConfig;

  export import ButtonType = buttonLists.ButtonType;
}

we use composite export to create an alias for objects under the namespace

We basically export all data we have under the namespace with export import alias syntax. And, since the main package module is index.ts in the root, we write a global export to expose the namespace to the public:

// index.ts

import { UiLib } from "./interfaces/ui";

export { UiCore } from "./namespaces/core";

declare global {
  let ui: UiLib;
}

we export UiCore, and now it is available from the outside

Two simple steps to achieve our goal! Now we can import some enum and enjoy writing the code. OR. Or we can think of some other use cases. In the example above, we used the ButtonType.Danger value to create a notification with some pre-defined button. What if we want to use ButtonType as a parameter type?

Covering edge cases

We are not going to use some particular value, so we expect to access the type UiCore.ButtonType without having to import anything. Currently, we don't have UiCore in the global scope and thus the code below does not work:

// example/application/moduleWithType.ts

const showNotificationWithButton = (
  buttonText: string,
  buttonType: UiCore.ButtonType // <-- TS2503: Cannot find namespace 'UiCore'
): void =>
  ui.notification.info("hello world!", [
    { text: buttonText, type: buttonType }
  ]);

TS2503: Cannot find namespace 'UiCore'

Obviously, we are going to add the namespace in the global scope. Unfortunately, we can't just use the namespace created earlier, we need to define a new one. The trick is to create a new namespace with the same name and with almost the same data included. Good news: instead of importing everything again, we can use our existing namespace to clone the data in form of types:

// index.ts

import { UiCore as _UiCore } from "./namespaces/core";
import { UiLib } from "./interfaces/ui";

export { _UiCore as UiCore };

declare global {
  namespace UiCore {
    export type NotificationButtonConfig = _UiCore.NotificationButtonConfig;

    export type ButtonType = _UiCore.ButtonType;
  }

  let ui: UiLib;
}

we create types from the existing namespace using the type alias syntax

We first rename the UiCore import as we want to avoid name conflict. Then we re-export UiCore under the correct name as it was done previously. Finally, we copy the UiCore namespace items under the global scope. Both namespaces (UiCore and global UiCore) export the same data. The only thing I want to draw your attention to is the way how we write export statements:

// UiCore under the global scope
export type ButtonType = buttonLists.ButtonType;

// UiCore that can be used as a value
export import ButtonType = lButton.ButtonType;

different syntax for each case

You can see the global namespace uses type alias syntax to define objects. For import statements, we want to have values (not types) accessible, so we can't use the same approach there. Instead, we import values and re-export them under the namespace using the composite export import operator. Thus, we collect all the constants, models, enums, interfaces under some common name, we can name it whatever we want, and it will be a single entry point for all our UI library-related data. As the result, we collected all data in one place, and the developer experience does not change from using the global object to having to import something.

This part is a tradeoff to get all usage cases working. It adds some copy-paste routine, but then it is a comfortable way to supply developers with type definitions: we can use the global variable exposed by the UI library as we do in JavaScript modules — without having to import anything. Then we can import the package and use constant values. All of them are defined and ready to use. The existing code will remain the same. And yes, we do support the new import type { UiCore } from "ui-types-package" syntax which was introduced in TypeScript v3.8 to define types. There is no conflict with our implementation.

Conclusion

You can find thousands of existing type definitions for JavaScript libraries. In this article, I tried to explain some specific edge case, where along with type definitions, the package needs to contain real values. We use this approach for our UI components library to style table cells, specify icons, and more. You can achieve such capabilities by following these steps:

Create and set up a new NPM package.
Describe the whole interface supported by the JavaScript library you want to write type definitions for.
Declare the global object that is being injected into window.
Create a namespace made of objects you have defined already - you will use it for import statements.
Create a namespace made of types based on the previous namespace. It will be located in the global scope.
Verify that we assigned the same name for both namespaces.

This small guide makes it possible to cover all potential use cases for any available JS library. In the end, you will get a package, that is easy to use, support, and extend.

The name UiCore, the package ui-types-package, and all objects in the article are placeholders to show the approach. You can use whatever names you want for your libraries and follow the idea described here.

Complete code example is located here.

What I Learned From My Contribution to Angular

Sergey Nikitin — Fri, 02 Apr 2021 16:28:37 +0000

ANGULAR 9 has come, and you might notice my name in the commit history. This was the first time I contributed to such a big and widely-used project. The journey appeared to be easy enough and very exciting! Was it so? Let me tell you the story.

In our company, we went through a bunch of technologies and approaches on how to develop frontend code. Initially, our service was written using the Grails framework — Java-based MVC server-side rendering engine. JQuery used to add some interactions with customers on the page which was quite common those days, but you definitely don’t want to see this in 2020.

A few years later, AngularJS showed up and it was like fresh air in frontend development. Services, components, template rendering engine, etc. We were happy to implement AngularJS on our platform and wrote over 700k lines of code.

Time flew and one day Angular (which was expected to be AngularJS v2) was released. The problem was that these two things are not compatible with each other, so our codebase became legacy at one moment. I pushed hard to update the version of the AngularJS and gave up on v1.5.11. What was the solution? We decided to keep existing applications as it is and to select a new way to write frontend inside the company. The thing is that our platform consists of independent applications each of them loads unrelatedly to others. Thus, every application can be written using any library or framework the team decided to use.

First of all, we switched to build js code with Webpack and removed Browserify for goods. This brought us a lot of opportunities like how we split bundles, what JS features are supported, and so forth. Then the time has come and we added Typescript. After all, we implemented React on the platform. Currently, engineers develop new applications using React. But fair to say that our vision remains the same: each team decided what to use on their own. Some teams still use AngularJS because it is too difficult to re-implement existing logic. Others still fix Grails applications (yes, we still have a few of them in production at the moment!).

The idea to tune up the infrastructure for Angular was flying in the air, but it was quite tricky until we started to use Webpack. With Webpack it seemed to be an easy deal: load CSS modules with raw-loader, fix Jest HTML templates loader and we good. Good enough? I thought so until we started to write an application based on the Angular framework…

Something Went Wrong

The problem appeared from a place we did not expect. Let’s make some introduction: we use UI component package which renders a beautiful and strict UI experience for our clients. This library is framework-agnostic and acts quite similar to Material UI components for Angular i.e. developer forms a specific HTML layout to bring particular component into action, populate and style components by applying pre-defined element classes and tags. Also, one can access any element in the JS code and play with it dynamically.

So it was my colleague Irina, who found an interesting issue. She was the first person to try Angular on our platform. Historically, the UI components we use rely on the HTML element attributes. These attributes have the form of data-ts or data-ts.something. For instance, if we want to implement a modal window, we should add the title by setting data-ts.title attribute:

<dialog data-ts="Modal" data-ts.title="some-title">
    <div data-ts="Panel">
        <p>Modal content.</p>
    </div>
</dialog>

Pretty straightforward, right? But what if we want to apply the title dynamically? Let’s say we want the title to contain a user name or something like this. What should we do? Yes, Angular provides a standard way to interpolate the attribute value from the controller property:

<dialog data-ts="Modal" [attr.data-ts.title]="modalTitle">
    <div data-ts="Panel">
        <p>Modal content.</p>
    </div>
</dialog>

Here we go! But wait… what?! This does not look good in the browser:

You may notice here that the Angular compiler went through the HTML template and parsed attributes in the wrong way. For attr.data-ts.title symbol it generates data-ts attribute instead of data-ts.title. This completely breaks the layout and the modal window does not work. UI components even don’t know that I defined a modal window because the attribute was overridden with the result of interpolation. It sounds like a real blocker that prevents us from using Angular.

Trying to Find a Solution

I tried to google the solution but had no luck. I felt like it is meant to be a very specific case nobody noticed really. Fair enough. On the other hand, if HTML standard supports this type of element attributes and browsers render them correctly, so should Angular compiler do. Taking this into account, I decided to ask Angular team directly. I went to Angular GitHub repository and opened an issue. The beginning was promising, they marked my issue with tags that highlight that the bug exists in the Angular compiler and the issue has low priority. What happened next? I started waiting…

…After 2 months nothing really happened. I figured out that since my problem is not something major, then there are low chances to see it fixed any time soon. The team is busy making the Ivy engine into a stable version. Nonetheless, they confirmed the bug exists, so they would not be against me fixing the issue by myself. Okay then, I am doing a fork of the Angular repository.

I am Going to Fix the Bug

First of all, I drew my attention to the CONTRIBUTING.md file and read it carefully (consider making a project fork to be my zero step). This file describes all the rules I should follow so Angular team will proceed with my Pull Request. It explains the responsibility of the parties, code ownership, agreement on the commit message format, test coverage requirements and many other questions.

Next, you need to sign the Contributor License Agreement with Google company which confirms you are okay with all contributing rules and restrictions. The CLA link is located at the end of the CONTRIBUTING.md file so read the whole text until the end. Finally, paperwork comes to an end, let’s dive into the project itself.

Angular is a typical yarn project, just big enough. You can simply run yarn install and it will setup all the environment. Well, okay, simply run yarn install and simply wait for 5–7 more minutes — I told you this is a big one!

I stopped for a second at this point, because I was looking forward to an exciting journey — to go through the source code. It was scary in the beginning to figure out what is going on in such a huge project, tons of modules, different pieces of code interact with each other. But after spending some time I came to the conclusion that big projects mean to be a big advantage.

When your project becomes huge, you focus on absolutely different things that might sound meaningless when you have just a few files. Different things, different approaches show up to be the priority. In the Angular, I saw that the project structure is a super important thing. Every module has a meaningful name, every variable document itself, every method shows what it does exactly. It is quite easy to navigate through the framework parts and the understanding of what this or that module is for comes to your mind instantly.

I already knew that my issue lays somewhere in the Angular compiler and it was quite easy to find the exact line:

" width="799" height="220">

Well, what is this? We receive an HTML element attribute (stored in the boundProp). Then we split the attribute name by some delimiter to figure out if it contains “attr” prefix. If the first part is the prefix, we consider the attribute name to be equal to the second part. Obviously, this is not correct, we should concatenate all the parts except the prefix instead. Let’s fix it:

Perfect! Now we need to make sure other changes would never break our functionality. I am going to write a test. It is quite easy to do in such huge projects like Angular. There is a requirement to cover any code change by unit tests so you definitely will find a spec file along with each module in the repository.

So I opened that spec file and saw a bunch of tests that cover the module I have changed. I went through the 2000 lines of test cases and found the test which checks the name of the attribute after compiler parsed some HTML element. Made a copy and changed attribute name, so now it contains a dot delimiter and fixed the output expectation. That’s it. Now my changes are covered! I thought it would be tough, but turn out it was super easy:

Well, I fixed the code. Writing a commit message keeping in mind the format team asked to follow and… going to the kitchen to make some tea as the pre-commit hook launches all unit tests in the project. Can you imagine having 37000+ tests in the project? The first launch will take a while, but then test results will be cached and next runs will take much less time. I made a commit, opened a Pull Request, started waiting…

Resolution

…After 2 months I decided waiting is enough for me. The code was the smaller problem, the bigger one was how to proceed with my changes? It was clear to me that I need to find a person who is somehow related to the Angular team and discuss what options I have right now. I applied the social engineering approach and went through the latest contributors to the Angular compiler module. Andrew Kushnir was the first on my mind. I found his Facebook account and wrote him a message. Unfortunately, a week after I did not get a follow back and decided not to be annoying for the person who doesn’t know me. I decided to have another try and found Pete Bacon Darwin. I noticed that his profile has an email address so it might be useful even in 2019. And it actually did work!

I wrote a long email describing all the little things we struggle with. Described our UI library, attached links on the issue and pull-request. I told about myself and my company. And most important I was really thankful as expecting Pete to spend his own time on my problem.

The next day I found a message from Pete. He told me that he is okay to contact via email about my pull request and that he never saw people define attributes with dot notation. He also gave me a piece of advice on how to write an accurate commit message. And then, he approved my code changes. After this, all happened with the speed of light… while I was sleeping. (guess why? 12 hours difference between the US and Novosibirsk — the place where I live)

While I was sleeping, the Angular team moved my pull request into a release state. They ran another set of tests (I guess they were integration tests this time) and figured out that in one test there was an SVG-block with some interesting attribute [attr.height.px]=”16". It used to be rendered as height=”16", but with my changes, it became height.px=”16". After a small discussion, they decided to fix that SVG block and to merge my changes into Angular. This meant that my fix will show up in the upcoming major version of the framework!

My commit was merged, my pull request was closed. I just got up in the morning and saw all these comments, was scared, upset, and glad at the same time.

In the evening I got an email from Pete. He confirmed that my fix will be released with Angular v9 and thanked me for contributing to the project.

From my side, I paid appreciation for the time he spent on me and for all the help. I said that it was quite an important step for me to make things right and to make a success.

You may ask me what’s next?

Next few months I was waiting for the release. I noticed that my changes came with Angular 9.0.0-rc.2. And now, literally, a month ago they have released the stable version of the Angular 9.

The outcome

For me, it was a success story. We finally got Angular based applications working on the platform. But the most important thing here is that I did my best to gain the result. So, go all the way and never give up. Try different ways to achieve what you want. Push the stuff you think is right. Look for people who can help you to find a way to deliver.

If you see a big popular project in front of you, it does not mean you can’t influence it. If you have an idea or you believe something works not as expected — just try. Even if the cost of your changes is a one-line fix. In most cases, the team is open to external contributions and any help from other developers. They might have no time to fix this or that issue. So you are welcome to offer your help.

I have this article posted in Russian as well, so if you want you can read the translated version here.