DEV Community: Nico Prat

Smooth gradient animation using @property

Nico Prat — Mon, 09 Mar 2026 15:34:44 +0000

I recently stumbled upon a small CSS challenge: we needed a pulsing ring of color, something subtle but noticeable enough to catch the user's eye. At first it sounded like an easy task, but after trying a few different approaches it turned out to be trickier than expected, at least if you want the animation to feel perfectly smooth.

Eventually it became a good opportunity to finally experiment with the new CSS custom property registration feature, so here’s a short post showing what worked and what didn’t.

TL;DR: here's the working solution using radial gradient background and @property 👇

The theory

The @property syntax is an improvement over the basic custom properties we already know, like --size: 20px. The declaration syntax looks like this (MDN docs):

@property --ratio {
  syntax: '<percentage>'; /* allows the browser to interpolate values */
  inherits: false;
  initial-value: 0%;
}

The custom property can then be set and used as usual:


div {
  --ratio: 50%;
  padding-bottom: var(--ratio);
}

And we can animate it as well:

@keyframes ratio {
  from {
    --ratio: 50%;
  }
  to {
    --ratio 100%;
  }
}

In this example it doesn’t provide anything that couldn’t be done otherwise, but its real power comes from allowing animation of only parts of a value. For instance, background-color is animatable, but background-image is not. At least, not without using custom properties as we’ll see in a moment.

The practice

So the goal is to animate a ring that grows from its center. Here are the constraints:

it should be smooth (meaning nicely anti-aliased)
it should have a consistent thickness throughout the animation

Let's try a few different techniques...

❌ Outline offset

For the first attempt, I used outline-offset. It’s very simple, but the issue is that the value is discrete (not continuous), meaning it animates pixel by pixel instead of subpixel. This is less noticeable on high-DPI displays, though I slowed down the animation here to make the issue more visible. The result doesn’t feel quite as smooth as we’d like.

Here's a GIF if you can't see the CodePen in action:

❌ Scale

Then I tried using scale. Still very simple, but the issue is that the thickness grows as well. Yes, I tried to cheat by reducing the border-width value during the animation, but like outline-offset, it’s also discrete, so the width jumps during the animation. What's more, Safari seems to use a rasterised version of the element and the result is very blurry.

Here's a GIF if you can't see the CodePen in action:

✅ Radial gradient

Finally, I tried using a gradient background, and this time everything is smooth! The idea is not to use a real gradient, but to use its API to draw a solid line that moves.

The downside is that the implementation becomes slightly more complex because it requires an additional element on top of it that is larger than the original one in order to draw the gradient inside it (backgrounds can’t overflow their element).

Here's a GIF if you can't see the CodePen in action:

As you can see in the code, the trick is to animate the gradient color stops values through the --pulse-size custom property. Once the correct calculations are in place, it becomes easy to reuse and adapt the code using variables.

.pulse {
  /* original value */
  --pulse-size: calc(100% / var(--ratio));
  /* drawing the circle */
  background: radial-gradient(
    /* shape and positioning */
    closest-side circle at 50%,
    /* starting point */
    transparent 0%,
    /* stop drawing transparent */
    transparent calc(var(--pulse-size) - var(--thickness)),
    /* start drawing colored circle */
    var(--color) calc(var(--pulse-size) - var(--thickness)),
    /* stop drawing the colored circle */
    var(--color) var(--pulse-size),
    /* start drawing transparent again */
    transparent var(--pulse-size),
    /* ending */
    transparent 100%
  );
  /* animating the circle */
  animation: pulse 2s 0.35s infinite ease-out;
}

In CodePen you'll see some - 1px, there're here to prevent Safari from drawing aliasing artefacts.

Now we can simply animate the custom property instead of the whole background gradient (which wouldn’t work anyway):

@keyframes pulse {
  100% {
    --pulse-size: 100%;
  }
}

The original value for --pulse-size can't be in the @keyframes definition as it seems to fail in Firefox at the time of writing, so I set it in the element style directly. Frontend wouldn't be fun without some weird browser quirks here and there, right?

Conclusion

So the solution was to use a technique that:

keep the size of the element itself: no scale
use continues values to prevent "jumps" in the animation: no border or outline
doesn't suffer from weird browser issues (like scale in Safari)
keep the document flow intact to get a fluid animation

Would you have come up with another solution?

How to write reviewer-friendly pull requests

Nico Prat — Fri, 17 Oct 2025 07:54:37 +0000

Reviewing someone else's work is often challenging and time-consuming. It can easily lead to procrastination, frustration, or even tension between developers. Yet, it's an essential part of our daily workflow and deserves careful attention.

Below are a few unordered tips we've gathered over time to make reviewing pull requests easier (from the author's perspective) to help prevent issues before they arise.

We use GitHub, so some examples are specific to it, but the same ideas apply to most alternatives.

1. Write small pull requests

This is the most common (and probably the most important) advice. To reinforce it, we automatically add t-shirt-sized labels to our pull requests. This encourages authors to keep them short and reassures reviewers that the review won't take too long.

2. Always prioritize readability

This applies not only to the codebase itself but also to the files diff. Don't hesitate to add code comments that provide context (eg. data format examples) even if they seem redundant with TypeScript types or equivalents. Anything that helps someone understand the code outside of an IDE is worth including.

3. Create a simple template

Use GitHub pull request templates to make authors' work easier and ensure consistency across pull requests. A short template with three or four sections (and maybe a few checkboxes) is often enough to remind authors of key steps in the process.

4. Explain why it's done in the description

Include any relevant specifications, documentation, or conversations related to the pull request. This not only helps the reviewer but can also help yourself realize if something has been overlooked (which happens more often than we'd like to admit). Plus, even if the reasoning seems obvious now, it will help future developers understand the decision (especially years down the line). Obviously, make sure to explain how the feature is supposed to work.

5. Explain how it's done in the files diff

Before requesting a review, review your own diff. You might catch accidental commits, hard-to-read code, or even mistakes. It's frustrating for reviewers to find easily avoidable errors. Also, force yourself to add helpful comments in the diff: I personally often find that they actually belong to the code itself and add a commit for them.

6. Help the reviewer with tips

I often add "guided tour" comments in the diff, like suggesting to "review with whitespaces ignored" or to "review commit by commit". These small hints can make the process much easier. You can also mark some code lines that are open to discussion or feedback. Encourage the reviewer to be part of the collaboration, not just a gatekeeper.

7. Make a unique commit for renaming or moving files

Whenever you rename or move files, make it a separate commit from content edits. (Git and GitHub sometimes detect this automatically, but not always.) This allows reviewers to skip the rename commit and focus on the real changes, instead of a massive "deleted and added" diff. This practice made our TypeScript migration much smoother for instance.

8. Rebase commits

Coding is rarely linear, mistakes are made, sometimes fixed a few days afterwards. Before opening a pull request, consider taking some time to rebase commits to make the history more readable. Don't try to make it perfect, but at least regroup commits that belongs together so it makes more sense when reviewed.

9. Suggest a pair review if necessary

For complex pull requests or ones that require intricate setup, a pair review might be faster and more productive. It's also a great opportunity to explain your code out loud: often, you'll discover parts that are hard to justify or could be simplified.

10. Kill your ego

Take feedback with an open mind. Make reviewers feel appreciated for the time they spend on your work. This way, they'll be more eager to review for you again. Remember that it's usually more valuable to make the reviewing process smooth and collaborative than to be "right" at all costs. That's easy to forget when we're deep in the work.

I hope those tips can help making this complex task smoother in your daily workflow!

Automatically take care of outdated browsers thanks to Browserslist and Github Actions

Nico Prat — Mon, 28 Jul 2025 08:46:32 +0000

Our policy is to support browsers released within the last two years. Previously, we used Browserslist to transpile our code and automatically add polyfills. At some point, we wondered if we could use the same configuration to inform users when their browser was too old — ideally, without needing to write or maintain that logic ourselves.

It's all in a regex

Fortunately, there's a package that does exactly that: browserslist-useragent-regexp. It generates a regular expression based on your Browserslist config, which you can run against navigator.userAgent.

Here’s a simple .browserslist.rc config targeting our policy:

last 2 years
not dead

Then, you can generate the regex using a script in your package.json:

{
  "scripts": {
    "supportedBrowsers": "npx update-browserslist-db@latest && echo \"export default $(browserslist-useragent-regexp --allowHigherVersions);\" > supportedBrowsers.js"
  }
}

The npx update-browserslist-db@latest command ensures your caniuse data is current, preventing the dreaded Browserslist: caniuse-lite is outdated warning.

This script outputs something like:

export default /Edge?\/(10[5-9]|1[1-9]\d|[2...

You can then import and use this regex in your app to notify users:

import supportedBrowsers from './supportedBrowsers.js'

if (!supportedBrowsers.test(navigator.userAgent)) {
  alert('Your browser is not supported, please update it.');
}

Automate the update

To keep the regex up to date, we use GitHub Actions to run the script automatically every month. That way, our last 2 years policy always reflects the current calendar without anyone needing to remember to update it.

Here’s a simplified version of our workflow:

name: CI - Update browsers list

on:
  schedule:
    # At 8:00AM UTC the first day of the month
    - cron: "0 8 1 * *"

jobs:
  update_frontend_browserslist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Update browsers list
        working-directory: components/frontend
        run: npm run supportedBrowsers

      - name: Commit and push changes if any
        run: |
          git config user.name Internal
          git config user.email internal@yourcompany.com
          # Check if there are any changes to the browsers list
          if [[ -n "$(git status --porcelain .)" ]]; then
            git add .
            git commit -m "chore: update supported-browsers.ts"
            git push
          fi

With this in place, we get a fresh, accurate regex every month — keeping users informed only when necessary, without adding manual work for the team.

What we learned by running an accessibility audit of our app

Nico Prat — Tue, 11 Feb 2025 13:30:06 +0000

We recently underwent an accessibility audit (thanks to Access42) for our app due to compliance regulations for large companies in France. Initially, we believed we were in good shape because we use modern tools, adhere to basic HTML structures, and avoid unusual ergonomics.

However, we decided to invest effort into this area as we needed to meet a minimum score, and the scoring system is quite stringent: any failure on a specific criterion on any audited page counts as a failure, which can quickly degrade the overall score.

That's when we realized just how poor our accessibility was, how complex the subject is, and how much work lay ahead of us...

Before diving in

As a typical developer, I initially believed that accessibility was merely a technical issue to be resolved. However, I soon realized I was mistaken, and I would like to share our experience before delving into more concrete details.

Get a proper training

It's easy to assume that accessibility is straightforward, but like everything in web development, there's a rich history, numerous quirks, and backward compatibility issues that complicate matters.

Fortunately, four developers and I had the opportunity to participate in a three-day training session, including hands-on testing of our own app. This was incredibly instructive. We were able to experiment with tools and ask questions on the spot, which was far more efficient than spending hours on Stack Overflow trying to figure out why VoiceOver wasn't behaving as expected...

Involve every stakeholder

A web app should be designed with accessibility in mind from the outset, much like performance and other cross-cutting concerns. While developers can implement fixes, these solutions are often less effective for users and require more effort from the team. Examples include manually adding aria-label attributes to icon-only buttons, creating textual alternatives for complex objects, and managing focus states manually when informations are spread on the interface.

Certain design-specific aspects, such as text size, color contrasts, and considerations for color blindness, cannot be addressed by developers alone. Currently, here, developers are primarily responsible for ensuring the accessibility of the product through testing. However, we hope that a culture of accessibility will gradually permeate all aspects of our work over time.

Understanding the accessibility tree

You might already be familiar with the DOM (Document Object Model) and CSSOM (Cascading Style Sheets Object Model), but we discovered that there is another, less visible underlying model: the accessibility tree.

It is primarily derived from HTML elements and results in four properties for each element:

name: a kind of identifier
description: a secondary string describing the element, similar to a tooltip
role: one of the list of roles. By default, it is generic; a button will be button, an a will be link, and it can be overridden by the role="" attribute.
state: indicates if the element is currently active, expanded, pressed, checked, etc.

Understanding these properties is crucial for correctly using attributes like aria-label, title, aria-describedby, and so on, as well as knowing their priority. For example, aria-labelledby takes precedence over aria-label. Modern browsers now offer a view of the accessibility tree in their developer tools, making it easier to debug. More on this later.

Subjectivity

One final note before diving in, regarding what may be the most challenging aspect of accessibility: subjectivity.

Here are some scenarios where it can be difficult because no tool can help you make a decision:

Should this text be a heading or a paragraph?
An image has an alt attribute, but is it truly meaningful?
A "skip" button has been added, but is it genuinely useful??
Should this notification be polite or assertive?

In short, even a 100% accessible website could be frustrating to use with a screen reader. The best way to assess this is to use it ourselves under "real" conditions. The only downside is that it's time-consuming, so I suspect few companies actually do it.

Using accessible librairies

Chances are that you rely on a UI library for common components. You first want to make sure it's already accessible enough, or else you'll lose a huge amount of time trying to fix errors that you don't actually control. In our case, we're migrating from ElementPlus to Radix Vue mainly for this reason.

It seems modern tools finally treat accessibility as a first class citizen, but it was not the case just a few years ago! Ark UI looks like a good alternative too. You can check their docs and even use the tool below to check its accessibility compliance.

We can also refer to Offical WCAG rules for simple and framework-agnostic examples.

Manual testing

Now that we have the basic theory, it's time to get our hands dirty and find issues and test fixes. Here are the main tools we used:

Browser accessibility devtools

Browsers have come a long way in terms of tooling, and it's really helpful to understand the state of a specific element and why it's considered that way. For instance, the aria-label attribute takes precedence over the title attribute, so Chrome indicates that it will be ignored:

It's not as clear in Firefox, but other information is provided:

Each browser offers different tools with their own advantages and disadvantages, so feel free to try them out to find your preferences.

Axe browser extension

Axe is probably the most well-known suite of tools for testing and improving accessibility. It is essentially included in every major testing solution, as we'll see next.

You can find the Axe extensions for browsers on their website (available for Chrome, Firefox, and Edge). It offers a lot of tools to identify accessibility issues:

While it might not be the most feature-complete, as indicated in this study by the British Government, it is probably better to have consistent test results across your tools (unit tests, manual tests, E2E tests, etc.) than ultra-exhaustive error reports.

Windows, Firefox & NVDA

This setup is the most widely used worldwide, and NVDA is the most valid and feature-complete free tool available, so it should be preferred when doing tests. If you're on Mac, you can use a virtual machine (we chose Parallels Desktop with Windows 11, which took about 30 minutes to set up and ~130€ one time payment).

MacOS, Safari & VoiceOver

VoiceOver is included in every Mac and can be toggled by pressing CMD+F5. It's pretty good by default, but it is known to have some quirks. For instance, it won't read aloud any alert that uses anything other than alert (log or status won't work). If you're on Windows, unfortunately, there's no way to emulate it locally.

Using BrowserStack

Online virtual machines can be useful too. We didn't try them, but BrowserStack currently supports screen readers, and there could be other tools offering similar functionality.

Automated Testing

Unit Tests

We believe unit tests are not particularly useful for accessibility, as checking only for HTML attributes is generally insufficient. Tools like Axe can handle this better than manual unit tests, so we didn't use them at all.

End-to-End Accessibility Tests with Cypress

End-to-end tests are better suited for accessibility checks because they closely mimic what users will see and interact with. However, there are some quirks with Cypress, such as handling tab keys to check for focus. You might want to look into cypress-real-events for a potential solution. (Edit: It seems like this issue is finally being considered in Cypress priorities).

I suppose Playwright might not suffer from those issues as it uses a different, more native way of controlling the browser, but we don't use this tool directly for now.

Axe Plugin

We used the cypress-axe plugin to easily integrate Axe into our tests. The upside is that it's straightforward to use; the downside is that reading errors can be challenging (clicking on lines provides better feedback, though):

Cypress Cloud accessibility add-on

Luckily for us, Cypress released a full featured accessibility add-on not so long ago.

It relies on Axe too, but it's much more integrated in the ecosystem. For instance, the online report is very nice (I can't expose the visual of our app unfortunately):

Also, the Slack integration is quite nice too:

The obvious downside is that it's a paid add-on, and it's quite expensive 🥵 so we probably won't be able to keep it in our suite.

Specific Tests

For more specific tests that don't rely on rules covered by Axe, you can add some manual checks. For example:

The first tab should show and focus a "skip to content" link.
After opening a dialog, its first input should be focused.
A notification should be shown once an action is completed (also check its attributes to ensure it will be announced by screen readers).

You can easily find the focused element in Cypress by running cy.focused().

Component Accessibility Tests with Storybook

Storybook proved to be really useful for accessibility testing. It's easier to set up than end-to-end (E2E) tests but still provides visual feedback and debugging tools. It also allows for complex cases where components are used together or under special conditions. You can write specific play functions that use any code or components you need, not just the one being tested.

By the way, Storybook uses Testing Library, which you can think of as an element selector tool with accessibility in mind. For instance, it won't let you retrieve an element by its class name but forces you to check its role or name (remember the accessibility tree we talked about above?). This is because we should test what the user faces, not the underlying code. It might seem like a small detail, but it sets you in the right mindset when testing.

Lastly, Storybook uses Playwright under the hood, so it actually controls the browser instead of creating fake events in JavaScript like Cypress does. This makes it easier to work with native interactions like tabbing, which is huge for accessibility.

Axe Plugin

Once again, Axe is part of the solution with an official accessibility plugin. It provides a checkA11y() function that can be set up to run automatically at the end of every test or manually called in a specific test (using the play() function in Storybook with the addon interactions). Here's a truncated example of what can be done:

// In the config
const config = {
  async preVisit(page) {
    await injectAxe(page);
  },
  async postVisit(page, context) {
    await checkA11y(page, 'body', {
      detailedReport: true,
      detailedReportOptions: {
        html: true,
      },
    });
  },
};

// In the story
export const Default: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    canvas.getByRole('button', { name: 'Show a notification' }).click();

    const notification = canvas.getByRole('alert');
    expect(notification).toBeInTheDocument();
    expect(notification).toHaveTextContent('This is a notification message!');

    // Accessibility tests will be run automatically here
  },
};

Again, it's pretty straightforward to set up. Errors in the interface are clear and actionable as shown below, but it's hard to read in the CI (GitHub Actions in our case) and we didn't spend time to try to improve it for now:

Specific Tests

We especially appreciated Storybook for running our own specific tests. For instance, we had a hard time ensuring that tooltips were used correctly (tooltips are much harder to get right than we initially thought). So, we interacted with the trigger element by focusing it or not and checked that everything was working as expected:

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement);

  const target = canvas.getByText('Hover me to show tooltip');
  // Check tabindex to be sure it's focusable
  await expect(target).toHaveAttribute('tabindex', '0');

  canvasElement.focus();
  await userEvent.tab();
  expect(document.activeElement).toEqual(target);

  const tooltip = canvas.getByRole('tooltip', { name: 'Hello world!' });

  await expect(tooltip).toBeVisible();

  // Check role button to be sure it's read by screen readers
  await expect(target).toHaveAttribute('role', 'button');
},

Another case was ensuring our focus trap always worked within an open dialog. We used the same mechanism to check that we looped through interactive elements without tabbing out.

Linting

ESLint can also help developers avoid simple mistakes early in the development process. We use the ESLint plugin VueJS accessibility, but there are alternatives for other major libraries. While it is the least capable of all the tools we listed, it offers the quickest feedback loop, making it ideal for simple cases.

We had to enforce and create custom rules for our specific use cases to ensure components are used correctly. For instance, our <Tooltip> component should have its interactive element as a direct child, like a <Btn>. We leveraged the vue/no-restricted-syntax rule as follows:

'vue/no-restricted-syntax': [
  {
    selector: 'VElement[rawName="Tooltip"] > VElement:not([rawName=/^(a|router-link|button|Btn)$/]) VElement[rawName=/^(a|router-link|button|Btn)$/]',
    message: 'Interactive elements should be the direct child of a tooltip, or its content will not be read aloud by screen readers',
  }
]

Conclusion

It's virtually impossible to achieve 100% accessibility on a complex web app. Companies that claim otherwise are likely mistaken, whether intentionally or not. Some conduct their own internal audits, which are clearly not as reliable as those performed by an external, independent organization.

We also discovered that there are some difficult and almost undocumented quirks. For instance, a tooltip must be set on an interactive element to be actually announced (e.g., with an implicit or explicit role of button or link; a span would be ignored) and I didn't see documented in common posts and examples. Therefore, the rule is to always test manually and not rely solely on green CI checks for the right attributes.

It must also be said that an audit is outdated as soon as it's done, as nothing prevents the code from changing from that date. In France, an accessibility declaration is only valid for a few years, and it must be rechecked when the website is "substantially" updated, which is quite subjective.

So, the "best effort" technique is the only way to go, and accessibility must be treated with sincerity to be achieved at its best. This involves truly treating it as an acceptance criterion, training developers and designers (and every stakeholder, by the way), having automatic tests, and using manual tools.

Finally, the Accessibility Object Model (AOM) is an experimental JavaScript API that allows interaction with the accessibility tree directly without using attributes, such as button.accessibleNode.expanded = true. This could greatly help developers, as it would eliminate the need to rely on easy-to-break IDs everywhere. However, as everything accessibility related, it might be years before it is widely supported...

Customize TypeScript syntax highlighting in VSCode

Nico Prat — Tue, 07 Jan 2025 18:11:18 +0000

TL;DR show me the code

TypeScript can be intimidating at first glance, especially when you're used to the relative simplicity of JavaScript (or allergic to the verbosity of other languages you might have studied, like me with Java). When I started learning it a few years ago, I found the code harder to scan, as if everything was slightly less readable.

I then searched for a way to better distinguish new code from existing code, and started exploring how VSCode handles visual themes.

Editor Tokens & Scopes

Similar to an Abstract Syntax Tree (AST), VSCode breaks down the code in each file into tokens to create an abstract view of it, making it easier to manipulate. This abstraction is then used to build themes and analyze the code.

To better understand this functionality, there are guides on syntax highlighting and semantic highlighting. The former focuses on static analysis, while the latter understands the code (for example, recognizing that a variable is actually a parameter and thus ensuring it retains the same color for consistency across occurrences):

Simply put, each character in your code is assigned:

A token type: String, Comment, ... (complete list here)
One or more scopes, which act like subsets or groups

Extensions can add new scopes, for example, for Vue files (Single File Components), which contain HTML, JavaScript, and CSS.

Customization

To help us understand this system, VSCode offers a command "Developer: Inspect Editor Tokens and Scopes" that displays a tooltip with information about the currently selected code. Here's an example with the compact function from Lodash:

There’s a lot of information, but the only thing we care about for now is the list of scopes; the most specific scopes are listed first. We can use these to target the elements we want to customize.

Next, we move on to the VSCode settings to adjust the theme to our needs. The documentation explains that you need to edit your settings.json file as follows (use the "Preferences: Open User Settings (JSON)" command):

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [],
        "settings": {}
      }
    ]
  },
}

As I navigated through the code over the weeks and experimented with rule specificity, I came up with this list of scopes (which is likely not exhaustive):

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": [
          "support.type.builtin.ts",
          "meta.interface.ts punctuation.definition.block.ts",
          "meta.type.annotation.ts",
          "meta.type.declaration.ts",
          "entity.name.type.ts",
          "support.type.primitive.ts",
          "entity.name.type.alias.ts",
          "entity.name.type.interface.ts",
          "storage.type.interface.ts",
          "keyword.operator.type.annotation.ts",
          "punctuation.definition.typeparameters.begin.ts",
          "punctuation.definition.typeparameters.end.ts",
          "meta.object.type.ts",
          "meta.type.parameters.ts",
          "meta.object.member.ts meta.type.tuple.ts",
          "keyword.control.satisfies.ts",
          "keyword.control.as.ts",
          "meta.type.declaration.ts punctuation.definition.block.ts",
          "meta.type.declaration.ts keyword.operator.assignment.ts",
          "meta.type.parameters.ts punctuation.separator.comma.ts",
          "meta.type.parameters.ts punctuation.definition.block.ts",
          "meta.type.parameters.ts meta.brace.square.ts",
          "meta.type.annotation.ts keyword.operator.type.ts",
          "meta.type.annotation.ts punctuation.terminator.statement.ts",
          "meta.type.annotation.ts punctuation.definition.block.ts",
          "meta.type.annotation.ts string.quoted.single.ts",
          "meta.return.type.arrow.ts meta.type.tuple.ts",
          "keyword.operator.definiteassignment.ts",
          "keyword.operator.optional.ts",
          "storage.type.type.ts",
          "meta.interface.ts"
        ],
        "settings": {
          "fontStyle": "italic",
          "foreground": "#ff0000"
        }
      }
    ]
  },
}

As you can see, all scopes end with .ts, and scopes can be further refined to ensure they’re nested within another using a space (similar to a CSS selector): "meta.type.annotation.ts keyword.operator.type.ts".

The only thing left is to decide which styles to apply. Unfortunately, the options are limited: just text color and a few font styles (bold, italic, underline, strikethrough), or a combination of these. To avoid color conflicts with a theme, I chose to apply italics, which remain fairly discreet in daily use. I had considered using a very light background color, but this still isn’t possible in VSCode (open ticket since 2016).

Here’s the result on an example from the TypeScript documentation with "fontStyle": "italic":

{width="495"}

Feel free to find what works best for you, for example, bold with "fontStyle": "bold":

{width="499"}

You can even experiment with more unusual styles, such as filter: drop-shadow() (it’s more complicated; here’s how the MoonLight theme does it)](https://github.com/robb0wen/synthwave-vscode/blob/ec7e97eba96febbcf069256a6513ecedd0b187ae/README.md)):

{width="501"}

Conclusion

For me, this trick helped a lot in the beginning to better digest TypeScript's new concepts. I could remove this customization now, but I’ve grown used to it and kept it. I hope it helps some of you get started with TypeScript!

Using BroadcastChannel API with Vue to sync a ref across multiple tabs

Nico Prat — Mon, 02 Dec 2024 15:32:48 +0000

We try to save time for everyone in our team, not only developers: some people spend a lot of time configuring our app for clients or demos, so we make sure it's as smooth as possible. For instance, we try to make every change real time, so there's no need to reload the app for changes to appear.

Recently, we figured out those people usually work with multiple tabs open, making sure the configuration works as expected in multiple pages of the app. So we thought about syncing the configuration across tabs.

We didn't want to store it, neither in session, local storage or anything else, as we will then have to make sure it's always up to date.

That's when we came across the BroadcastChannel API, I didn't even know it existed. It's not fairly new, but Safari was the last to implement it according to CanIUse. Anyway it's largely supported now. You can think of it like the good old window.postMessage() from iframe, but across multiple tabs of the same origin.

Luckily for us, VueUse already made a little composable to ease its usage: https://vueuse.org/core/useBroadcastChannel/#usebroadcastchannel

const {
  isSupported,
  channel,
  post,
  close,
  error,
  isClosed,
} = useBroadcastChannel({ name: 'unique-name' })

So we created a little in house composable based on it to make sure a ref is always synchronized among all tabs:

import { useBroadcastChannel, watchPausable } from '@vueuse/core';
import { nextTick, watch } from 'vue';

import type { Ref } from 'vue';

export const useSync = <T>(value: Ref<T>, name: string, options?: { immediate?: boolean; deep?: boolean }) => {
  // Name must be unique
  const { post, data } = useBroadcastChannel<T, T>({ name });

  // When value changes locally, update other tabs
  const { pause, resume } = watchPausable(
    () => value.value,
    (newValue) => {
      post(structuredClone(newValue));
    },
    options,
  );

  // When value changes in another tab, update it locally
  watch(
    () => data.value,
    async (newValue) => {
      // Prevent watch loop when updating config
      pause();
      value.value = newValue;
      await nextTick();
      resume();
    },
    options,
  );
};

So now we can sync a ref with a single line:

const config = ref({})
useSync(config, 'config', { deep: true });

And voilà! That's some hours saved each month across teams 🥳

Incrementally fixing lots of ESlint errors in a clean way with ESlint Nibble

Nico Prat — Mon, 18 Nov 2024 16:10:46 +0000

As our team is growing, we need more functional and aesthetic rules to keep our codebase less error-prone and more consistent. Fortunately, both our backend and frontend use JavaScript (with the same version of TypeScript) so those changes make a big impact on our daily work for the whole team.

We usually do this kind of improvements on what we call "tech days" (on monday every two weeks) when we can work on tasks we choose ourselves. We try to do them incrementally to avoid long lasting branches that are hard to maintain and review.

Recently, we chose to add the Unicorn plugin, which contain dozens of ESlint rules. It can feel overwhelming at first because it triggers hundreds of errors. Fortunately, we discovered eslint-nibble: a command line tool that helps adding rules one by one with a graphical interface.

How to use it

The first step is to install the new plugin we want to apply. Then, instead of enabling the rules one by one, we can now enable them all in .eslintrc.js. Finally, instead of linting everything at once with eslint, we can simply use eslint-nibble like this:

npx eslint-nibble --fixable-only --no-warnings --cache "./src/**/*.{ts,js,vue}"

it speeds up our process at first with --fixable-only rules
since we don't make CI fail on warnings, we use --no-warnings to clear things up
the --cache option is similar to the ESlint one and will make the repeated process much faster

We're then welcomed by a nice graphic that shows every failing rule with the count of errors for each one:

When selecting a rule through its interface, we're proposed to autofix it (if possible). Then, we usually review it manually before committing, just in case something odd pops up.

Another key point is that it's capable of fixing one and only one rule at a time, even if a line a code contains multiple rule errors. It makes the commits atomic, so it's easy to debug and review for instance.

If you make any additional change before committing — for example we sometimes need to apply Prettier on the changed line — make sure you don't save & lint the file, because it would fix all other errors related to other rules in the file. The correct way is to manually fix the needed problem only by focusing the line and running Quick fix , then use the command Fix without formatting of VS Code.

Benefits

The main advantage is to easily see which rules are the simplest to add next. Each day, we can now choose to fix one rule with a lot of errors, or a lot of rules that have only a few occurrences. Previously, we were blindly enabling rules one by one without knowing their impact in advance.

It's also an opportunity to understand the rule itself by reading its documentation and why it's better (or not) to do it this way, so we learn new things.

We sometimes decide to customize or completely disable a rule because it doesn't fit our needs or code style. For instance, we decided to disable a rule forcing to use Set in some cases: as Vue 2 doesn't support reactivity on Map and Set, we thought it could introduce bugs or encourage developers to use it in an unexpected way.

Finally, it's easier for reviewers to read commits about one rule at a time. This tool makes progressive enhancement a breeze by helping us adding a few ESlint rules from time to time.

How we migrated from Vue 2 to Vue 3

Nico Prat — Tue, 12 Nov 2024 13:16:11 +0000

About one year ago we finally migrated from Vue 2 to Vue 3. It was 6 months before its official end of life. At the time, our app has around 100 pages and 300 components, and used some of the classic dependencies tied to Vue: Vue-router, Pinia (and Pinia ORM), Vue-i18n, TipTap, ElementUI (ElementPlus for Vue 3)

Here are a few advices that helped us. As Vue 2 still work pretty well, you better take the time to ease the migration instead of rushing it, breaking your app and destroying your moral!

1️⃣ Before starting

Warn others

Things will certainly break, even a little. You better make sure it's ok with other teams.

Upgrade to latest Vue 2.7

Obviously, as most of the new features are available in Vue 2.7, and retrocompatible, it's important to catch up if you don't already have. While migrating to Vue 3 you'll still be able to enjoy its features. The step to migrate will also be smaller.

Take the time

This can be a pretty big work so you better anticipate to mitigate the risk over a long period. Also, it helped us (the developers) keep the moral! Plan a few weeks or even months, as you know when you start, but you don't know when you'll finish... Finally, it's better to dedicate some time every week, so any outage won't be disastrous.

Create a team

Don't rely on only one developer if possible, as it's an exhausting task. Also, you need quick feedback & merge loops, because a lot of changes will affect the entire codebase and could create conflicts on a daily basis. It's already hard enough without having to handle this!

Test driven migration

Half of the time will be spent testing the whole app, so you better automate it the most possible. In our experience:

Unit tests are not very useful, as they're usually testing things not really tied to Vue (only "pure JS" functions for instance), se we didn't focus on them
Component testing with vue-test-utils were a pain to migrate, in the end we even had to disable some of them
End to end tests were the most valuable as it's not tied to any JS or Vue internals and failed as soon as a error was thrown away in the app

In conclusion the best is to create so-called "smoke test", where you just navigate within the app with the most basic scenario you can think of. Keep them simple, so they're fast, because the sooner you can make them run, so the more useful they'll be. Bonus point if they run before merging (in a CI for instance).

Type everything

TypeScript helped a bit, but support for it in Vue 2 is still poor. Using TypeScript is still a good idea, but it might not help too much there; Once using Vue 3, the setup syntax will be your best friend though!

Lint everything

It's obvious, but a lot of changes will happen in the code, so does a lot of errors. A simple ESLint / Prettier can save a lot of time. If you already do have them, you can check the new rules for Vue 3 meanwhile you migrate: https://eslint.vuejs.org/rules/

Use Vite

We already had migrated from Webpack to Vite before beginning migrating Vue, so I'm not sure it helps a lot, but as it's the clear standard today, some plugins might not even give instruction for upgrade with Webpack. I guess it's safer to do it first as Vite supports Vue 2, but in the opposite the Vue 3 ecosystem might not support Webpack.

2️⃣ Small steps first

The goal is to have the less changes possible when actually upgrading Vue itself.

Upgrade dependencies

Take a look at every Vue-related dependency you use, and check if there's a version that support both Vue 2 and Vue 3, and upgrade to it. Vue-demi helped a lot plugin maintainers to achieve it, so there's a good chance it's available.

For instance, you might want to migrate from Vuex to Pinia, which support both versions (Vuex still requires a small migration) and is the new standard anyway.

Replace dependencies

For other dependencies, you might want to check if any modern alternative could suit your needs. For instance, we replaced vue-mq by vue-use.

Monkeypatch when needed

We had to be pragmatic, so as some migrations were harder than others, we ended up creating a small layer of abstractions to fix it. For instance, we had a hard time with vue-i18n v9 which brings some (sometimes undocumented) breaking changes. So we finally created a helper that expose a custom version of $t to prevent having to rewrite every component (because this most used function now doesn't accept "nullish" values for basically no reason). In other terms, don't be too perfectionist!

3️⃣ Start migrating

Now the hard work begins. Everything we did before will ease the pain. There's no magic here, it will probably be the hardest part of the migration.

Change everything, but nothing

Replace Vue 2 by Vue 3 with the "migration build" (also called compat mode) by following the instructions.

Turn off every available flag so the app runs almost as it did with version 2.

Check that no breaking change is impacting your app, or fix them.

Small steps

Incrementally enable each flag and test the app thoroughly. If some components are too hard to migrate, keep in mind you can override its compatibility option; so you better merge everything but keep a few components to migrate later instead of waiting for the whole app to work right now. Don't try to fix everything at once, let some days pass so you can catch any bugs (and recharge your mental health).

Big steps

Some dependencies don't provide shortcuts though. In our case, migrating our UI library from ElementUI (Vue 2) to ElementPlus (Vue 3) was hard, and couldn't be split into smaller steps. I heard it was even harder for Vuetify. For this, you'll have to be strong, patient, and take time to do it all at once. Maybe allow a full week for it in your team calendar!

Remember that you can still override the compatibility behavior of each component you import at runtime:

import { ElButton } from 'element-plus'

ElButton.compatConfig = {
  FEATURE_ID_A: true // features can also be toggled at component level
}

Last step

Once every flag has been turned on, it's time to remove the migration build. Hopefully you won't discover new unexpected issues by now!

Don't forget to celebrate, you deserved it! 🥳

Restricting some syntax with ESLint

Nico Prat — Mon, 04 Nov 2024 15:54:20 +0000

ESlint is a fantastic tool to make our code more consistent, and saves our teams a lot of time. There are a ton of plugins that handle most of the generic use cases, but sometimes we have some specific needs, and creating our own rule would take too much time.

For the simplest cases, when we just want to prohibit usage of a function (or anything else actually), we can leverage a default rule: no-restricted-syntax.

Understanding the Abstract Syntax Tree (AST)

Before writing our first selector, we need to understand the underlying system. The AST is simply a representation of a program in the form of nested objects (hence the "Tree" in AST), created by a "parser". It's very flexible because it can be easily read, queried and manipulated. The alternative would be to use regular expressions, but that would be very hard to read and write. So it's basically an intermediate step that allows every great things an IDE does by understanding our code.

To understand how it works, we can play with the AST Explorer, a handy tool that shows a bit of code and its AST in parallel, where you can hover or click on any part of the code to highlight its corresponding AST part:

⚠️ Be careful to correctly select the parser when changing the language.

For instance, when writing Vue code, be sure to use the vue-eslint-parser in our case, because we want to write an ESlint selector. You could also inspect what the @vue/compiler-dom outputs, but you won't be able to query the resulting tree with an ESlint rule.

Creating a selector

The second helpful tool we'll need is the ESLint selectors documentation. It lists the expression we can use to query the AST, and it might feel familiar if you're used to work with CSS. It's based on the same "cascading" behavior, with matchers like descendants, siblings, node and attributes filtering, and so on. Here are some examples from the docs:

AST node type: ForStatement
attribute value: [attr="foo"]
nested attribute: [attr.level2="foo"]
field: FunctionDeclaration > Identifier.id

So, given this code:

const time = dayjs();

It will generate the following AST using @typescript-eslint/parser:

Program {
  body: [
    VariableDeclaration {
      declarations: [
        VariableDeclarator {
          id: Identifier
          init: CallExpression {
            callee: Identifier {
              name: "dayjs"
            }
            arguments: []
            optional: false
          }
        }
      ]
      kind: "const"
    }
  ]
  sourceType: "module"
}

In our case, we need to match a function call (CallExpression) which name is dayjs (Identifier with name property). We also need the direct descendant selector > to be sure we don't match any function call that whould have a dayjs identifier nested within. So the selector will be CallExpression > Identifier[name="dayjs"].

Examples

Simple function selector

Here's our selector to prevent dayjs usage without UTC that you can try live in the ESLint Playground:

'no-restricted-syntax': [
  'error',
  {
    selector: 'CallExpression > Identifier[name="dayjs"]',
    message: 'Always use dayjs.utc() instead of dayjs() to avoid timezone issues',
  },
]

const foo = dayjs();
//          ^^^^^ Invalid
const bar = dayjs.utc();

We also recently decided to ban omit by default and prefer pick so we are sure not to expose sensitive data for instance: ESLint playground

'no-restricted-syntax': [
  'error',
  {
    selector: 'CallExpression[callee.name="omit"], CallExpression Identifier[name="omit"]',
    message: 'Prefer pick() over omit()',
  },
]

omit() // Invalid
_.omit() // Invalid
_.pick()

Inside Vue templates

Here's another example that prohibits a (pretty hacky) way of setting local variables in templates in Vue templates (note that the rule is prefixed by vue/ because it needs the eslint-plugin-vue package):

'vue/no-restricted-syntax': [
  'error',
  {
    selector: 'VAttribute > VExpressionContainer > AssignmentExpression',
    message: 'Do not assign values in templates as it will not be reactive',
  },
],

<template>
  <div :set="(foo = 'bar')">{{ foo }}</div>
  <!-- Outputs <div>bar</div> -->
  <!--       ^^^^^^^^^^ Invalid -->
</template>

By the way you can read more here about this weird trick that caused us a few reactivity issues in the past, so we decided to prohibit it altogether.

Using regex

This is the last example, where we had a case where we needed to forbid the usage of a specific set of translations, so we had to find the t (or any variation) function which has a first argument starting with exports.:

'no-restricted-syntax': [
  'error',
  {
    selector: 'CallExpression[callee.name=/^(t|tc|tf|te|d|n)$/][arguments.0.value=/^exports./]',
    message: 'Do not assign values in templates as it will not be reactive',
  },
],

const translation = t('exports.test');
//                  ^^^^^^^^^^^^^^^^^ Invalid

Conclusion

If you struggle to come up with the right selector, you could ask ChatGPT for help! It's good at explaining selectors too:

Also if you need to restrict imports only, it's simpler to use the no-restricted-imports rule:

'no-restricted-imports': [
  'error',
  {
    paths: [
      {
        name: 'lodash',
        importNames: ['default'],
        message:
          "Please import lodash methods directly to allow tree-shaking, e.g. 'import { map } from 'lodash';'",
      },
    ],
  },
]

This solution works great in the simplest situations, but it won't let you propose an autofix. For more complete solutions, a custom rule should be created instead.

Thanks to those rules, we save time by not repeating the same mistake twice!