{
  "name": "my-cool-vue-components",
  "dependencies": {
    "vue": "^3.5.15"
  },
  "devDependencies": {
    "eslint": "^9.15.0"
  }
}

The main difference is that devDependencies are only needed during the build or development phase, while dependencies are required for the project to run. For example, eslint in the case above only lints our source code; it's no longer needed when we publish the project or deploy it to production.

The concept of dependencies and devDependencies was originally introduced for authoring Node.js libraries (those published to npm). When you install a package like vite, npm automatically installs its dependencies but not its devDependencies. This is because you are consuming vite as a dependency and don't need its development tools. So, even if vite uses prettier during its development, you won't be forced to install prettier when you only need vite in your project.

As the ecosystem has evolved, we can now build much more complex projects than ever before. We have meta-frameworks for building full-stack websites, bundlers for transpiling and bundling code and dependencies, and so on. Node.js became a lot more than just running JavaScript code and packages on the server side.

I'd roughly categorize projects into three types:

1. Apps: Websites, Electron apps, mobile apps, etc. Here, package.json primarily keeps track of dependency information, and the app itself is never published to npm.
2. Libraries: Packages designed to be published to npm, then installed and consumed by other projects.
3. Internal: Packages used within monorepos that are never published.

Fundamentally, the distinction between dependencies and devDependencies only truly makes sense for libraries intended for publication on npm. However, due to different scenarios and usage patterns, their meaning has extended far beyond the original purpose.

Tools often overload the meaning of dependencies and devDependencies to fit various scenarios, aiming for sensible defaults and better Developer Experience.

For example, Vite treats dependencies as "client-side packages" and automatically runs pre-optimization on them. Build tools like tsup, unbuild, and tsdown treat dependencies as packages to be externalized during bundling, automatically inlining (bundling) anything not listed in dependencies.

While these conventions certainly simplify things in most cases, they also force dependencies and devDependencies to wear multiple hats, making it harder to grasp the purpose of each package.

If we see vue listed in devDependencies, it could mean several things:

• We are inlining/bundling it.
• We are only referencing its types.
• We use it solely for testing.
• We have it to enable IDE IntelliSense.
• Or something else entirely.

Simply classifying packages as dependencies or devDependencies doesn't provide the full picture of that package's purpose without external documentation (also note that package.json doesn't support comments).

Categorize Your Dependencies

Let's forget about dependencies and devDependencies for a moment, how might we categorize our dependencies? Here are some rough ideas I could come up with:

• test: Packages used for testing (e.g., vitest, playwright, msw).
• lint: Packages for linting/formatting (e.g., eslint, knip).
• build: Packages used for building the project (e.g., vite, rolldown).
• script: Packages used for scripting tasks (e.g., tsx, tinyglobby, cpx).
• frontend: Packages for frontend development (e.g., vue, pinia).
• backend: Packages for the backend server.
• types: Packages for type checking and definitions.
• inlined: Packages that are included directly in the final bundle.
• prod: Runtime production dependencies.
• ...

Categorization might differ between projects. But that point is that dependencies and devDependencies lack the flexibility to capture this level of detail.

This thing had been bothering me for a while, though it didn't feel like a critical problem needing immediate resolution. Only until pnpm introduced catalogs, opening up possibilities for dependency categorization we never had before.

PNPM Catalogs

PNPM Catalogs is a feature allowing monorepo workspaces to share dependency versions across different packages via a centralized management location.

Basically, you add catalog or catalogs fields to your pnpm-workspace.yaml file and reference them using catalog:<name> in your package.json.

# pnpm-workspace.yaml
catalog:
  vue: ^3.5.15
  pinia: ^2.2.6
  cac: ^6.7.14

// package.json
{
  "dependencies": {
    "vue": "catalog:",
    "pinia": "catalog:",
    "cac": "catalog:"
  }
}

Or with named catalogs:

# pnpm-workspace.yaml
catalogs:
  frontend:
    vue: ^3.5.15
    # We locked the version for some reason, etc.
    pinia: 2.2.6
  prod:
    cac: ^6.7.14

// package.json
{
  "dependencies": {
    "vue": "catalog:frontend",
    "pinia": "catalog:frontend",
    "cac": "catalog:prod"
  }
}

During installation and publishing, pnpm automatically resolves dependencies to the versions specified in the catalogs. While it's originally designed for managing version consistency across monorepos, I found Named Catalogs are also a great way to also categorize dependencies. As shown above, we can categorize vue and cac into different catalogs even though they both presented in dependencies. This information makes version upgrade easier and would help on reviewing dependency changes.

A nice bonus: you can use comments in pnpm-workspace.yaml to share additional context with your team.

Tooling Support

Given that catalogs are still quite new, this shift requires better tooling support. A significant pain point for me on this was losing the ability to see a dependency's version at a glance in package.json when using catalog:<name>.

To address this, I created a VS Code extension, PNPM Catalog Lens, which displays the resolved version inline within package.json.

It also adds distinct colors to each named category for easier identification. This gives us the categorization and centralized version control without significantly impacting DX.

Since versions move to pnpm-workspace.yaml, CLI tools would need to make some integrations to support this. So far, we've adapted the following tools:

• taze: Checks and bumps dependency versions, now supporting reading and updating versions from catalogs.
• eslint-plugin-pnpm: Enforces using catalogs for all dependencies in package.json, with auto-fixes.
  • If you use @antfu/eslint-config, enable this by setting pnpm: true.
• pnpm-workspace-yaml: A utility library for reading and writing pnpm-workspace.yaml while preserving comments and formatting.
• node-modules-inspector: Visualizes your node_modules, now labeling dependencies with their catalog name for a better overview of their origin.
• nip: Interactive CLI to install packages to catalogs

Looking into the Future

Currently, I see the value of categorize dependencies is mainly for better communication and easier version upgrade reviews. However, as this convention gains wider adoption and tooling support improves, we could integrate this information more deeply with our tools.

For example, in Vite, we could gain more explicit control over dependency optimization, decoupling it from the dependencies and devDependencies fields:

// vite.config.ts
import { readWorkspaceYaml } from 'pnpm-workspace-yaml'
import { defineConfig } from 'vite'

const yaml = await readWorkspaceYaml('pnpm-workspace.yaml') // pseudo-API

export default defineConfig({
  optimizeDeps: {
    include: Object.keys(yaml.catalogs.frontend)
  }
})

Similarly, for unbuild, we could explicitly control externalization and inlining without manually maintaining lists in multiple places:

// build.config.ts
import { readWorkspaceYaml } from 'pnpm-workspace-yaml'
import { defineBuildConfig } from 'unbuild'

const yaml = await readWorkspaceYaml('pnpm-workspace.yaml')

export default defineBuildConfig({
  externals: Object.keys(yaml.catalogs.prod),
  rollup: {
    inlineDependencies: Object.keys(yaml.catalogs.inlined)
  }
})

For linting or bundling, we could enforce rules based on catalogs, such as throwing errors when attempting to import backend packages into frontend code, preventing accidental bundling mistakes.

This categorization could also provide valuable context for vulnerability reports. Vulnerabilities in build tools might be less severe than those in dependencies shipped to production.

...and so on.

I've already started migrating many of my projects to use named catalogs(node-modules-inspector for example). Even outside monorepos, the ability to categorize dependencies is a compelling reason to adopt to pnpm catalogs. I consider this an exploratory phase where we're still discovering best practices and improving tooling support.

So, that's why I'm writing this post: to invite you to consider this approach and try it out. We'd love to hear your thoughts and how you would utilize it. I look forward to seeing more patterns like this emerge, helping us build more maintainable projects with a better DX. Thanks for reading!

Seven years ago, my first visit to Japan - a trip to 大阪(Osaka), 京都(Kyoto), and 北海道(Hokkaido) - planted the seed of wanting to live in Japan one day. It was an unforgettable experience that changed the way I see the world. The meticulous attention to detail, the dedication to craftsmanship, and the seamless blend of tradition and modernity continue to inspire me.

Here are some photos I took back in 2018 on that trip:

During certain periods of my life, photography was my greatest passion, just as much as I do today with Open Source and programming. Instagram was once a delightful, minimalist platform for photo sharing that I frequently used - until Meta's acquisition changed everything. While I could even tolerate the algorithms, ads, and short videos, the recent change of profile photo grids' aspect ratio from square to 4:5 was the final straw - an arrogant decision that impacts every user's content without providing proper solutions.

I am not sure if anger or disappointment are the right words to describe my feelings. But I'm certainly lucky to be a frontend developer - so I can leverage my skills to build my own website and host my photos here.

I requested to download all my data from Instagram (it took roughly a day to process in my case), and imported them to the website. Thankfully, the downloaded data was relatively easy to process, with photos dating back to 2015. I use sharp to process the images and compress them with this script. This automation helps me manage the photos without worrying about image sizes for hosting.

Looking through these old photos brings back so many memories. While some may not meet my current standards - and I admittedly feel a bit embarrassed sharing them - they hold too many precious memories to leave behind. So I decided to keep most of them - hope you won't look too closely at them :P

Here are some of my recent photos:

It's a shame that the image quality from Instagram isn't great, since they compress photos heavily upon posting. I might replace some of them with higher quality originals in the future, but for now, I think it's a good start.

That said, I hope to get back into regularly sharing photos (as I keep saying 😅), especially now that I have my own platform for it.

Thanks for reading! And I hope you find my photos interesting. Cheese 🧀!

In modern programming, the function coloring problem isn't new. Based on how functions execute: synchronous (blocking) and asynchronous (non-blocking), we often classify them into two "colors" for better distinction. The problem arises because you generally cannot mix and match these colors freely.

For instance, in JavaScript:

• An async function can call both sync and other async functions.
• A sync function, however, cannot directly call an async function without changing its own color to async.

This restriction forces developers to propagate the "color" throughout their codebase. If a function deep in your logic needs to become async, it forces every caller up the chain to also become async, leading to a cascading effect (or "async inflection"). This makes refactoring harder, increases complexity, and sometimes leads to awkward workarounds like blocking async calls with await inside sync contexts, or vice versa.

We often discuss the async inflection problem, where a common solution is to make everything async since async functions can call both sync and async functions, while the reverse is not true. However, the coloring problem actually goes both ways, which seems to be less frequently discussed:

While an async function requires all the callers to be async, a sync function also requires all the dependencies to be sync.

At its core, it's the same problem with different perspectives. It depends on which part of the code you're focusing on and how difficult it is to change its "color." If the function you're working on must be async, the burden shifts to the callers. Conversely, if it must be sync, you'll need all your dependencies to be sync or provide a synchronous entry point.

Libraries in Practice

For example, the widely used library find-up provides two main APIs, findUp and findUpSync, to avoid dependents being trapped by the coloring problem. If you look into the code, you'll find that the package essentially duplicates the logic twice to provide the two APIs. Going down, you see its dependency locate-path also duplicates the locatePath and locatePathSync logic.

Say you want to build another library that uses findUp, like readNearestPkg, you would also have to write the logic twice, using findUp and findUpSync separately, to support both async and sync usage.

In these cases, even if our main logic does not come with its own "colors," the whole dependency pipeline is forced to branch into two colors due to an optional async operation down the road (e.g., fs.promises.stat and fs.statSync).

Async Plugins

Another case demonstrating the coloring problem is a plugin system with async hooks. For example, imagine we are building a Markdown-to-HTML compiler with plugin support. Say the parser and compiler logic are synchronous; we could expose a sync API like:

export function markdownToHtml(markdown) {
  const ast = parse(markdown)
  // ...
  return render(ast)
}

To make our library extensible, we might allow plugins to register hooks at multiple stages thoughout the process, for example:

export interface Plugin {
  preprocess: (markdown: string) => string
  transform: (ast: AST) => AST
  postprocess: (html: string) => string
}

export function markdownToHtml(markdown, plugins) {
  for (const plugin of plugins) {
    markdown = plugin.preprocess(markdown) // [!code hl]
  }
  let ast = parse(markdown)
  for (const plugin of plugins) {
    ast = plugin.transform(ast) // [!code hl]
  }
  let html = render(ast)
  for (const plugin of plugins) {
    html = plugin.postprocess(html) // [!code hl]
  }
  return html
}

Great, now we have a plugin system. However, having markdownToHtml as a synchronous function essentially limits all plugin hooks to be synchronous as well. This limitation can be quite restrictive. For instance, consider a plugin for syntax highlighting. In many cases, the best results for syntax highlighting might require asynchronous operations, such as fetching additional resources or performing complex computations that are better suited for non-blocking execution.

To accommodate such scenarios, we need to allow async hooks in our plugin system. This means that our main function, markdownToHtml, as the caller of the plugin hooks must also be async. We could implement it like this:

// [!code word:Promise]
// [!code word:async]
// [!code word:await]
export interface Plugin {
  preprocess: (markdown: string) => string | Promise<string>
  transform: (ast: AST) => AST | Promise<AST>
  postprocess: (html: string) => string | Promise<string>
}

export async function markdownToHtml(markdown, plugins) { // [!code hl]
  for (const plugin of plugins) {
    markdown = await plugin.preprocess(markdown) // [!code hl]
  }
  let ast = parse(markdown)
  for (const plugin of plugins) {
    ast = await plugin.transform(ast) // [!code hl]
  }
  let html = render(ast)
  for (const plugin of plugins) {
    html = await plugin.postprocess(html) // [!code hl]
  }
  return html
}

While this maximized the flexibility of the plugin system, this approach also forces all users to handle the process asynchronously, even in the cases where all plugins are synchronous. This is the cost of accommodating the possibility that some operations "might be asynchronous". To manage this, we often end up duplicating the logic to offer both sync and async APIs, and restrict async plugins to the async version only.

Such duplications lead to increased maintenance efforts, potential inconsistencies, and larger bundle sizes, which are not ideal for maintainers or users.

Is there a better way to handle this?

Introducing Quansync

What if we could make our logic decoupled from the coloring problem and let the caller decide the color?

Trying to make the situation a bit better, {@sxzz} and I took inspiration from gensync by {@loganfsmyth} and made a package called quansync. Taking it even further, we are dreaming of leveraging this to create a paradigm shift in the way we write libraries in the JavaScript ecosystem.

The name Quansync is borrowed from Quantum Mechanics, where particles can exist in multiple states simultaneously, known as superposition, and only settle into a single state when observed (try hovering over the atom below).

import fs from 'find-up'
import { quansync } from 'quansync'

export const readFile = quansync({
  sync: filepath => fs.readFileSync(filepath),
  async: filepath => fs.promises.readFile(filepath),
})

const content1 = readFile.sync('package.json')
const content2 = await readFile.async('package.json')

// The quansync function itself can behave like a normal async function
const content3 = await readFile('package.json')

import { quansync } from 'quansync'

export const readFile = quansync({
  sync: filepath => fs.readFileSync(filepath),
  async: filepath => fs.promises.readFile(filepath),
})

// Create a quansync with `function*` and `yield*`
// [!code word:function*:1]
export const readJSON = quansync(function* (filepath) {
  // Call the quansync function directly
  // and use `yield*` to get the result.
  // Upon usage, it will auto select the implementation
  // [!code word:yield*:1]
  const content = yield* readFile(filepath)
  return JSON.parse(content)
})

// fs.readFileSync will be used under the hood
const pkg1 = readJSON.sync('package.json')
// fs.promises.readFile will be used under the hood
const pkg2 = await readJSON.async('package.json')

// [!code word:quansync/macro]
import { quansync } from 'quansync/macro'

// Use async/await syntax
// They will be transformed to `function*` and `yield*` at build time
export const readJSON = quansync(async (filepath) => {
  const content = await readFile(filepath)
  return JSON.parse(content)
})

// Expose the classical sync API
export const readJSONSync = readJSON.sync

Three years ago, I wrote a post about shipping ESM & CJS in a single package, advocating for dual CJS/ESM formats to ease user migration and trying to make the best of both worlds. Back then, I didn't fully agree with aggressively shipping ESM-only, as I considered the ecosystem wasn't ready, especially since the push was mostly from low-level libraries. Over time, as tools and the ecosystem have evolved, my perspective has gradually shifted towards more and more on adopting ESM-only.

As of 2025, a decade has passed since ESM was first introduced in 2015. Modern tools and libraries have increasingly adopted ESM as the primary module format. According to {@wooorm}'s script, the packages that ships ESM on npm in 2021 was 7.8%, and by the end of 2024, it had reached 25.8%. Although a significant portion of packages still use CJS, the trend clearly shows a good shift towards ESM.

Here in this post, I'd like to share my thoughts on the current state of the ecosystem and why I believe it's time to move on to ESM-only.

The Toolings are Ready

Modern Tools

With the rise of Vite as a popular modern frontend build tool, many meta-frameworks like Nuxt, SvelteKit, Astro, SolidStart, Remix, Storybook, Redwood, and many others are all built on top of Vite nowadays, that treating ESM as a first-class citizen.

As a complement, we have also testing library Vitest, which was designed for ESM from the day one with powerful module mocking capability and efficient fine-grain caching support.

CLI tools like tsx and jiti offer a seamless experience for running TypeScript and ESM code without requiring additional configuration. This simplifies the development process and reduces the overhead associated with setting up a project to use ESM.

Other tools, for example, ESLint, in the recent v9.0, introduced a new flat config system that enables native ESM support with eslint.config.mjs, even in CJS projects.

Top-Down & Bottom-Up

Back in 2021, when {@sindresorhus} first started migrating all his packages to ESM-only, for example, find-up and execa, it was a bold move. I consider this move as a bottom-up approach, as the packages that rather low-level and many their dependents are not ready for ESM yet. I was worried that this would force those dependents to stay on the old version of the packages, which might result in the ecosystem being fragmented. (As of today, I actually appreciate that move bringing us quite a lot of high-quality ESM packages, regardless that the process wasn't super smooth).

It's way easier for an ESM or Dual formats package to depend on CJS packages, but not the other way around. In terms of smooth adoption, I believe the top-down approach is more effective in pushing the ecosystem forward. With the support of high-level frameworks and tools from top-down, it's no longer a significant obstacle to use ESM-only packages. The remaining challenges in terms of ESM adoption primarily lie with package authors needing to migrate and ship their code in ESM format.

Requiring ESM in Node.js

The capability to require() ESM modules in Node.js, initiated by {@joyeecheung}, marks an incredible milestone. This feature allows packages to be published as ESM-only while still being consumable by CJS codebases with minimal modifications. It helps avoid the async infection (also known as Red Functions) introduced by dynamic import() ESM, which can be pretty hard, if not impossible in some cases, to migrate and adapt.

This feature was recently unflagged and backported to Node.js v22 (and soon v20), which means it should be available to many developers already. Consider the top-down or bottom-up metaphor, this feature actually makes it possible to start ESM migration also from middle-out, as it allows import chains like ESM → CJS → ESM → CJS to work seamlessly.

To solve the interop issue between CJS and ESM in this case, Node.js also introduced a new export { Foo as 'module.exports' } syntax in ESM to export CJS-compatible exports (by this PR). This allows package authors to publish ESM-only packages while still supporting CJS consumers, without even introducing breaking changes (expcet for changing the required Node.js version).

For more details on the progress and discussions around this feature, keep track on this issue.

The Troubles with Dual Formats

While dual CJS/ESM packages have been a quite helpful transition mechanism, they come with their own set of challenges. Maintaining two separate formats can be cumbersome and error-prone, especially when dealing with complex codebases. Here are some of the issues that arise when maintaining dual formats:

Interop Issues

Fundamentally, CJS and ESM are different module systems with distinct design philosophies. Although Node.js has made it possible to import CJS modules in ESM, dynamically import ESM in CJS, and even require() ESM modules, there are still many tricky cases that can lead to interop issues.

One key difference is that CJS typically uses a single module.exports object, while ESM supports both default and named exports. When authoring code in ESM and transpiling to CJS, handling exports can be particularly challenging, especially when the exported value is a non-object, such as a function or a class. Additionally, to make the types correct, we also need to introduce further complications with .d.mts and .d.cts declaration files. And so on...

As I am trying to explain this problem deeper, I found that I actually wish you didn't even need to be bothered with this problem at all. It's frankly too complicated and frustrating. If you are just a user of packages, let alone the package authors to worry about that. This is one of the reasons I advocate for the entire ecosystem to transition to ESM, to leave these problems behind and spare everyone from this unnecessary hassle.

Dependency Resolution

When a package has both CJS and ESM formats, the resolution of dependencies can become convoluted. For example, if a package depends on another package that only ships ESM, the consumer must ensure that the ESM version is used. This can lead to version conflicts and dependency resolution issues, especially when dealing with transitive dependencies.

Also for packages that are designed to used with singleton pattern, this might introduce multiple copies of the same package and cause unexpected behaviors.

Package Size

Shipping dual formats essentially doubles the package size, as both CJS and ESM bundles need to be included. While a few extra kilobytes might not seem significant for a single package, the overhead can quickly add up in projects with hundreds of dependencies, leading to the infamous node_modules bloat. Therefore, package authors should keep an eye on their package size. Moving to ESM-only is a way to optimize it, especially if the package doesn't have strong requirements on CJS.

When Should We Move to ESM-only?

This post does not intend to diminish the value of dual-format publishing. Instead, I want to encourage evaluating the current state of the ecosystem and the potential benefits of transitioning to ESM-only.

There are several factors to consider when deciding whether to move to ESM-only:

New Packages

I strongly recommend that all new packages be released as ESM-only, as there are no legacy dependencies to consider. New adopters are likely already using a modern, ESM-ready stack, there being ESM-only should not affect the adoption. Additionally, maintaining a single module system simplifies development, reduces maintenance overhead, and ensures that your package benefits from future ecosystem advancements.

Browser-targeted Packages

If a package is primarily targeted for the browser, it makes total sense to ship ESM-only. In most cases, browser packages go through a bundler, where ESM provides significant advantages in static analysis and tree-shaking. This leads to smaller and more optimized bundles, which would also improve loading performance and reduce bandwidth consumption for end users.

Standalone CLI

For a standalone CLI tool, it's no difference to end users whether it's ESM or CJS. However, using ESM would enable your dependencies to also be ESM, facilitating the ecosystem's transition to ESM from a top-down approach.

Node.js Support

If a package is targeting the evergreen Node.js versions, it's a good time to consider ESM-only, especially with the recent require(ESM) support.

Know Your Consumers

If a package already has certain users, it's essential to understand the dependents' status and requirements. For example, for an ESLint plugin/utils that requires ESLint v9, while ESLint v9's new config system supports ESM natively even in CJS projects, there is no blocker for it to be ESM-only.

Definitely, there are different factors to consider for different projects. But in general, I believe the ecosystem is ready for more packages to move to ESM-only, and it's a good time to evaluate the benefits and potential challenges of transitioning.

How Far We Are?

The transition to ESM is a gradual process that requires collaboration and effort from the entire ecosystem. Which I believe we are on a good track moving forward.

To improve the transparency and visibility of the ESM adoption, I recently built a visualized tool called Node Modules Inspector for analyzing your packages's dependencies. It provides insights into the ESM adoption status of your dependencies and helps identify potential issues when migrating to ESM.

Here are some screenshots of the tool to give you a quick impression:

This tool is still in its early stages, but I hope it will be a valuable resource for package authors and maintainers to track the ESM adoption progress of their dependencies and make informed decisions about transitioning to ESM-only.

To learn more about how to use it and inspect your projects, check the repository .

Moving Forward

I am planning to gradually transition the packages I maintain to ESM-only and take a closer look at the dependencies we rely on. We also have plenty of exciting ideas for the Node Modules Inspector, aiming to provide more useful insights and help find the best path forward.

I look forward to a more portable, resilient, and optimized JavaScript/TypeScript ecosystem.

I hope this post has shed some light on the benefits of moving to ESM-only and the current state of the ecosystem. If you have any thoughts or questions, feel free to reach out using the links below. Thank you for reading!

People often assume that a zero-major version indicates that the software is not ready for production. However, all of the projects mentioned here are quite stable and production-ready, used by millions of projects.

Why? - I bet that's your question reading this.

Versioning

Version numbers act as snapshots of our codebase, helping us communicate changes effectively. For instance, we can say "it works in v1.3.2, but not in v1.3.3, there might be a regression." This makes it easier for maintainers to locate bugs by comparing the differences between these versions. A version is essentially a marker, a seal of the codebase at a specific point in time.

However, code is complex, and every change involves trade-offs. Describing how a change affects the code can be tricky even with natural language. A version number alone can't capture all the nuances of a release. That's why we have changelogs, release notes, and commit messages to provide more context.

I see versioning as a way to communicate changes to users — a contract between the library maintainers and the users to ensure compatibility and stability during upgrades. As a user, you can't always tell what's changed between v2.3.4 and v2.3.5 without checking the changelog. But by looking at the numbers, you can infer that it's a patch release meant to fix bugs, which should be safe to upgrade. This ability to understand changes just by looking at the version number is possible because both the library maintainer and the users agree on the versioning scheme.

Since versioning is only a contract, and could be interpreted differently to each specific project, you shouldn't blindly trust it. It serves as an indication to help you decide when to take a closer look at the changelog and be cautious about upgrading. But it's not a guarantee that everything will work as expected, as every change might introduce behavior changes, whether it's intended or not.

Semantic Versioning

In the JavaScript ecosystem, especially for packages published on npm, we follow a convention known as Semantic Versioning, or SemVer for short. A SemVer version number consists of three parts: MAJOR.MINOR.PATCH. The rules are straightforward:

• MAJOR: Increment when you make incompatible API changes.
• MINOR: Increment when you add functionality in a backwards-compatible manner.
• PATCH: Increment when you make backwards-compatible bug fixes.

Package managers we use, like npm, pnpm, and yarn, all operate under the assumption that every package on npm adheres to SemVer. When you or a package specifies a dependency with a version range, such as ^1.2.3, it indicates that you are comfortable with upgrading to any version that shares the same major version (1.x.x). In these scenarios, package managers will automatically determine the best version to install based on what is most suitable for your specific project.

This convention works well technically. If a package releases a new major version v2.0.0, your package manager won't install it if your specified range is ^1.2.3. This prevents unexpected breaking changes from affecting your project until you manually update the version range.

However, humans perceive numbers on a logarithmic scale. We tend to see v2.0 to v3.0 as a huge, groundbreaking change, while v125.0 to v126.0 seems a lot more trivial, even though both indicate incompatible API changes in SemVer. This perception can make maintainers hesitant to bump the major version for minor breaking changes, leading to the accumulation of many breaking changes in a single major release, making upgrades harder for users. Conversely, with something like v125.0, it becomes difficult to convey the significance of a major change, as the jump to v126.0 appears minor.

{@TkDodo|Dominik Dorfmeister} had a great talk about API Design, which mentions an interesting inequality that descripting this: "Breaking Changes !== Marketing Event"

Progressive

I am a strong believer in the principle of progressiveness. Rather than making a giant leap to a significantly higher stage all at once, progressiveness allows users to adopt changes gradually at their own pace. It provides opportunities to pause and assess, making it easier to understand the impact of each change.

I believe we should apply the same principle to versioning. Instead of treating a major version as a massive overhaul, we can break it down into smaller, more manageable updates. For example, rather than releasing v2.0.0 with 10 breaking changes from v1.x, we could distribute these changes across several smaller major releases. This way, we might release v2.0 with 2 breaking changes, followed by v3.0 with 1 breaking change, and so on. This approach makes it easier for users to adopt changes gradually and reduces the risk of overwhelming them with too many changes at once.

Leading Zero Major Versioning

The reason I've stuck with v0.x.x is my own unconventional approach to versioning. I prefer to introduce necessary and minor breaking changes early on, making upgrades easier, without causing alarm that typically comes with major version jumps like v2 to v3. Some changes might be "technically" breaking but don't impact 99.9% of users in practice. (Breaking changes are relative. Even a bug fix can be breaking for those relying on the previous behavior, but that's another topic for discussion :P).

There's a special rule in SemVer that states when the leading major version is 0, every minor version bump is considered breaking. I am kind of abusing that rule to workaround the limitation of SemVer. With zero-major versioning, we are effectively abandoning the first number, and merge MINOR and PATCH into a single number (thanks to David Blass for pointing this out):

Of course, zero-major versioning is not the only solution to be progressive. We can see that tools like Node.js, Vite, Vitest are rolling out major versions in consistent intervals, with a minimal set of breaking changes in each release that are easy to adopt. It would require a lot of effort and extra attentions. Kudos to them!

I have to admit that sticking to zero-major versioning isn't the best practice. While I aimed for more granular versioning to improve communication, using zero-major versioning has actually limited the ability to convey changes effectively. In reality, I've been wasting a valuable part of the versioning scheme due to my peculiar insistence.

Thus, here, I am proposing to change.

Epoch Semantic Versioning

In an ideal world, I would wish SemVer to have 4 numbers: EPOCH.MAJOR.MINOR.PATCH. The EPOCH version is for those big announcements, while MAJOR is for technical incompatible API changes that might not be significant. This way, we can have a more granular way to communicate changes. Similarly, we also have Romantic Versioning that propose HUMAN.MAJOR.MINOR. The creator of SemVer, Tom Preston-Werner also mentioned similar concerns and solutions in this blog post. (thanks to Sébastien Lorber for pointing this out).

But, of course, it's too late for the entire ecosystem to adopt a new versioning scheme.

If we can't change SemVer, maybe we can at least extend it. I am proposing a new versioning scheme called 🗿 Epoch Semantic Versioning, or Epoch SemVer for short. It's built on top of the structure of MAJOR.MINOR.PATCH, extend the first number to be the combination of EPOCH and MAJOR. To put a difference between them, we use a fourth digit to represent EPOCH, which gives MAJOR a range from 0 to 999. This way, it follows the exact same rules as SemVer without requiring any existing tools to change, but provides more granular information to users.

The name "Epoch" is inspired by Debian's versioning scheme.

The format is as follows:

• EPOCH: Increment when you make significant or groundbreaking changes.
• MAJOR: Increment when you make minor incompatible API changes.
• MINOR: Increment when you add functionality in a backwards-compatible manner.
• PATCH: Increment when you make backwards-compatible bug fixes.

I previously proposed to have the EPOCH multiplier to be 100, but according to the community feedback, it seems that 1000 is a more popular choices as it give more room for the MAJOR version and a bit more distinguision between the numbers. The multiplier is not a strict rule, feel free to adjust it based on your needs.

For example, UnoCSS would transition from v0.65.3 to v65.3.0 (in the case EPOCH is 0). Following SemVer, a patch release would become v65.3.1, and a feature release would be v65.4.0. If we introduced some minor incompatible changes affecting an edge case, we could bump it to v66.0.0 to alert users of potential impacts. In the event of a significant overhaul to the core, we could jump directly to v1000.0.0 to signal a new era and make a big announcement. I'd suggest assigning a code name to each non-zero EPOCH to make it more memorable and easier to refer to. This approach provides maintainers with more flexibility to communicate the scale of changes to users effectively.

[!TIP]
We shouldn't need to bump EPOCH often. It's mostly useful for high-level, end-user-facing libraries or frameworks. For low-level libraries, they might never need to bump EPOCH at all (ZERO-EPOCH is essentially the same as SemVer).

Of course, I'm not suggesting that everyone should adopt this approach. It's simply an idea to work around the existing system, and only for those packages with this need. It will be interesting to see how it performs in practice.

Moving Forward

I plan to adopt Epoch Semantic Versioning in my projects, including UnoCSS, Slidev, and all the plugins I maintain, and ultimately abandon zero-major versioning for stable packages. I hope this new versioning approach will help communicate changes more effectively and provide users with better context when upgrading.

I'd love to hear your thoughts and feedback on this idea. Feel free to share your comments using the links below!

Node.js provides a built-in --cpu-prof flag that allows you to generate CPU profiles. However you can't directly pass it in your nuxi command, you have to use it with node directly.

Instead of running nuxi dev, you can run node with the direct path to the CLI in node_modules:

# nuxi dev
node --cpu-prof ./node_modules/nuxi/bin/nuxi.mjs dev --fork=false

Note that --fork=false is important as by default nuxi will start the Nuxt process in a forked process which will make the CPU profile not working.

The simliar technique can be applied to other CLI tools that are not directly using node to start the process.

After killing your Nuxt process, you will find two CPU.***.cpuprofile files generated in your working directory. I recommend using CPUpro to visualize the profile. If you are using VS Code, I also created an extension for you to directly open the .cpuprofile file in VS Code easily.

It's not a secret that open-source projects are now a critical part of almost every software project. While most open-source projects are maintained by volunteers, the sustainability of these projects becomes a big concern. The recent xz/liblzma vulnerability accident is a great example that shows the importance of open-source projects and how severe the problem could be.

There are multiple ways to support open-source projects (another excellent article by Rob Mensching, highly recommended). Funding is indeed one of its essential aspects. I believe most open-source maintainers are not doing it for money. However, maintainers still need to pay their bills to make a living and spend time maintaining the projects. Unrewarded free work is not sustainable in the long run.

We are glad to see that more and more companies and individuals started to see the importance of open-source sustainability and have started to sponsor open-source projects. We also see that some companies have started to hire or support maintainers to work on open-sources projects full-time (for example, thanks {NuxtLabs} for having the Nuxt core team and me 💚. {Astro} {Stackblitz} {Netlify} {Vercel} and other companies are also doing it). We, as the maintainers, genuinely appreciate all that support.

However, today, it's still extremely hard for maintainers to figure out ways to get the minimal funds to work on open-source projects full-time, not even asking for returns that match the value they are providing. There are many aspects of open-source funding that need to be improved. In this post, I'd like to bring up some problems we have observed and propose solutions to improve the situation.

Unbalanced Funding

In open-source, there are different types of projects.

Some projects are more "front-facing" and are directly interacted with by developers and users on a daily basis. These projects often have short and loud names, well-designed logos, and a large community discussing them or even holding events around them.

On the other hand, there are also "underlying" dependencies that are used extensively but may not be as visible. The majority of the users may not even be aware that they are indirectly depending on them.

Whether a project is "front-facing" or "underlying", both types of projects are crucial to the ecosystem and deserve support. What they have in common is that they rely on people who invest their time and effort into maintaining these projects.

Among all the contributors and maintainers, there is a mix of individuals who have different working styles and levels of visibility. Some are more "high-profile" and actively share their work, while others prefer to stay low-profile and focus on their contributions behind the scenes. The different working styles should not diminish the value of their work.

Naturely, front-facing projects and high-profile maintainers are much more likely to receive attention and sponsorships, while the underlying dependencies and low-profile maintainers are often overlooked. To illustrate this, let me present you this famous xkcd comic again:

Imagine, with that critical dependency being removed, here we have a falling apart version by Adam Leventhal:

When you find a tool that has been helpful to you and you want to show your support, it's natural to look for a way to sponsor the tool or its maintainers. We greatly appreciate this kind of support. The problem of the unsupported dependencies is not usually the sponsor's responsibility.

However, it's important to recognize that when we develop a "front-facing" tool or framework, we often rely on other tools and dependencies to make our work possible. It wouldn't be fair for the "front-facing" projects to take all the credit. In reality, even those "front-facing" projects are often underfunded. That's why we are grateful to see many open-source projects forwarding sponsorships to supporting their dependencies.

For example, {ESLint} is forwarding sponsorships to its contributors and dependencies, {Astro} is giving funds to the ecosystem, projects that I am participating like {Vite|https://opencollective.com/vite/expenses} and {Elk|https://opencollective.com/elk/expenses?collectiveSlug=elk&type=INVOICE} are also started following similar approaches on their Open Collective. Many other projects are doing it as well.

{@nzakas|Nicholas C. Zakas}, the creator of ESLint, also wrote a great article Sponsoring dependencies: The next step in open source sustainability, explaining the importance of this.

About Me

I am honestly super lucky to have the opportunity to work on numerous front-facing projects and be a relatively high-profile maintainer in the community and on social media. I am extremely grateful for all the sponsorships I have received. As I mentioned in another post, I have received tremendous help from the community and contributors in creating the tools that you are using. I firmly believe that I shouldn't take all the credit and appreciation from sponsors alone. That's why I wrote this blog post - to find a way to give back to the ecosystem with the resources and influence I have.

Sponsorships Forwarding on GitHub

I am already sponsoring a number of maintainers who I benefit a lot from. {GitHub Sponsors|https://github.com/sponsors} is a great platform. It covers the transaction fees, and provides great connections with sponsors, maintainers, and projects, making the discovery and sponsorship process smooth. However, while it is great for individual sponsors, it lacks the ability to forward sponsorships to other projects or maintainers. {@patak-dev} raised this feature request for GitHub two years ago, which is currently the top-upvoted request from the community, but unfortunately, it has not been resolved yet.

Here, let's do some simple math to see why this feature is essential:

• With GitHub Sponsors, the maintainer receives a monthly payout to their bank account.
• This payout counts as personal income, and the maintainer needs to pay taxes based on the country they live in.
• If the maintainer wants to sponsor another maintainer, they need to pay from their own pocket.
• When the second maintainer receives the funds after another month, they must also pay taxes again.

For example, the tax I have to pay here in France is roughly 41%. Assume both maintainers have the same tax rate. This means that when forwarding sponsorship on GitHub Sponsors, the second maintainer will only receive

of the original amount, plus two months of delay in between (on top of the case that GitHub already covers the transaction fees). Sometimes, we even have circular sponsorships because we both want to show appreciation to the others. Ultimately, this is a significant loss, especially when there is not enough funding for open source already (it's also worth mentioning that GitHub Sponsors is not yet available in all countries).

Despite GitHub Sponsors limitations, a lot of maintainers are still forwarding part of their funds to others ({@danielroe|Danielroe's Sponsoring|https://github.com/danielroe?tab=sponsoring}, {@patak-dev|Matias' Sponsoring|https://github.com/patak-dev?tab=sponsoring}, {@kazupon|Kazupon's Sponsoring|https://github.com/kazupon?tab=sponsoring} and many more). While we really wanted to support more dependencies and maintainers, the current situation on GitHub is not very feasible in the long run.

Open Collective

Another popular platform for open-source projects to receive sponsorships is Open Collective. It provides great transparency on how funds are collected and spent.

For open-source projects, Open Source Collective is a commonly used fiscal host on Open Collective. It charges a total of 10% transaction and hosting fees upfront. The important part is that it allows funds to be forwarded to other projects on the same fiscal host with no additional fees. This makes it a much better fit for the sponsorship forwarding use case.

Anthony Fu's Collective

So, I came up with the idea of creating my personal collective: {Anthony Fu Collective}

Where you can sponsor my work across the ecosystem, including but not limited to:

{Vite} {Vue} {Nuxt} {Vitest} {VueUse} {UnoCSS} {Slidev} {Elk} {Shiki} {TwoSlash} {ESLint Stylistic}

The main difference is that I won't take the funds for myself;
(except for occasional expense reimbursements like hosting or domain renewal)

All the funds will be redistributed to the dependencies and contributors. Each month, I will select a few dependencies and contributors to forward the funds. Depending on the amount raised, I may also set up recurring sponsorships for high-impact dependencies in the future. You give the trust and support to me, and I will make sure the funds are well spent.

To allow differentiating easily, I will treat the funds on GitHub Sponsors and Open Collective differently:

• {Sponsor Anthony Fu on Open Collective|https://opencollective.com/antfu} - To sponsor the dependencies and ecosystem of the projects Anthony maintains.
• {Sponsor Anthony Fu on GitHub Sponsors|https://github.com/sponsors/antfu} - To sponsor Anthony's personal work on open-source projects.

I would generally recommend sponsoring on Open Collective first to support the entire ecosystem and open source. Well, I'd also be grateful if you could sponsor on both platforms :P

Recurring sponsorships are highly appreciated. They help provide a more consistent monthly income and contribute to long-term sustainability for the projects and maintainers.

This collective is my approach trying to see how I can help the ecosystem with the resources and knowledge I have. It also serves as an initiative to encourage more maintainers and projects to follow, by forwarding the support they receive to the dependencies and contributors they benefit from.

Transparency

Since this involves money and trust, I think transparency is crucial here. I will try to answer honestly some questions you might have below. Feel free to raise more questions if you have any other concerns, I will try to update this post with my responses accordingly.

Why am I Doing this?

As I explained throughout this post, my intention is to contribute to the open-source ecosystem and make it better with my little efforts.

To be completely honest and transparent, yes, I couldn't say I am not doing this 100% selflessly. Despite the fact that I am not taking funds for myself, I might still indirectly benefit from this initiative.

I do undeniably have vanity and ego due to my human nature, and I am not ashamed to admit it. I do care about my reputation and influence to some extent. I see this endeavor as similar to contributing to open source. Does everyone do open source completely selflessly? I doubt that. But does that mean everyone is doing it solely for their own benefit? I don't believe that either. The beauty of open source lies in its non-zero-sum nature, where maintainers can derive benefits such as a sense of accomplishment, skill improvement, recognition, and reputation, while providing value to benefit the entire world.

Being part of the open-source community who also relies on it, I certainly have the incentive to help the community become better and more sustainable. I am not a materialistic person, and the sponsorships I have received are not huge, but they are enough for me to make a basic living. While I do believe there are other projects and maintainers who would benefit more from the funds at this time.

Ultimately, my goal is to increase the overall funding into the open-source ecosystem and develop robust systems to support projects, so that everyone can reap the benefits of open source and acknowledge the hard work put in by its contributors.

How to Ensure the Distribution is Fair?

Regrettably, I don't think it's possible to design a "perfect algorithm" to "score" and distribute the funds fairly. Representing a project, a person, or their work with a single number to rank is unrealistic.

When it comes to equality and equity, I believe it's important to prioritize supporting underrepresented and underfunded projects and maintainers. This would involve subjective judgment, and while I can't guarantee complete fairness, I will strive to be transparent and sincere. I will actively engage with the community and openly communicate how and why the funds are distributed.

Why "Personal" Collective

As mentioned above, there is no absolute way to distribute the funds fairly. In this case, it's based on my judgment and the trust you give me. As the starting point of this initiative, I believe it's easier and simpler to start with a personal collective and adjust based on the feedback and results. Meanwhile, a personal collective not bound to a specific project could be more flexible and better support the goals of this initiative.

This is certainly not going to be the only collective that forwards sponsorships. Maybe in the future, sponsoring multiple individuals collectively and group collectives would help make the distribution less opinionated and less biased.

For a related example, inspired by this tweet, we recently started an organization with several maintainers to improve the performance and quality across JavaScript packages. Later, we might set up a collective for this organization so you can sponsor the efforts on performance improvements. Stay tuned for a future announcement.

Other Alternative Platforms?

There are quite a few other platforms for open-source funding that also bring exciting solutions to this problem.

This collective is only one more idea, an attempt to help our ecosystem become more sustainable - feel free to explore other platforms and initiatives you think are making sense. The main difference between this collective and the others is that it has me working behind it, instead of just metrics and algorithms. The human factor also made it possible to reduce sponsorships waterflow, where on some platforms the sub-dependencies are harder to get enough funds. With this collective, I can reach the critical dependencies and contributors directly to support them. I will spend time doing the research and communications every month to find important dependencies to support.

Sponsor Now

This initiative is something I couldn't do alone. I would need your support to make it happen.

If I have convinced you this initiative is meaningful, use the buttons below to help me support the open-source ecosystem and make it more sustainable. Thank you!

Slides: PDF | SPA

Made with Slidev - presentation slides for developers.

中文翻译 Chinese Version

TL;DR: I am doing great and not going anywhere. Having some pressure but still holding up and trying to improve. Thank you and don't worry!

This is the 4th year since I have started doing Open Source. To be completely honest, I began to feel things were getting out of my capacity more and more often. I am still not sure if I have ever been through actual burnout or not, but I surely have experienced the ups and downs of my productivity and motivation periodically.

This post is not a guide, or not even complaining. It's more like my personal diary, which I serve as a record for myself. I just think it might be interesting if I could share those with you.

If you are been through a burnout or feeling close to it, I'd recommend you to take some breaks, talk to someone, and seek professional help if needed. Here is also a nice article Maintaining Balance for Open Source Maintainers that you could reference. Take great care!

And so here, let me tell you some random stuff I have been thinking about recently

Unprepared

In a way, Open Source is still very new to me, even today.

Since I started to learn programming and knowing about open source, I have been dreaming about being a full-time open source developer. When I was in college, I was eager to get recognized by the open source community, trying hard to "figure out" some impactful work that I could accomplish. All of a sudden, you will reach a pivotal point, where your project might unexpectedly take off, or you have been invited to join a big project - in a moment, you will start to feel all those excitements as well as the responsibilities suddenly come along. In a few days, when the initial excitement starts to fade away, you start to realize that it also means so much responsibility and other things that you have never thought about. Despite that I have been trying all my college years to get into open source, when I finally stepped into it, I realized how much I was unprepared.

One interesting thing about Open Source is that one is probably never prepared. You might encounter tricky technical problems, or have to keep up with the new technologies, but there are also a bunch of things other than coding that you have to deal with. You have to be your customer support to answer questions; be a designer, a writer to prepare nice documentation; a project manager to keep the project on track; a team leader to onboard new contributors and keep the team motivated; marketing your stuff; speaking at conferences; and so on. Those are the "side-effects" of being an open source developer, many things come to you in a bundle, not only the code.

For me, it's so much a challenge. I am quite introverted, I am not good at chatting or making conversations. I was terrible on my English exams back in school, and wasn't confident at all to speak in English. I got stage fright even just in front of my classmates. And I suppose I don't enjoy team management either, even though I never led a team - so many things to be afraid of.

It doesn't give you the time to prepare for ready (or on the other hand, one might never be ready without taking the first step), as the project grows, as your responsibilities grow, you will be forced to learn and adapt. When it naturally grows a team, you have to learn to communicate, to lead. When someone invites you to do a podcast or give a talk, they won't wait 3 years for you to practice the language or speaking skills -- you either miss the chance or you fight your fear and do it. Because I love doing Open Source so much, I have to conquer them and myself.

Might be overwhelming it seems. But if you take those challenges and get through them one by one, gradually, you might find that they are quite fun and rewarding. In the end, I appreciate a lot about all those chances for pushing me out of my comfort zone and forcing myself to improve. Throughout these 4 years in Open Source, despite still being not perfect at many things, I managed to speak English much more confidently. I have given talks at many conferences, some of which even have thousands of attendees. I still get super nervous before every talk, but at least I am no longer afraid of doing it.

There are still so many challenges and surprises coming up. I am half fearful and half excited to see what's next.

"Expectations"

Human adapts. That drives us to survive as well as keep improving, but that also makes us hard to stay satisfied.

I was so excited when I started my first few open source projects. I would keep refreshing the page, eagerly waiting for new issues, new pull requests, and new comments to show up. Every single star would make me happy, and I'll try to help with every single issue as much as possible. I set milestones like 100 stars, 500 stars and celebrate when I reach them. I still remember how proud I was when I told my friends that I had a few hundred stars on my projects and I was making some impact on the world.

Once you reach those goals, things start to become "usual". You will then start to expect more and set higher goals. At a certain point, I start to not care about those numbers of stars or downloads anymore. It's not necessarily a bad thing as they are not the metrics I should be focusing on anyway, but I sometimes miss the old days when I could get joy from those simple things.

I gradually realized, that the experience of so many things in our life has a direct relationship with our expectations. When we just get started, we have little expectations, which could be relatively easy to reach. As we go forward and stand on a higher ground, we start to expect much more, that might not scale linearly. Getting 100 more stars when you have 1000 does not sound as impressive as when you have nothing. When you have 1000 stars, you will look for another 1000, and only 100 can no longer satisfy you. That is odd to me, and I don't enjoy this "human nature" of mine.

I found that lowering my expectations and being grateful for what I have is a good way to keep me happy. When you start to realize you can't keep reaching your milestones one and another, it's a good way out to stop seeking higher, take a break and enjoy the view around you - maybe you have already reached high enough. Since I started to "not overly concerned about gains and losses", I found myself much happier trying different ideas even if they might not be successful - because I don't have high expectations of them, there is no such concept of "failure" to me. And if some of them later might turn out to be good ideas, it would be a nice "unexpected surprise".

If you are interested, I explained about my ideas-finding process in the About Yak Shaving post.

"Self-Expectations"

Expectations apply not only to what we are doing, but also come to myself. When I care about a project too much, I often find I am expecting myself too much in the role of being a kind and friendly maintainer. I will feel bad when I read people criticizing my projects, when a certain bug causes people trouble, or when I don't reply to issues in time, etc. The feelings become even stronger on popular projects, as you know there are a lot of people who depend on it. Those self-expectations put me under quite a lot of pressure and stress.

As I mentioned in another post, the ratio of maintainers to users is often unbalanced in open source projects. It's really hard to meet a new collaborator or team member, but there is basically no threshold to grow more users due to Open Source being naturally free.

I think it's hard for maintainers to make the mind shift and consider that they are not obligated to solve the issues for others -- because open-source software is usually served as-is. Especially for maintainers who care about their users and community, it's hard to ignore when we receive new issues. But in another perspective, one person's time and energy are limited. When the amount of work grows out of one's capacity, it's better to set priorities and focus on the most important things first.

I wish someone could tell me this when I started maintaining high-traffic open source projects (you have great resources online like this) - it took me a long time to realize that I don't have to be perfect, and it's okay to do things at my own pace. Instead of receiving notifications passively, it's better for me to turn off the push notifications, and to proactively check the issues and pull requests when I feel ready to do so.

I made a talk about How I Manage GitHub Notifications, if you are interested in more about the methodology.

Lowering the expectations of yourself - no one is perfect, and no one is a machine. Don't let them become a burden to you. It's more important to maintain a healthy and sustainable pace, and to keep yourself happy and motivated to have more positive impacts in the long run.

When Your Dream Becomes Your Job

It's awesome to live in your own dream, and honestly, a privilege. But also, to be realisistic, having a dream is quite different from living in it. Dreams are always idealized, excluding all the boring details. My dream is to be a full-time open source developer. Yes, it sounds great to be independent, to work on what you like, to have a flexible or no schedule at all, to work from anywhere, and to benefit the world, etc. But in reality, things are not that simple.

It's quite similar to "Make your hobby your job". It indeed has a great amount of benefits, like you will be more enjoyable and productive, but it also comes with obligations and responsibilities. When a hobby becomes a job, you lose the freedom to choose when and what to. Before, you would do your hobbies as after-work relaxation, but now when you want to relax with your hobbies, they become work.

I was lucky that software development is a big field with many different things to do. Outside of the "main" open source project maintenance, I sometimes do some small projects (Generative Art, Stable Diffusion, some little experiments, etc.) for fun to refresh my mind (as a kind of "relax" from main projects). I also enjoy playing indie games a lot, while I keep thinking of getting serious about developing some games - but that's another story - at least now I still have some ways to escape when I really want to stay away from code.

I probably enjoy programming too much that I don't have strong feelings about this. The line between "work" and "fun" is quite blurry on my side. Sometimes, a fun project can become something serious that people rely on.

Velocity, Scope, and Quality

This is actually the topic that drove me to write this blog post.

Let's start with this "Iron Triangle" of Velocity, Scope and Quality.
(typicall they are Quality/Speed/Cost where I made a few adjustments here)

Usually, people would say -- in these three factors, you can only pick two. If you want to deliver a project faster, you might have to sacrifice the quality or have a smaller scope of features. If you want to have a high-quality and feature-rich product, you might have to sacrifice speed to deliver good stuff slowly, and so on.

To my personal standards, having high-quality software in Open Source is an unbendable standard that I would never compromise.

While also, keep a certain velocity and momentum is also very important to me. The majority of my motivation is driven by the feeling of accomplishment after I have finished something. I could be in an excellent flow when I can create the feedback loop of iterating things out then delivering.

So, to say, I usually pick Quality and Velocity. In the beginning, the scope of my projects was quite clear and small. I managed to keep the quality high, deliver things fast, and get feedback from the community quickly. At that time, I was able to stay productive and motivated to keep working on those projects.

Scope

I was "accidentally" able to keep that momentum and velocity for quite a long time. I started getting into Open Source with {i18n Ally} and {VueUse}, and since then, I joined Vue and Vite teams. Within 2021 alone, I came up with {Slidev} (April 2021), {UnoCSS} (October 2021) and {Vitest} (December 2021) -- Everything went almost too smoothly that I barely realized the capacity of having larger scope will have a certain limit.
I continued doing so with the "velocity" ignorantly since then. I am super lucky to meet the amazing teams and community, and get help from them:

• The awesome & super supportive {Nuxt} team {@Atinux} {@danielroe} {@pi0}
• {@sheremet-va} {@AriPerkkio} and the Vitest team for taking care of {Vitest}
• {@chu121su12} {@zyyv} and the UnoCSS team for polishing {UnoCSS} a lot
• {@okxiaoliang4} {@wheatjs} {@Alfred-Skyblue} {@Tahul} and the VueUse team for {VueUse}
• {@sxzz} for managing {Unplugin}
• {@KermanX} {@tonai} for pushing many features on {Slidev}
• {@arashsheyda} for helping a lot on {Nuxt DevTools}
• {@shuuji3} {@Shinigami92} for contributing to {Elk}
• {@patak-dev} {@sapphi-red} {@bluwy} for keep pushing Vite forward with the awesome community
• {@userquin} for maintaining {Vite PWA} and helping basically everything everywhere
• {@yyx990803}, whom I learned a lot about OSS and decision-making from
• ...and many of you who have contributed to Open Source or provided financial support via Sponsorships!

It's a shame I couldn't list all of them, and many of them are actually overlapping across projects. What I am trying to say is that, I am not working alone, and I can't do all of these alone. I have borrowed so much help from the community and the teams to have all those projects. I am truly grateful for that. On top of Quality and Velocity, it seems that I also work on a wide Scope of projects - looks like it broke the rule of the iron triangle - but actually, the awesome community behind the scenes is the "magic" that makes it possible.

Capacity

The amount of work required to maintain multiple high-traffic open source projects is honestly massive. I should have reached my limit a long while ago without help from the community. While the community helps me a lot, it still, takes a lot of energy to communicate, coordinate, as well as consistently context-switching. Over time, I accumulated many things I had to do myself, many ideas I wanted to try, and many things I wanted to improve.

I want to keep those projects alive and keep them moving forward; I want to write more blog posts to share my thoughts; I want to do more talks, to travel and meet people; I want to do more live streams as I know many are waiting for it; I have to clean this thing up, to do that release; I also want to learn French; And spend more time with my family - I mean, this is probably just life. People have their own concerns and responsibilities, I ain't any more special or busier than others.

"But somehow, there seems to be something,
something makes me hard to breathe."

I am probably reluctant to admit my potential burnout. Not because I am afraid of it, but more like, I don't want to give up and handle it passively. I know to take rest when I need it, but calling myself "burnout" and giving up is an "easy way out" to escape from the responsibilities. I want to find out the "root cause" and try to improve the situation instead of just "workaround" it. As we talked about previously, the shift of "expectations", and the re-evaluation of my "unpreparedness" and "self-expectations" are my solutions to the moments when I was close to burnout for different reasons. By adjusting myself and adopting, I was usually able to recover from the low points in roughly a week and keep moving forward.

The case this time is a bit different, it's not about me being unmotivated, but rather, there are too many things I wanted to do but I am running out of capacity. I started to think, that maybe it was that I expected myself to keep delivering everything with the same Velocity, I was anxious about not doing enough and not doing fast. Getting quick feedback is awesome and quite productive, but I am probably growing some impatience because I am too used to being quick. Combined, they make me easy to get frustrated when working on something that requires mid-to-long-term effort.

For example, writing. I am not good at writing, and I don't honestly enjoy it. Documentations, blog posts, tutorials, and talks -- all require a lot of time, and also, something I have to do. I easily get distracted and lose focus when I am writing or giving up in the middle. So I asked about it on Twitter and got a lot of great advice from the community (check the comments out and you might find something useful for you too). I started trying to take it easy and doing it slowly, trying to shift my mind to not expecting immediate results and enjoying the process. This blog you are reading took me roughly a week to write (that's a pretty long time for me), fragmented into multiple sessions. I feel also helps me to rethink and reorganize my thoughts and feelings, and actually, writing them down makes me feel much better about my anxiety.

So, I should probably re-evaluate my capacity and expectations. I have to understand and accept that I can not always keep the same velocity and I don't have to push myself too hard. Slowing down a bit to take more care about the details, maybe I will find different joy and satisfaction in the process.

Honestly, I am not even sure what I am trying to tell in this blog post - maybe just simply sharing my thoughts and feelings with you. Right now, I still feel quite some pressure. I am still adapting and trying to find a better way of dealing with it. I feel a lot better throughout this week of writing and talking to friends, and I am sure I will get through this. This might just be like many other things in our lives; we don't always have perfect solutions, but we have to keep going forward and find our way out.

Maintaining good mental health is one of the important tasks for every open source maintainer to keep sustainable. I don't think there would be "an answer" or "a solution" to the highs and lows throughout the journey. It's more like a continuous process of learning and adapting to find the ways that work for each of us.

I'd Love to Hear From You

Thank you for reading through my messy and verbose thoughts until the end!

I know my opinions must be heavily biased. If it ever triggers any thoughts or feelings for you, I am curious to hear what you think or what are your ways. You can leave some comments under this tweet or mastodon, or send me an email at hi@antfu.me if you prefer private conversations. Looking forward to hearing from you!

Meanwhile, there are actually many other things about open source I didn't get to talk about in this post. Artem Zakharchenko wrote a great article The Dark Side of Open Source, from different perspectives and points that I also resonate a lot with. Highly recommended to give it a read as well.

Thanks

Thanks to {@patak-dev} and {@posva} for our deep conversations around this topic, they really helped me a lot and provided great support.

And You, as well as the great open source community! I am so grateful for all the help and support I have received from you.

Till next time, take care!

Slides: PDF | SPA

Made with Slidev - presentation slides for developers.

// @errors: 2540
console.log((1 + 2 + 3 + 4).toFixed(2))
//                            ^|

interface Todo {
  title: string
}

const todo: Readonly<Todo> = {
  title: 'Delete inactive users',
//  ^?
}

todo.title = 'Hello'

Try hovering on each token to see the type information. Shiki runs oniguruma to give syntax highlighting, and TwoSlash runs typescript to give type information. Both are quite heavy libraries, but this is done ahead of time on building, it means that what you see here is completely static pure HTML and CSS!

The Shiki integration allows you to provide custom renderer of how the HTML been generated based on AST. This allows us to have dual themes support, and also the syntax highlighting for the type information.

Check @shikijs/twoslash and commit for the integration on antfu.me, for more information :)

```ts twoslash
// @errors: 2540
console.log((1 + 2 + 3 + 4).toFixed(2))
//                            ^|

interface Todo {
  title: string
}

const todo: Readonly<Todo> = {
  title: 'Delete inactive users',
//  ^?
}

todo.title = 'Hello'
```

[!TIP]
Just a quick tip, that you can use > [!TIP] to create
a GitHub-style alert in your README.md like this.

> [!TIP]
> Just a quick tip, that you can use `> [!TIP]` to create
> a GitHub-style alert in your README.md like this.

The original GitHub proposal is here. It's rolled out basically everywhere on GitHub now.

Use it in your website

And in case you like it, and wanted to use it in your own website, I wrote a quick markdown-it plugin for it:

Vite

If you are using unplugin-vue-markdown:

import MarkdownItGitHubAlerts from 'markdown-it-github-alerts'
// vite.config.ts
import Markdown from 'unplugin-vue-markdown/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Markdown({
      markdownItSetup(md) {
        md.use(MarkdownItGitHubAlerts)
      }
    })
  ],
})

VitePress

If you are using VitePress, you can add this to your .vitepress/config.js:

import MarkdownItGitHubAlerts from 'markdown-it-github-alerts'
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(MarkdownItGitHubAlerts)
    }
  }
})

Nuxt Content

Nuxt Content use remark instead of markdown-it, so the plugin won't work yet. I will implement it later if there is demand.

Reference

• Commit of this blog post and setting it up
• Proposal to VitePress for adding this by default

[!IMPORTANT]
Thanks for reading! :)

Slides: PDF | SPA

Made with Slidev - presentation slides for developers.

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

Inspiration

The first time I saw such stroke animations in SVG is the Material Line Icons by Vjacheslav Trushkin. It was cool, but I never thought about making one my own until I saw Mu-An Chiou's banner on her website. I suddenly feel like I want to be the cool guy too!

Breakdown

I downloaded Mu-An's SVG to read the code, cross-referencing the Material Line Icons. I found the trick is quite interesting, they animated stroke-dasharray to achieve the effect. This feels quite unintuitive as when you check the MDN documentation, it looks like a pretty boring attribute.

I searched a bit more and found these two interesting articles:

• Animated line drawing in SVG by Jake Archibald
• How SVG Line Animation Works by Chris Coyier

They covered this technique very well, highly recommend reading them if you are interested. Basically, the animation is done by a very long dash moving, in which you will see the dash as the drawing line and the gap as empty space. The length and position of the dash are controlled by stroke-dasharray and stroke-dashoffset, which are both animatable.

The Original Logo

My original logo comes from around 8 years ago, I draw it with a pressure-sensitive pen on my Surface Pro 4. It was used as a temporary placeholder for the portfolio I was trying to build at that time. I later image-traced it with Adobe Illustrator to get the SVG version. Surprising to recall, it has been so long since then.

Rework the Logo

As we see, the animation is done by moving the dash on strokes, while my Logo is a vector outline with multiple control points. So I need to redraw it with a single stroke. It took a bit of practice to get used to the pen tool, I managed to make it with Figma.

Manually adding the styles in the exported SVG,

@media (prefers-reduced-motion) {
  path {
    animation: none !important;
    stroke-dasharray: unset !important;
  }
}
@keyframes grow {
  0% {
    stroke-dashoffset: 1px;
    stroke-dasharray: 0 350px;
    opacity: 0;
  }
  10% {
    opacity: 1;
  }
  40% {
    stroke-dasharray: 350px 0;
  }
  /* Moving back */
  85% {
    stroke-dasharray: 350px 0;
  }
  95%,
  to {
    stroke-dasharray: 0 350px;
  }
}
path {
  stroke-dashoffset: 1px;
  stroke-dasharray: 350px 0;
  animation: grow 10s ease forwards infinite;
  transform-origin: center;
  stroke: #303030;
  animation-delay: 0s;
}

now we have a decent animated logo:

The only downside is that the stroke is evenly thick everywhere, making it looks less like a signature. I tried to look for solutions and end up with the Variable width stroke proposal, however, it does not seem to be going anywhere. Well, it's stroke anyway, it's supposed to be even. Giving the animation is super cool already, what else can I ask for?

Variable Stroke Width

When I almost gave up, I was playing around with Figma to do some final cleanup with the drafts, I suddenly realized that SVG does have mask support. So what if I have the original SVG shape as the mask, and let the stroke animate inside the mask? So I gave it a try and surprisingly it works!

Basically we are using the mask to limit the stroke's visibility, a trick to workaround the limitation of the stroke width. Note it's not 100% pixel-perfect, as in the interaction we can't control the stroke width, so the stroke will be a bit off the mask. We can try to adjust the mask to make it look a bit better, but you will still see a big glitch when zooming in a lot. I guess it might be possible to solve this with multiple strokes and masks, but this one is already quite good to me.

Hope you enjoy the article, and I'd love to see your animated SVG logo too!

package-import-method=copy
prefer-symlinked-executables=false

This will make pnpm copy the files instead of symlinking them. And expose the executables in node_modules/.bin correctly.

Co-authored by Anthony Fu, 赛博迪克朗, wangcai and 代々木

This is a live document, will be updated as we learn more. Check back occasionally.

A summary of discussions made in QRBTF's Discord server and Anthony's Discord server. Thanks to everyone who participated in those servers.

What's a Stable Diffusion QR Code?

Images that are generated with Stable Diffusion with QR Codes as ControlNet's input, making the QR Code data points blend into the artwork while still being scannable by QR Code readers.

The original idea was created by the people behind QRBTF, and was first revealed on this reddit by nhciao.

QRBTF recently launched their online generation service for open beta. As of July 14th, 2023, they haven't released their model or methodology yet, you can join their Discord server to follow the latest news.

The methods mentioned in this guide are based on community research and experiments.

How to Generate?

There are a few online services you can try, but this guide will focus on doing it locally on our own. You will need the basic knowledge of Stable Diffusion and ControlNet, a computer with a GPU (or a cloud GPU instance) to start.

If you are new to Stable Diffusion, we recommend reading these guides to get started:

• Stable Diffusion Knowledge Hub
• Stable Diffusion LoRA Models

Once you set them up, there are two approaches to generating a stylized QR Code:

Method A: Text to Image with ControlNet

Generate an image with prompts, and use ControlNet with a QR Code input to intervention the generation process.

• Stylistic QR Code with Stable Diffusion - by Anthony Fu
• Refining AI Generated QR Code - by Anthony Fu
• [Video] 二维码融合技术2.0 - by 赛博迪克朗

Method B: Image to Image

Use a QR Code image as input, and let Stable Diffusion redraw each part of the QR Code. Doesn't require ControlNet.

• How to make a QR code with Stable Diffusion - by Andrew

Our Recommendation

We found that Method A, Text to Image approach produces much better results, and it's easier to control the output. We will mostly focus on that approach in this guide.

ControlNet Models

Here are a few ControlNet models we found useful:

• QR Pattern
• QR Code Monster
• IoC Lab Control Net
  • Brightness Model
  • Illumination Model

See model comparison section for more details.

The Code is Not Scannable

Before going into details, let's picture the goal of your QR Code first. Here are 3 typical approaches listed by @1r00t:

• Artistic code that scans 100% and is obvious but creative
• Code that is kind of hidden but with a bit of fiddling you get it
• Code that is completely hidden as a sort of secret message

All these approaches are viable. They are on a different balance between the art and the functionality. It's better to have such expectations so you can tune your models, parameters and prompts accordingly.

Scanners

When the images are generated, we will use a QR Code scanner to verify if the code is scannable.

If your goal is to make a more blended-in QR Code, and you are okay with the code not being scannable by all QR Code readers, it's better to use an error-tolerant scanner to verify. We recommend using iOS's code scanner from the Control Center, or the scanner from WeChat to verify your QR Code. They are the most tolerant ones we found so far.

Meanwhile, if you failed to find a good scanner on your phone, or want to verify the QR Codes directly in your computer, we recently enrolled a new scanner in Anthony's QR Toolkit, based on WeChat's open sourced algorithm (Ported to WebAssembly, source code at antfu/qr-scanner-wechat).

Compare with the Original QR Code

You can use Anthony's QR Toolkit to compare the generated QR Code with the original one. It will show you the mismatches and help you to optimize the generation process.

Read more about it in this post.

Parameters

ControlNet

The parameters of the ControlNet affect when and how the control is applied to the generation process.

• Control weight - The weight of the ControlNet. The higher the weight, the more the output will be affected by the ControlNet.
• Start control step - The percentage of the generation process when the ControlNet starts to take effect.
• End control step - The percentage of the generation process when the ControlNet stops taking effect.

prompts + control net

prompts

Control Start

Control End

The start control step will allow the prompts and the model to be creative before it knows the QR Code control exists. And the end control step will allow the model to try to blend the QR Code into the artwork more (but will make the code less scannable).

It requires a few trials and errors to find the right balance so that the ControlNet has enough time to intervene, but not too much so the code can be artistic enough.

Different models might have different strengths of the control, so you might need to adjust the parameters accordingly. It's better to read their instructions first.

---

Credits to 赛博迪克朗

Model Comparison

Thanks a lot to 赛博迪克朗 for running the following matrixes against each model.

Here is the original image (without ControlNet) and the QR Code Input:

The comparison matrixes are generated with the exact same prompts and same seed as the original image, but only the parameters of the ControlNet are changed.

Detailed prompts and paramaters

best quality, masterpiece, depth of field, 1girl, dress, trees, flowers, sky, water

NSFW, nude, bad-hands-5, bad-picture-chill-75v, badhandv4, easynegative, ng_deepnegative_v1_75t, verybadimagenegative_v1.3, bhands-neg, watermark, character watermark, photo date watermark, Date watermarking

• Checkpoint: PrimeMix
• Steps: 50
• Sampler: DPM++ 2M SDE Karras
• CFG scale: 7
• Seed: 1902542336
• Size: 768x1024

You can drag the sliders below to see the difference between the start and end control steps:

QR Pattern Model

QR Code Monster Model

IoC Lab Brightness Model

---

Improve the Result

Say that you already generated a bunch of QR Codes and find some of them you like. You want to improve them to make them more scannable, or more blended-in, or more artistic. Here are some tips we found useful.

Tweak the Input

The input QR Code is one of the most important parts of the whole process to generate well-blended code.

You can refer to this post to see a comparison of how different QR Code input affects the output.

We recommend using Anthony's QR Toolkit to generate the QR Code. It allows you to customize the QR Code and distort it as needed.

Meanwhile, the margin area of the QR Code also affects the look and feel, for example:

Adding some noise to the margin

Manually connect some points in margin (Photoshop etc.)

---

Credits to 代々木

Improve the Prompts

Theoretically, you can use any prompts to generate those QR Codes.

To help the QR codes more blend in, we find that it's helpful to include some fluidity or fragmented items in the prompts.

Example Outputs

Example Prompts

Ribbon - by 代々木

(1 girl:1.6), full body, from side, ultra wide shot, (azure blue dress:1.3), (grey long hair:1.3), (white ribbon:1.6), (white lace:1.6), BREAK, (dark background:1.3)

Feather - by 代々木

(1 girl:1.3), upper body, (grey long hair:1.3), (blue dress:1.3), zigzag patterns, graphic impact, (white feathers:1.6), BREAK, (dark background:1.3)

Birds - by 代々木

(1 girl:1.3), upper body, rosemaling patterns, Norwegian folk art, decorative designs, vibrant colors, (white birds:1.6), BREAK, (dark background:1.3)

Wave - by 五倍速企鹅

(1 girl:1.3),(white dress:1.3), upper body, blonde hair, from side, decorative designs, (wave:1.3),BREAK, (blue background:1.3)

Leaf - by 五倍速企鹅

(1 girl:1.3),(pink dress:1.3), upper body, white hair, from side, decorative designs, (leaf:1.6),BREAK, (sunset background:1.3)

---

Credits to wangcai

XYZ Plot

In case you are uncertain about which model or prompts to use, you can utilize the XYZ Plot script to generate a matrix of images with different prompts and models for easier comparison.

You can learn more about how to use XYZ plot in this tutorial.

Below is an example of a matrix runned by wangcai, testing some popular checkpoint models and the prompts we mentioned above. You can click to select different combinations, or click the image to see the full matrix.

Similarly, this is a matrix testing samplers:

We encourage you to try different prompts and models to find the best combination for your use case.

---

Credits to 赛博迪克朗

Non-Square Image

To make the QR Code less obvious, you can try to generate a non-square image, leaving some extra space around the QR Code for the Stable Diffusion to be creative. With that, you can shift the focus of the viewers to the other parts of the image.

To generate a non-square image, you can change the Resize Mode in ControlNet to Resize and Fill and change the Text to Image width or height.

Or in the Toolkit, you click the button on Margin to expand the option and have different margins for each side.

---

Credits to lameguy

Perspective

You can also try to apply some perspective transformation to the QR Code to make it more interesting.

---

Credits to 赛博迪克朗

Multiple ControlNet

Multiple ControlNet layers are mainly used to increase the recognizability of the image when the model control is insufficient. Try to avoid the result deviation caused by excessive changes in the picture, causing the ideal picture cannot be obtained.

Difficulties in recognition may be due to changes in prompts or due to the characteristics of the SD model, resulting in too trivial details of the picture or too bright/dark overall tone to make it impossible to recognize.

This method can effectively improve the automatic recognition success rate of scanning.

Usually, we use QR Code Monster or QR Code Pattern model as the main guidance model, and use the Brightness Model from IoC Lab as the auxiliary model to improve the local contrast.

赛博迪克朗: It's recommended to use the QR Monster model. The QR Pattern v2.0 still has too much interference, which may cause a great change in the style of the image.

For example, running the same prompts as the previous example, when using the QR Code Monster model alone (single model), with control steps 0.0 to 1.0, we got the following results with different weights:

We notice that only Weight 1.5 and 1.7 are scannable (and do not have very good error tolerant), and we also see the compositions of them are changed a lot as the weight increases.

So if we want to keep the original composition but still have good enough recognizability, we could add the Brightness Model as the second model.

We can see that even if we reduce the weight of the Monster Model to 1.0, the recognizability is as good as the single model with the Weight 1.5, while the composition is closer to the original image.

If you want to go further, it's also possible to try more models. For example, here is the result of using QR Code Monster and Brightness Model together with QR Pattern:

If you didn't see the tabs for multiple layers of ControlNet, you can go to the settings page to enable it:

---

Credits to wangcai

OpenPose

To get more control over the composition, you can also use other ControlNet models like OpenPose to generate a human pose and use it as the input of the QR Code.

For example, you can see the following image is generated with both QR Code and OpenPose as the input. With some tricks on the composition, you can shift the focus of the viewers to the other parts of the image and make the QR Code less obvious.

You can learn more about OpenPose in this tutorial.

---

Credits to Anthony Fu

Selective Multi-layer Control

Look deep into the QR Code specification, you can see a QR Code is composed with different types of data and position patterns:

Other than the position markers that are obvious to find, we can see there are also the Version and Format information around the position markers. Those information are quite important because it tells the scanner how to decode the QR Code properly. On the other hand, since the Data area has good error correction and duplications, it's actually fine for it to contain a few misalignment when needed. Now we realize that many QR Code that are not scannable are because those area are not distinguishable enough, causing the scanner to exit early before going into the actual data.

So, since the data points in a QR Code are not equally important, why would we control them equally? Maybe we could try to selective control different areas. Like increasing the control weight of the functional areas and decreasing the weight of the data area, to make the QR Code more scannable while being more artistic.

In the recent update of QR Toolkit, we added a new option Render Type to only generate some specific areas of the QR Code, combining with a grey background, we could have:

Both QR Pattern v2 and QR Code Monster models support having grey as the hint of arbitrary content (bypass the control). Thanks for the information from Nacholmo and Cyril Bareme.

With this, we could use two ControlNet layers:

• Layer 1: Full QR Code, with medium control weight.
• Layer 2: Selective parts of QR Code, with strong weight but shorter control steps.

For example, here I have two ControlNet layers, both using the QR Code Monster model:

In the second layer of the example, I excluded the position markers as I was seeking for more blend-in image. You can also include them if you want to make the QR Code more scannable.

After a few tweaks, the result are surprisingly good. It's able to retain the recognizability of the QR Code while being more artistic. Here are some of the results:

---

Credits to QR Code Monster

Image to Image Enhancement

When you find a generated image is hard to scan, you can try to send the image to img2img, enable ControlNet with your original QR Code input and:

• Decrease the Denoising strength to retain more of the original image.
• Increase the Control weight for better readability.
• A typical workflow for "saving" a code would be: Max out the guidance scale and minimize the denoising strength, then bump the strength until the code scans.

This tells the model to re-enhance the image by making dark areas darker and light areas lighter under the guidance of ControlNet.

---

Manually Editing and Inpainting

The ultimate solution is indeed to manually edit the output image. You can use editing tools like Photoshop combined with inpainting to fine-tune every part of the imaged image. It might require a lot of effort, we'd generally recommend focusing on tweaking the generation first before going to this step. More details can be found in this post.

Extra: Hidden Text in Image

While the QR Code models are primarily designed for generating QR Codes, they are fundamentally brightness-contrast models. This means that they can be used to control and modify anything that exhibits distinct local contrast. So, in addition to generating QR Codes, we can utilize these models to hide text or any symbols inside the generated images. This opens up exciting possibilities for creative exploration beyond just QR Code generation.

For example, we could have this using the exact same methods we learned for generating QR Code:

Input Image

You can click the image to see the full size. When you zoom in on the QR Code image, it can become challenging to distinguish the text from the background. However, when you zoom out significantly, the text becomes much clearer and easier to scan. This observation highlights an interesting aspect of human vision—our eyes are indeed excellent scanners.

Similarly, we could combing with QR Code, or anything you can think of:

Input Image

Contributing

This guide is aimed to be a one-stop documentations and references for the community to learn about the QR Code models and how to use them.

If you are interested in contributing to this post, fixing typos, or adding new ideas, you can edit this page on GitHub. Or if you are not familiar with Git, you can also go to Anthony's Discord server and discuss with us.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/ai-qrcode-refine https://antfu.me/posts/ai-qrcode-refine Fri, 30 Jun 2023 17:00:00 GMT [[toc]]

Update: New blog posts - Stable Diffusion QR Code 101

Last week, I wrote a blog post about how I learned to generate scannable QR Codes. When doing so, I consider my goal is to find an image that looks like a QR Code as little as possible to humans, but still be recognizable by the machine.

We need to find a balance, tweaking the weights to try and error. It's still quite hard to find a good composition that represents the black & white spots, while keeping the content meaningful to human. If you go too far, the QR Code will be unscannable, and if you don't go far enough, the image will just be like a boring QR Code.

Since there is quite some randomness in the process, sometimes it could be a pity when you find a good one but realize it's not scannable. To improve this, my workflow was to open up Photoshop, overlay the generated image with the original QR Code, manually check the difference, use the brush to mark those spots and send to inpaint to draw those areas. It works to some extent, but pretty inefficient as you need to go back and forth quite a few times. Meanwhile, doing this manually can also be inaccurate as the scanning algorithm might see them differently.

So, I need to find a way to automate this, helping me to verify and refine the generated QR Code easier. And I came up with a simple web tool to do so. Let me introduce you to a bit about it.

Anthony's QR Code Toolkit

Generating the Base QR Code

One thing I found quite important is that the generated QR Code we put in the ControlNet affects the image quite a lot. The basic square QR Code will lead to a more square-ish and blocky image. It's worth to try with dots, rounded, or other styled QR Codes to see if they can help to generate a better image.

The images above are generated with the exactly same parameters, and the same seed, except the QR Code inputs has slightly different on the styles. You can see the difference is quite significant.

In addition, since the distribution of QR Codes is directly affecting the image's composition. Sometimes we might find some patterns might be hard to work around. We would need to find different versions of the QR Code to find a better fit to the image we want. If you are familiar with QR Code enough, you might know there is a step in QR Code generated called Mask Pattern. There are in total 8 different kind of patterns can apply to the QR Code that serves the same content. Sadly, most of the generators do not provide the capability to change it. Ok, I'll build it.

So specifically for this need, I built a QR generator based on QR Code Generator Library:

It offers me the full capability of the generation process. You can change the error correction level, mask pattern, version of the QR Code, and rotation to find a good distribution of the black & white spots. Also, it allows you to change the styles of the dots, or add some random noise to the border making the generated image more blended-in.

Generating the Images

Now we have the QR Code, we could move up to generate those images with Stable Diffusion and ControlNet. For detailed steps, please refer to my previous blog post.

Verify and Refine the QR Code

Running overnight, I now got like 200 images generated. Say I find one quite interesting and see some potential of being a good one. I will first use my phone to try to scan it. As mentioned earlier, you may not get lucky every time. This one is unfortunately not scannable.

From a glance, we see there are quite some QR Code-ish spots in this image, which should make it recognizable by the scanner. But why not? Let's find out why:

Using the Compare tab of the toolkit, upload both the generated image and the original QR Code, tweak the grid size, and then we could see the mismatched spots and inspect the nodes.

We can see that the image is not scannable because we have quite a lot of mismatches, saying that some parts of the image might not have enough contrast. Hover on the Highlight Mismatch button, we can see the mismatched spots highlighted:

It seems the top half part of the image is a bit too dark and makes the scanner hard to distinguish. We can also try to increase the image contrast to see how it would look like in the scanner:

Now it's quite clear what's the problem. Then how can we fix it? You can then try to hover on the Preview Corrected button, to see what needs to be changed:

It will lighten the spots that are too dark, and darken the spots that are too bright. Then you see this image immediately becomes scannable now!

It's great but definitely not the final result we would end up with. We can download the correction overlay, or the mask from the toolkit, to use them on inpaint or fine-grained adjustment in Photoshop.

Final

After a few rounds of inpainting and adjustment, upscale to improve details, and now we have the final image as:

Put it back to the toolkit, we see that the mismatched spots are now reduced a lot! Some of the mismatches are actually made on purpose, since QR Code has the error correction capability allowing that.

In case you are interested, here you can see what it looks like when overlaid with the original QR Code:

It's quite interesting to see how the QR Code is been distorted and blended as different parts of the image.

Hide the Markers

The current result is already surprisingly good to me. The only thing that is missing probably is that the position makers do not blend very well, but I guess that's kinda the limitation. When I was about to call it a day and go to bed, thinking about the possibility of making the QR Code makers less obvious, I saw in classic.qrbtf.com (created by the creator that came up with the AI QR Code idea), there is a style call SP-1 that has a "Plus shape" style of the position markers. It looks much less artificial than the squared or double-circle ones. I didn't know it would also work for the scanner, so I think it might be worth a try.

So I implemented it in my generator, and it looks like this:

As you can see, the marker looks much less distinguishable from the other data points (be aware it also make the code less scannable). It might be worth trying as the control net input to see if it can generate better images. But since we already have a pretty good one, let's use the new QR Code to redraw the markers.

So doing the inpainting process again using the new QR Code, and a few more editing, we have the final result as:

Even though I made it step by step, it's still mind-blowing to see the final result looks like this but still scannable! 🤯

Check it on Civital

Bonus Tip: Distort the QR

Since we found the QR Code input affects the output image quite significantly. In another way of thinking, instead of refining the generated image in the post, maybe we can also try to manipulate the QR Code itself before sending it to the model.

For example, we could use the generator to try different patterns and configurations, to generate a better distribution of the data points. Adding some noise in the margin, making the position makers more randomized, and rounding up the hard edges to reduce the blocky feeling. We could have:

Then I started to think about what more we could do. So I tried to play filter effects in Photoshop. I found that the Distort > Ripple and Pixelate > Crystallize filters have quite a balanced distortion effect. So I reimplemented the crystallize effect in the toolkit, and we have:

This further blurs the distinction between data points in human eyes. Sending it to the model, we get surprisingly very good results! Here is one of the examples:

Since input has much more soft edges with some shades, it makes the model being able to "guess" with items with more freedom. Hope you'll find this tip useful! I will try to implement more useful effects in the toolkit as we go.

Conclusion

I hope you enjoy the walkthrough. If you just started doing AI QR Code, give a try to the tool and let me know if it helps. You can find the app and the source code below.

Anthony's QR Code Toolkit

antfu/qrcode-toolkit

Join my Discord Server, share what you are working on, and let's explore more together!

If you are interested in how I make such tools, I'd recommend continuing reading About Yak Shaving to learn the philosophy I follow when building tools. And if you like my work, consider sponsoring on GitHub Sponsor to support me in coming up with more ideas and tools.

Thank you and happy hacking!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/ai-qrcode https://antfu.me/posts/ai-qrcode Sun, 25 Jun 2023 05:00:00 GMT [[toc]]

Update: New blog posts

• 👉 Refining AI Generated QR Code
• 📚 Stable Diffusion QR Code 101

Yesterday, I created this image using Stable Diffusion and ControlNet, and shared on Twitter and Instagram -- an illustration that also functions as a scannable QR code.

The process of creating it was super fun, and I'm quite satisfied with the outcome.

In this post, I would like to share some insights into my learning journey and the approaches I adopted to create this image. Additionally, I want to take this opportunity to credit the remarkable tools and models that made this project possible.

Get into the Stable Diffusion

This year has witnessed an explosion of mind-boggling AI technologies, such as ChatGPT, DALL-E, Midjourney, Stable Diffusion, and many more. As a former photographer also with some interest in design and art, being able to generate images directly from imagination in minutes is undeniably tempting.

So I started by trying Midjourney, it's super easy to use, very expressive, and the quality is actually pretty good. It would honestly be my recommendation for anyone who wants to get started with generative AI art.

On my end, being a programmer with strong preferences, I would naturally seek for greater control over the process. This brought me to the realm of Stable Diffusion. I started with this guide: Stable Diffusion LoRA Models: A Complete Guide. The benefit of being late to the party is that there are already a lot of tools and guides ready to use. Setting up the environment quite straightforward and luckily my M1 Max's GPU is supported.

QR Code Image

A few weeks ago, nhciao on reddit posted a series of artistic QR codes created using Stable Diffusion and ControlNet. The concept behind them fascinated me, and I defintely want to make one for my own. So I did some research and managed to find the original article in Chinese: Use AI to Generate Scannable Images. The author provided insights into their motivations and the process of training the model, although they did not release the model itself. On the other hand, they are building a service called QRBTF.AI to generate such QR code, however it is not yet available.

Until another day I found an community model QR Pattern Controlnet Model on CivitAI. I know I got to give it a try!

Setup

My goal was to generate a QR code image that directs to my website while elements that reflect my interests. I ended up taking a slightly cypherpunk style with a character representing myself :P

Disclaimer: I'm certainly far from being an expert in AI or related fields. In this post, I'm simply sharing what I've learned and the process I followed. My understanding may not be entirely accurate, and there are likely optimizations that could simplify the process. If you have any suggestions or comments, please feel free to reach out using the links at the bottom of the page. Thank you!

1. Setup Environment

I pretty much follows Stable Diffusion LoRA Models: A Complete Guide to install the web ui AUTOMATIC1111/stable-diffusion-webui, download models you are interested in from CivitAI, etc. As a side note, I found that the user experience of the web ui is not super friendly, some of them I guess are a bit architectural issues that might not be easy to improve, but luckily I found a pretty nice theme canisminor1990/sd-webui-kitchen-theme that improves a bunch of small things.

In order to use ControlNet, you will also need to install the Mikubill/sd-webui-controlnet extension for the web ui.

Then you can download the QR Pattern Controlnet Model, putt the two files (.safetensors and .yaml) under stable-diffusion-webui/models/ControlNet folder, and restart the web ui.

2. Create a QR Code

There are hundreds of QR Code generators full of adds or paid services, and we certainly don't need those fanciness -- because we are going to make it much more fancier 😝!

So I end up found the QR Code Generator Library, a playground of an open source QR Code generator. It's simple but exactly what I need! It's better to use medium error correction level or above to make it more easy recognizable later. Small tip that you can try with different Mask pattern to find a better color destribution that fits your design.

3. Text to Image

As the regular Text2Image workflow, we need to provide some prompts for the AI to generate the image from. Here is the prompts I used:

Prompts

(one male engineer), medium curly hair, from side, (mechanics), circuit board, steampunk, machine, studio, table, science fiction, high contrast, high key, cinematic light,
(masterpiece, top quality, best quality, official art, beautiful and aesthetic:1.3), extreme detailed, highest detailed, (ultra-detailed)

Negative Prompts

(worst quality, low quality:2), overexposure, watermark, text, easynegative, ugly, (blurry:2), bad_prompt,bad-artist, bad hand, ng_deepnegative_v1_75t

Then we need to go the ControlNet section, and upload the QR code image we generated earlier. And configure the parameters as suggested in the model homepage.

Then you can start to generate a few images and see if it met your expectations. You will also need to check if the generated image is scannable, if not, you can tweak the Start controling step and End controling step to find a good balance between stylization and QRCode-likeness.

4. I'm feeling lucky!

After finding a set of parameters that I am happy with, I will increase the Batch Count to around 100 and let the model generate variations randomly. Later I can go through them and pick one with the best conposition and details for further refinement. This can take a lot of time, and also a lot of resources from your processors. So I usually start it before going to bed and leave it overnight.

Here are some examples of the generated variations (not all of them are scannable):

From approximately one hundred variations, I ultimately chose the following image as the starting point:

It gets pretty interesting composition, while being less obvious as a QR code. So I decided to proceed with it and add add a bit more details. (You can compare it with the final result to see the changes I made.)

5. Refining Details

Update: I recently built a toolkit to help with this process, check my new blog post 👉 Refine AI Generated QR Code for more details.

The generated images from the model are not perfect in every detail. For instance, you may have noticed that the hand and face appear slightly distorted, and the three anchor boxes in the corner are less visually appealing. We can use the inpaint feature to tell the model to redraw some parts of the image (it would better if you keep the same or similiar prompts as the original generation).

Inpainting typically requires a similar amount of time as generating a text-to-image, and it involves either luck or patience. Often, I utilize Photoshop to "borrow" some parts from previously generated images and utilize the spot healing brush tool to clean up glitches and artifacts. My Photoshop layers would looks like this:

After making these adjustments, I'll send the combined image back for inpainting again to ensure a more seamless blend. Or to search for some other components that I didn't found in other images.

Specifically on the QR Code, in some cases ControlNet may not have enough prioritize, causing the prompts to take over and result in certain parts of the QR Code not matching. To address this, I would overlay the original QR Code image onto the generated image (as shown in the left image below), identify any mismatches, and use a brush tool to paint those parts with the correct colors (as shown in the right image below).

I then export the marked image for inpainting once again, adjusting the Denoising strength to approximately 0.7. This would ensures that the model overrides our marks while still respecting the color to some degree.

Ultimately, I iterate through this process multiple times until I am satisfied with every detail.

6. Upscaling

The recommended generation size is 920x920 pixels. However, the model does not always generate highly detailed results at the pixel level. As a result, details like the face and hands can appear blurry when they are too small. To overcome this, we can upscale the image, providing the model with more pixels to work with. The SD Upscaler script in the img2img tab is particularly effective for this purpose. You can refer to the guide Upscale Images With Stable Diffusion for more information.

7. Post-processing

Lastly, I use Photship and Lightroom for subtle color grading and post-processing, and we are done!

The one I end up with not very good error tolerance, you might need to try a few times or use a more forgiving scanner to get it scanned :P

Conclusion

Creating this image took me a full day, with a total of 10 hours of learning, generating, and refining. The process was incredibly enjoyable for me, and I am thrilled with the end result! I hope this post can offer you some fundamental concepts or inspire you to embark on your own creative journey. There is undoubtedly much more to explore in this field, and I eager to see what's coming next!

Join my Discord Server and let's explore more together!

If you want to learn more about the refining process, go check my new blog post: Refining AI Generated QR Code.

References

Here are the list of resources for easier reference.

Concepts

• Stable Diffusion
• ControlNet

Tools

• Hardwares & Softwares I am using.
• AUTOMATIC1111/stable-diffusion-webui - Web UI for Stable Diffusion
  • canisminor1990/sd-webui-kitchen-theme - Nice UI enhancement
• Mikubill/sd-webui-controlnet - ControlNet extension for the webui
• QR Code Generator Library - QR code generator that is ad-free and customisable
• Adobe Photoshop - The tool I used to blend the QR code and the illustration

Models

• Control Net Models for QR Code (you can pick one of them)
  • QR Pattern Controlnet Model
  • Controlnet QR Code Monster
  • IoC Lab Control Net
• Checkpoint Model (you can use any checkpoints you like)
  • Ghostmix Checkpoint - A very high quality checkpoint I use. You can use any other checkpoints you like

Tutorials

• Stable Diffusion LoRA Models: A Complete Guide - The one I used to get started
• (Chinese) Use AI to genereate scannable images - Unfortunately the article is in Chinese and I didn't find a English version of it.
• Upscale Images With Stable Diffusion - Enlarge the image while adding more details

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/nuxt-dx-strasbourg-2023 https://antfu.me/posts/nuxt-dx-strasbourg-2023 Thu, 25 May 2023 00:00:00 GMT

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/manage-github-notifications-2023 https://antfu.me/posts/manage-github-notifications-2023 Wed, 17 May 2023 00:00:00 GMT

Slides: PDF | SPA

Recording: YouTube | 哔哩哔哩

Made with Slidev - presentation slides for developers.

Transcript

As you see, I am maintaining a range of projects, across different organizations and teams. Some are quite large with a lot of users and contributors, some are smaller, like the upstream libraries. In order to keep them maintained, I figured out a methodology, I'd call it "Notification-driven Developement".

Since there are too many repositories to keep track of, why don't we let notifications to do the lead? At some level, I think how many notifications you have for a project is a good indicator of how active the project is. For example, some underlying libraries that has been silent for a while probably means it's relatively stable and doesn't need much maintenance, or no one is actually using them. Either way, the notifications can show you where the community is focusing on.

Same as many of you, I get a lot of notifications every day.

This could look quite scary. Well don't worries, the number is made up. But we know that if we leave them there, the number will only grow and eventually hit the point that would make you feel overwhelmed. Which is something I believe we all want to avoid.

So, my approach is that - I do Inbox-Zero, everyday. Well, at least, I try to achieve that everyday.

Why Inbox-Zero?

You must be curious what's the benefit of doing Inbox-Zero. Here are some of my thoughts.

The first point is to be responsive. Providing feedback on time is one of the important ways to maintain a healthy community and make contributors feel welcomed. You will see people sending appreciation messages when you reply to them in a timely manner. It feels good, and also encourages them to contribute more.

The second point is to keep your maintenance work in control. If we are able to tackle most of incoming notifications everyday, we don't accumulate too much work that might beyond our capacity.

Then naturally, you will know better of what to focus on since now we have smaller maintenance scope.

0. Reduce Notifications Created

Before we start to talk about how to manage notifications, let's first talk about how to reduce the number of notifications created beforehand. Like writing good contribritions guide, have good issue forms and templates, and so on. These could help contributors have more information, and at some level, reduce the number of duplications or low quality issues. I won't dive into details here, but instead I'd like to share a interesting tip that could help you manage those information better.

GitHub supports a magic repository called .github. You can create one under your organization or personal namespace. Put the contributions guides and the templates in that repository, and they will be automatically applied to all the repositories under the organization or your account. This could greatly save your time and effort to maintenance those community health especially when you have a lot of repositories.

1. Seek for Notifications

Now let's talk about how I manage the notifications. The first tip is to seek for notifications, and don't let them seek for you. I would highly recommand you to turn off your email notifications or the push notifications on your phone, if you haven't. You don't want to being interrupted by notifications when you are working on something else, or in the middle of sleeping. Instead, I would look for notifications proactively, at the beginning of the day, or when I finished my current task.

You can either use GitHub Notifications Inbox to do so, or you can also give to try on Volta, project management tool our team is building on top of GitHub. Allowing you to track your notifications and milestones in a more intractive way. It's free for open source, so I would definitely recommand you to give it a try to see if it fits your workflow. Today, I will focus more on using GitHub's native notifications inbox.

2. Group Notifications

The second tip I would love to share is to group your notifications by repository, instead of solely on time. When you looking at a list of notifications like this, it's easy to get lost of which repository they are from, or that is happening in which project.

To do so, you will see there is a "Group by repository" button on the top right corner of the notifications inbox. Click it, it will now divide the notifications into different groups, and you can see the repository name on the top of each group.

I found this is a huge time saver, as I can now focus on one repository at a time, and avoid doing context switching too often. You can then filter out the notifications for each repository easier.

3. What to Focus

Then the last point to to know what to focus, and set priority. I will try to filter out the noises, dismiss the unrelated notifications, so I can keep the notifications inbox as my temporary todo list.

In practice, I will first dismiss issues and PRs that are closed or merged, when I didn't participant in. In the other words, I trust the decision made by my team. A closed issue usually means the conversion is over, or we would encourage people to create new issues if it's still relevant. This along already saved me a lot of time.

Then I will dismiss a range of notifications immediately as well. For example, the notifications from bots. We might have some deployment bots, or the bots automatically ask for reproductions or missing informations, for those, I will dismiss until here are human interactions.

Then also smaller things like new commits pushed to a working-in-progress PRs, or GitHub Actions been canceled, etc.

Following these rules, I have been manually dismiss them for a long while, until someday I feel it's still a lot of work to do so. So, I wrote a userscript, a piece of JavaScript you injected into GitHub on your local to automate this. It's called . Be aware it's quite hacky and opinionated, but I wish it could be a good starting point for you to build your own automation.

It does a few things, that I see a huge improvement to my workflow. First, it automatically dismiss the "unrelated" notifications I just mentioned.

Then it colorize the notifications by types. As you see, review request becomes purple, and metion and author becomes green and so on. This would help to determind which issue to check first when you scanning the list.

Then it keep only single instance of the notification tab. I commonly found myself opening multiple tabs of the notifications inbox, and they are usually opened in different time and has different state. It could be quite confusing as you will see the notifications that you might already handled. So this userscript will keep only one instance of the notifications tab, and when you open a new one, it will close the previous one.

And lastly, it automatically refresh the page to keep the notifications always update to date.

Wrapping Up

So to wrap it up, there are a few finally points I would love to share. The goal is indeed not the make the Inbox-Zero itself, but just one way I use to keep the maintenance scope managable and avoid to let it grow out of control.

Applying to notifications, I will also do Reply and forget. I will usually reply to the issue or PR, and then dismiss the notification and "forget" about it. As we know the new notifications will come up once you get replied. This would help to reduce the frustration of long-distance back-and-forth conversations.

And of course, use the tools to help you focus and manage them.

Finally, the most important point to enjoy what you are doing and keep good work-life balance.

Thank you!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/sliding-enter-animation https://antfu.me/posts/sliding-enter-animation Sun, 07 May 2023 00:00:00 GMT import { useRouter } from 'vue-router/auto' const router = useRouter()

As you might notice, I recently added a sliding enter effect to almost all the pages in my blog. And I quite like it. If you missed it, <a @click="router.go(0)">refresh the page to see it in action.

This effect is inspired by paco.me - the portfolio of Paco Coursey, one of my favorite developer-designers.

In this blog post, let's break it down and implement one our own.

Breakdown

If you go inspecting the source code of paco.me, you will find that it's implemented with CSS animation, and it's quite concise:

@keyframes enter {
  0% {
    opacity: 0;
    transform: translateY(10px);
  }

  to {
    opacity: 1;
    transform: none;
  }
}

[data-animate] {
  --stagger: 0;
  --delay: 120ms;
  --start: 0ms;
}

@media (prefers-reduced-motion: no-preference) {
  [data-animate] {
    animation: enter 0.6s both;
    animation-delay: calc(var(--stagger) * var(--delay) + var(--start));
  }
}

[data-animation-controller='false'] [data-animate] {
  animation: none;
}

And in the HTML usage, we have:

<p style="--stagger: 1" data-animate>Block 1</p>
<p style="--stagger: 2" data-animate>Block 2</p>

It defines a keyframe animation enter that slides the element up by 10px and fades, creating the gentle "floating" effect. The key point is the animation-delay property - assigning a different delay to each element/block, making them have the effect of enter one by one. Then, some CSS variables are used to make the the delay sequence easier to control.

Applying to Contents

Now with it, we should be able to add nice sliding enter animation to our layout and homepage, etc. Even though it can be a bit verbose to add style to each element, it gives you full control of what and when those animations take place.

However, when it comes to content like a Markdown page, it will not be that pleasant to wrap each paragraph with a <p> tag and add the data-animate attribute. So I begin to wonder if there is an easier way to apply to all my posts.

I started messing up with the CSS Counters, an interesting way allowing you to store some numeric variables inside of CSS.

So it should be something like this, where you can add slide-enter-content class wrapping the generated content of a Markdown page:

.slide-enter-content {
  counter-reset: enter-count;
}

.slide-enter-content > p {
  --stagger: 0;
  --delay: 150ms;
  --start: 0ms;
  animation: slide-enter 1s both 1;
  animation-delay: calc(var(--start) + var(--stagger) * var(--delay));
}

.slide-enter-content > p {
  counter-increment: enter-count;
  --stagger: counter(enter-count);
}

It all seems to make sense, but it actually doesn't work. The reason is that the counter() function returns a string instead of a number and currently there is no way to convert it to a number, in which the calc() function will fail to compute. There are some discussions & proposals about this, but it seems not going to happen very soon.

So as a workaround, which also been posted in the previous link, we can use the nth-child() selector to achieve the same effect, manually:

.slide-enter-content > * {
  --stagger: 0;
  --delay: 150ms;
  --start: 0ms;
  animation: slide-enter 1s both 1;
  animation-delay: calc(var(--start) + var(--stagger) * var(--delay));
}

.slide-enter-content > *:nth-child(1) { --stagger: 1; }
.slide-enter-content > *:nth-child(2) { --stagger: 2; }
.slide-enter-content > *:nth-child(3) { --stagger: 3; }
.slide-enter-content > *:nth-child(4) { --stagger: 4; }
.slide-enter-content > *:nth-child(5) { --stagger: 5; }
.slide-enter-content > *:nth-child(6) { --stagger: 6; }
.slide-enter-content > *:nth-child(7) { --stagger: 7; }
.slide-enter-content > *:nth-child(8) { --stagger: 8; }
.slide-enter-content > *:nth-child(9) { --stagger: 9; }
.slide-enter-content > *:nth-child(10) { --stagger: 10; }
.slide-enter-content > *:nth-child(11) { --stagger: 11; }
.slide-enter-content > *:nth-child(12) { --stagger: 12; }
.slide-enter-content > *:nth-child(13) { --stagger: 13; }
.slide-enter-content > *:nth-child(14) { --stagger: 14; }
.slide-enter-content > *:nth-child(15) { --stagger: 15; }
.slide-enter-content > *:nth-child(16) { --stagger: 16; }
.slide-enter-content > *:nth-child(17) { --stagger: 17; }
.slide-enter-content > *:nth-child(18) { --stagger: 18; }
.slide-enter-content > *:nth-child(19) { --stagger: 19; }
.slide-enter-content > *:nth-child(20) { --stagger: 20; }

The limitation is clear, that the animation only applies to a finite number of elements. You could add more CSS rules to support more, but in practice, I think 20 elements are already quite enough as we don't usually have that many paragraphs fit in one screen.

So that's it, I have applied this effect to most of the pages as well as the blog posts. Let me know what do you think! And you can find the source code here.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/introducing-nuxt-devtools https://antfu.me/posts/introducing-nuxt-devtools Mon, 27 Mar 2023 16:00:00 GMT Go to nuxt.com and read the full announcement.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/break-lines-in-js https://antfu.me/posts/break-lines-in-js Fri, 10 Feb 2023 16:00:00 GMT You probably don't need it usually, but in case you want to break lines programmatically in JavaScript, here is my lazy man's solution:

// break lines at space with maximum 25 characters per line
text.split(/(.{0,25})(?:\s|$)/g).filter(Boolean)

A quick example:

const text = 'A quick brown fox jumps over the lazy dog.'
const lines = text.split(/(.{0,16})(?:\s|$)/).filter(Boolean)

console.log(lines)
// ['A quick brown', 'fox jumps over', 'the lazy dog.']

You probably see a few edge cases already. But come on, it's just one line of code :P

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/nuxt-dx-2023 https://antfu.me/posts/nuxt-dx-2023 Thu, 09 Feb 2023 00:00:00 GMT

Slides: PDF | SPA

Recording: YouTube | Bilibili (中文)

Made with Slidev - presentation slides for developers.

Transcript

Let's talk about Developer Experience. These years we have heard about Developer Experience more and more often. Frameworks have put a lot of effort into improving Developer Experience, to make our work more efficient and productive, and of course, a better experience. Here I'd like to divide the big concept into different parts and see what we have done to really make a difference from a framework's perspective.

---

The first thing I am going to pick is "Responsiveness".

In Nuxt 3, we switched our default bundler to Vite, the tool well-known for its instant hot module replacement, or so call HMR. It allows you to see the change from your code to the app in nearly no time, and creates a great workflow and feedback loop.

On the server-side rendering, we use vite-node, the same engine that powers Vitest, to do the HMR on the server-side.

And finally, we introduced Nitro along with Nuxt 3, apart from many awesome features it provides, it also offers hot reload for server APIs on dev time. Remember the time you need to restart your node process every time you change to your backend API? It's no longer the case with Nitro!

Combining all these tools, we are able to make your app reactive for any changes you make, no matter whether it's client code, ssr, or server-side APIs.

---

As a framework, Nuxt offers common practices built-in.

TypeScript and ESM are supported out-of-box, thanks to Vite.

Nuxt also makes it simple to build single-page application, server-side rendering, static site generation, or hybrid them per routes - using the same codebase isomorphically without any explicit setup.

Then we provided the layout system, plugins, route middlewares, etc., to make the app creation easier and your codebase better organized.

On top of that, we also provided a few composable utilities like useState and useAsyncData, and SEO utilities like useHead and useSeoMeta to make states accessible across the server and client sides.

Not to mention we also have one of the best backend integrations. With Nitro, you can deploy your Nuxt app to any hosting service like Vercel, Netlify, Cloudflare, etc., with zero-config!

All of these features are trying to provide the common practice and sensible defaults that you might need, out-of-box. And save you time going down the rabbit hole configuring them.

---

And then to the cool part, we also introduced some conventions.

The first one is file-based routing, which allows you to have a multi-page app by simply creating the Vue component with the same structure in the filesystem.

Similarly, with the power of Nitro, we also have file-based server APIs, where you can create your serverless APIs in the same way as routing.

Then we add components auto-imports, components under the components folder will be directly available in any Vue file with the same name as their file name. And also, they will are code-splitted well.

And in Nuxt 3, we introduced compostables auto-import. It means you no longer need to type import { ref } from 'vue' in every component. APIs from Vue are directly available to you. 3rd party modules could also provide their custom composables to be auto-imported, and the same works for your local composables.

We also introduced client and server-only components. Making it easy, you can directly do it by adding .client and .server at the end of your component filename.

And finally, all those conventions are fully typed. You can even have type autocomplete when doing route navigation or fetching data from the APIs.

Conventions are introduced to greatly reduce the boilerplates you need to write and avoid duplications in your codebase. Which I see have significant benefits to boost your productivity.

---

When it comes to the ecosystem, Nuxt has a large community to build modules around it. Look at these on our site, we have hundreds of high-quality modules for you to pick from, and all of them here are available to Nuxt 3. With modules, getting integrations for features you want is effortless. And they are taking care of the details and best practices for you.

---

So, with so many great features we would have from a framework, there is, unfortunately, one problem - Transparency.

This might be considered a trade-off of having a framework or actually any tools. Every time we build some cool new features, we add a bit of abstraction to the framework. The abstraction is indeed a great thing to hide some implementation complexity from the users, but it sometimes could also create some extra burden for users to understand. And the conventions could sometimes lead to implicitness, where it's not clear where a component is from, or who is using a certain component, etc. And of course, sometimes it can make things hard to debug.

So how can we improve this?

---

To solve the same issue I had in Vite. I made the package called vite-plugin-inspect. It provides a UI for you to inspect the intermediated state of each plugin transformation of Vite. This makes the Vite pipeline transparent, and you can see how your code has been transformed step by step. If there is anything goes wrong, you can spot which plugin is causing that. (Demo a bit)

Since vite-plugin-inspect is for Vite, it can actually work with any framework or tools built on top of Vite, including Nuxt. However, because Vite is framework agnostic, the inspect feature is relatively low-level. It can be helpful in some cases, but it can also be quite limited.

---

So, by having the context of Nuxt, let's take one step forward -

Introducing Nuxt DevTools!

---

Nuxt DevTools is a set of visual tools that help you to know your app better. It will enhance your overall developer experience with Nuxt. Providing more transparency to the conventions. We also wish it to be able to help you monitor the performance and find the bottleneck. It should be interactive and playful, and it would be great if it could be personalized documentation when you need it.

So that's the plan. And it's indeed a big plan to achieve. Today I am going to showcase to you a bit preview of the things we have been working on.

---

Let's go demo time!

So, here is a dev server of Elk, a Mastodon client built with Nuxt. Daniel already gave a great explanation in his talk. With Nuxt DevTools enabled, here we have a small Nuxt icon on the bottom to open up the DevTools. Click it we see it pop up on a panel right inside our app. Just be aware that this is a very early preview, we have quite a lot of features are not yet been implemented and many things might be changed.

Let's get started. First, we will see a quick overview of your app, like which version you are using, and how many pages, components and composables you have. This is a barebone page for now but we will make it better.

So let's quickly go through the features we have.

The first tab we have pages, here you can see your current route of your app, and all the routes available. You can quickly navigate between pages by simply clicking them. You can also use the text box to see how the route is matched. When it's orange, it means you don't have a page for that route. When it's green, you can navigate to them by pressing enter.

Let's go to the next components tabs. Here it lists all the components you have in your app, and either they are from the user components, registered at runtime, from Nuxt, or from 3rd-party libraries. You can search from them, can click to go the source file in your editor.

You can also see the components graph by clicking the button here. You see Elk is indeed a complex project that has a lot of components. You can click one component and filter the graph to see how this component is using the others.

Nuxt DevTools also integrated components inspector, where you can click the arrow button here and goes to your app, to know where an element is from. Click it, it will open the source code to the exact line of that component.

Then we have imports tabs to show all the auto-imported entries you have from different sources. For example, here you can see VueUse offers many functions and we are using some of them. Click into, you will see a short description of what it does, and a link to the documentation page of that specific function, and how many files are referencing it.

Go to the modules tab, you will see the modules you have installed. With their informations and links to the documentation. In the future, we plan to have some nice UI for you to install or even manage your modules with one-click.

Here we have all the plugins executed in order. This page is working in progress.

Then we have runtime configs and payload. Where you can see the data you have from useRuntimeConfig(), or the state you have from useState(), useAsyncData() etc. And they are reactive and editable. You can change the color mode by editing this here.

We have a hooks tab, to show you how Nuxt hooks been executed in both client side and server side, and how much time they cost. This could be helpful to find the bottleneck of your app or even help us to find bugs in Nuxt core.

Then we have virtual files from Nitro, the generated-code to support Nuxt's convention. This is a bit advanced mostly for module authors.

And if you are already using vite-plugin-inspect, here for sure we have it built-in as well!

Alright, so that's the feature we had for Nuxt DevTools right now. We hope you like them.

---

Oh, almost forgot, we have one more thing!

---

Nuxt DevTools is also designed to be flexible and extensible. That means modules can actually contribute to DevTools to present interactive information for their integrations. Here let me show you a few modules that support Nuxt DevTools right now.

The first one is VS Code, let's click the "Start" button first. Thanks to VS Code Server, we are able to embed a fully featured VS Code into the DevTools, where you can sync with your vscode settings as your local, and all the extensions are available. With this, you are now able to edit your file without even leaving your app, for example, let's change the title of Elk (edit NavTitle.vue). You see, it's instant! You can also close the DevTools and open it back at any time.

Let's go to the next one. When you have the VueUse module installed, the module will contribute a new tab to the DevTools, and this shows all functions of VueUse with instant search.

Similarly, we also have UnoCSS inspector, where you can see how each file uses the atomic CSS, and how CSS is generated.

And finally, with the nuxt-vitest module, that Daniel and I have been working on recently, allows you to run your tests alongside your dev server, using the exact same pipeline as your Nuxt app. Whenever you update your file, the test will automatically reruns so you can see the client get updated and the test result at the same time!

This is only something we have right now as a MVP. We see great potential on this and it would be hard to imagine how it would end up being. We would like to invite you to join us for brainstorming and bringing an even better developer experience to Nuxt.

---

And so, the preview of Nuxt DevTools is open-sourced, right now! You can give it a star at Nuxt Devtools and find the instructions there for trying it in your Nuxt apps.

That's all for my talk. Thank you!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/bonjour-paris https://antfu.me/posts/bonjour-paris Sat, 10 Dec 2022 16:00:00 GMT Bonjour Paris!

I am so excited to share with you that I have moved to Paris!

Paris is always my dream city, it's still a bit unreal to see that I am actually here! Here I am going to share with you some of my life updates and what would they mean to me.

Thanks

At the very first, I need to give a HUGE thanks to my company NuxtLabs and my colleagues. They made all this possible and helped us a lot along the way.

And also thanks to every one of you. It's your support that helps me find my work valuable and continue working on them. You couldn't imagine my mom and my friends' reactions when I first told them my journey of getting a career by typing on the keyboard at home - the magic of Open Source and the communities! More than that, I got to know so many of you - my friends, colleagues, teams, contributors, followers or fans. All of these really changed our life, thank you!

Life

Before coming to France, I was a digital nomad for 1.5 years in China. It was a really special experience for me, that I also been through quite a lot of ups and downs. It's fun and fresh to wake up in different places every day, but it also comes with a lot of challenges and trade-offs. You got to get familiar with the new environment every day, and meet new friends but also need to say goodbye very soon.

This time I am going to stay in Paris for a long while. Learning the language, exploring the city, meeting new people and getting a cozy home. It's a new chapter for me, I am so excited about it!

Photography

I was quite passionate about photography before I started working on Open Source. Since my focus shifted to programming, I took fewer photos, which is the thing I always feel a bit pity. I think this could be a good chance for me to get back to it.

Instead of carrying a heavy DSLR with lenses, I got a Ricoh GR3x that can easily fit in my pocket. Using it for a few weeks, I found myself becoming more willing to carry it and take photos every day.

Travel

So happy the pandemic is close to the end, and I can finally join you in conferences and meetups!

Oh by the way, I am going to Vue Amsterdam on February 9-10 in person! It would be my first-ever in-person speaking. I am so excited to meet you there!

Once I am settled down, I plan to travel around Europe and visit some of my friends. Let's have a cup of coffee if you are around!

I have been in Paris for only a week, and I am already in love with it! I am so excited about what is coming next to share with you!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/patterns-of-vueuse-vuefes-japan-2022 https://antfu.me/posts/patterns-of-vueuse-vuefes-japan-2022 Sun, 16 Oct 2022 00:00:00 GMT

Vue Fes Japan 2022

Slides: PDF | SPA

Made with Slidev - presentation slides for developers.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/vite-on-demand-dx-viteconf-2022 https://antfu.me/posts/vite-on-demand-dx-viteconf-2022 Tue, 11 Oct 2022 00:00:00 GMT

ViteConf

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/dev-ssr-on-nuxt https://antfu.me/posts/dev-ssr-on-nuxt Tue, 04 Oct 2022 00:00:00 GMT [[toc]]

In Nuxt 3, we introduced first-class support for Vite as bundler, interchangeable with Webpack (also available in Nuxt 2 with Bridge). Since Vite provides an incredibly fast developer experience, we had to make sure SSR works as fast.

Since Nuxt 3 RC.9, we shipped a new development-time SSR approach that is as fast as Vite's HMR with on-demand capability. Here is writeup on how we iterated to make it possible.

SSR

In case you are not familiar with SSR already, let me do a brief introduction.

Server-side rendering (SSR) is a popular tech to improve SEO and initial page rendering speed. When using frameworks like Vue, the components are written purely in JavaScript. This means your distribution app's index.html would look like this:

<html>
  <body>
    <div id="app">
      <!-- Empty. And will be rendered by JavaScript in the client browser -->
    </div>
    <script src="/assets/app.js"></script>
  </body>
</html>

When a user visits your website, the browser fetches and evaluates the JavaScript to let the framework render the content of your app (Client-side Rendering, CSR). Compared to the old age where all the content were directly written in HTML and made available directly when visiting, the modern way to build websites make the time between users hitting the Enter and seeing the content much longer (we call it First Meaningful Paint (FMP) or LCP in performance measurement).

SSR is introduced to solve this. By rendering the app on the server side before the page is served, the content can be delivered directly as HTML. With SSR, the example above will be served as:

<html>
  <head>
    <!-- Manifests injected by SSR -->
    <link rel="stylesheet" href="/assets/app.css" />
  </head>
  <body>
    <div id="app">
      <!-- SSR -->
      <h1>Your title</h1>
      <p>These contents are server-rendered and shipped with the HTML</p>
    </div>
    <script src="/assets/app.js" async></script>
  </body>
</html>

Once the JavaScript has been downloads and evaluated, the client app will hydrate the static DOM to provide client-side interactivity.

If you are interested in learning more details about SSR and CSR, I recommend reading Rendering on the Web by Jason Miller and Addy Osmani.

SSR in Development

In general, when talking about SSR, we commonly refer to a web server in production that can render the page into HTML upon every incoming request. While the performance gain from SSR seems to only matter to the end users, it's also vital to have SSR running in development.

SSR improves the performance and UX and allows you to run server-specific logic, like fetching internal states or accessing databases. SSR in development ensures your app works consistently across development and production, helping identify bugs earlier.

The Challenge

The main challenge of making dev SSR is that, unlike production, development code is addressed to be changed quite often. Whenever you make some changes to your source code, you expect the dev server to grab the changes for the SSR.

In addition, the environments of Node.js and browsers are also different (e.g. you don't have window in Node.js). Libraries might have different builds and logic targeting Node and browsers; frameworks might compile components into different outputs for CSR and SSR. This usually means for client build and SSR build, we need two pipelines for handling the transformation and bundling.

Approach 1: Rebuild

To do SSR, we have to render our app on the Node side. However, Node won't understand TypeScript .ts files we used, nor the Vue SFC .vue. It does not apply our custom configurations like alias and plugins either. A straightforward solution is to bundle our code into plain JavaScript for Node to consume. With the programmatic APIs Vite provided, we can do this:

import { build } from 'vite'

async function buildSSREntry() {
  await build({
    ssr: true,
    // config for Vite
  })
}

Then on the server side, we could import the bundle entry in Node to send the rendered result:

// need to first invalidate the renderer, here we skipped that part
const { default: ssrRenderer } = await import('./dist/entry.mjs')

// render HTML on request
const html = await ssrRenderer(req.url)

To make it reflects user changes, we need to use a filesystem watcher to trigger the rebuild upon each change.

fsWatcher.on('change', async () => {
  // rebuild the entire app in SSR on file change
  // in real-world this will be debounced
  await buildSSREntry()
})

Or instead, we could directly use Vite's Watch mode:

import { build } from 'vite'

function buildSSREntry(watchOptions) {
  build({
    watch: watchOptions,
    // ...
  })
}

It's powered by Rollup's watch mode, which will only re-transform the changed files to output the bundle more efficiently.

This approach is also how we handle the SSR build in Webpack. However, as you can see, Vite's bundleless approach makes the client-side app almost instant in development. The full bundling of SSR has now become the bottleneck of the developer experience.

Approach 2: Dev Bundler

Having the client in dev mode and SSR in the production bundle would inevitably introduce some inconsistencies as they go into different pipelines. To solve it, Pooya Parsa came out with a brilliant idea to use the Vite dev server "constructing" the app in SSR:

import { createViteServer } from 'vite'

const server = createViteServer()

// transform module `id` for SSR
const result = await server.transformRequest(id, { ssr: true })

Vite's dev server provides a method called transformRequest(), which is the same as you requesting a module from the browser but in the programmatic style. The extra { ssr: true } could tell Vite to transform the ESM import/export syntax so it can work without relying on browsers resolving logic.

For example, the following code will be transformed by Vite:

import { ref } from 'vue'

export function foo() {
  return ref(0)
}

into

const __vite_ssr_import_0__ = await __vite_ssr_import__('vue')

function foo() {
  return __vite_ssr_import_0__.ref(0)
}
Object.defineProperty(__vite_ssr_exports__, 'foo', { value: foo })

Oops, that looks quite complex! But no worries, you don't have to understand it. All it does is transform the reserved ESM keywords import / export into function calls. The reason why this is needed is that Vite uses a different module resolution algorithm than Node, it was made for the browser's resolution. Since we can't interop the native ESM's resolving logic directly, transforming them into function calls would allow us to provide our custom resolving logic.

With this API, we can now get the SSR code for each module. Our task now becomes how we could chain them together. In our first proof of concept at nuxt/vite, we implemented our own dev-bundler using the transformRequest(). Here is a simplified example:

const __modules__ = {
  '/foo': () => {
    /* output of transformRequest for `/foo` */
    const __vite_ssr_exports__ = {}
    const bar = await __vite_ssr_import__('/bar')
    // ...
    // return exports
    return __vite_ssr_exports__
  },
  '/bar': () => {
    /* output of transformRequest for `/bar` */
  },
  // ...other modules
}

function __vite_ssr_import__(id) {
  return await __modules__[id]()
}

export default __vite_ssr_import__('/foo')

production code reference

We wrap the transformed modules as functions and store them in an object __modules__ for indexing. Then we can provide a custom import function __vite_ssr_import__ to evaluate the modules we want.

We call this approach Dev Bundler. With it, we don't actually bundle things, but concatenate code transformed by Vite's dev server. We are using the same pipeline and internal cache as the client-side modules, making the SSR build more efficient and consistent with the client build. It then became our approach in Nuxt 3, and works great across our beta period.

But indeed, there are some things we could optimize.

First is that the approach is not really "on-demand". We are transforming all the modules in your app regardless of if it has been used for certain requests. And that makes this approach less "Vite".

Second is the source map support. Since all the modules have been concatenated into a single file and lost the source map, whenever you get an error, the stack trace will show you the error happens in the bundled file instead of the real source. This will hurt the DX as it might make it hard to locate the actual error.

Approach 3: Vite Node

So to address the drawbacks of the Dev Bundler, we need to have the "on-demand" philosophy in mind. Instead of transforming all the modules and then evaluating them, we'd better do it upon the module that has been requested. Then we could use the vm module from Node to this:

import vm from 'node:vm'
import { createDevServer } from 'vite'

const server = createDevServer()

async function importModule(id) {
  // get the transform code on import
  // could be a request if the server is in another thread
  const result = await server.transformRequest(id, { ssr: true })

  // to provide vite ssr utils
  const wrappedCode = `(async function (__vite_ssr_exports__, __vite_ssr_import__) {
   ${result.code}
  })`

  // execute the code to get the function
  const wrappedFn = vm.runInNewContext(wrappedCode, {
    // with the file name we could have better stacktrace
    filename,
  })

  // passing the ssr utils (in wrappedCode)
  return wrappedFn({}, importModule)
}

export default await importModule('/foo')

production code reference

Using the Node vm allows us to execute modules in a safer and isolated context. With inline sourcemap and the filename argument to the runInNewContext, it makes the stacktrace directly point to the correct location of the source file. And most importantly, moving the transform request inside the importing function makes it fully on-demand (caching and sourcemap are simplified in the example).

We ended up extracting this logic into a more general package called vite-node, so it could also be used outside Nuxt.

Not only does vite-node make it on-demand by only requesting modules it needs, but it also makes it possible to control the module cache to provide hot module replacement. We implemented the HMR logic in vite-node, similiar to how Vite handles it on the client side -- making the SSR reloads surprisingly fast.

From a rough testing with a real-world Nuxt 3 app with 15 routes and 7 modules, we see the SSR reload time by changing a single Vue file goes from ~200ms to <0.01ms with vite-node. Since it switched a full build to module level on-demand HMR, the difference will be more significant as the project grows.

Opening Up Possibility

The work on making vite-node not only benefits the Nuxt's dev SSR but also opened up a lot of possibilities for the tooling around Vite. Since vite-node uses Vite for transformaing the modules, it inherits the great power of Vite. Like out-of-box TypeScript and JSX, the powerful plugin API and ecosystem - all that would just work on vite-node same as your client code.

For example, Vitest was only made possible because of the vite-node. It provides the infrastructure to run the tests on Node efficiently with the shared pipeline as your client app consistently. It also made possible to have the HMR support for the tests, making the test-driven development experience much better.

In addition, vite-node powers Histoire, a interactive component playgrounds for Vite. vue-termui, a terminal UI framework for Vue, is using vite-node to do developement HMR.

We are happy to see our work on Nuxt inspires and pushes the Vite ecosystem for more innovations and better tools. We are also eager to see what is comming next for the tools and integrations that built with "on-demand" philosophy in mind, providing better performance and developer experience.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/why-not-prettier https://antfu.me/posts/why-not-prettier Sat, 01 Oct 2022 00:00:00 GMT [[toc]]

中文 Chinese Version

I have started writing this post multiple times but never ended up posting it. I wasn't able to figure out a proper way to express my position about Prettier. But this time, I think I should try harder to explain that for future reference.

First of all, I am not against Prettier. Actually, I love it.

I Love Prettier

Prettier is a great tool, and it saved me a lot of time. I appreciated the efforts of the maintainers and contributors to make it possible and formed a great foundation of how the clean code would look for the community. I have to confess that the title is a bit clickbait. I use Prettier a lot for interactive documentation and playgrounds, like VueUse and UnoCSS. I love it for the out-of-box support of a lot of languages. I could make the generated code pretty with less than 5 mins of integrating Prettier.

But, Why Not?

If you have ever come across my open source projects, you might find that I rarely use Prettier to format the source code. In this post, I would try to explain the reason why I made this decision:

It's Opinionated

Prettier describes itself to be "an opinionated code formatter".

Opinionated essentially means it's not for everyone. Prettier makes a lot of hard-coded decisions to provide a minimal configuration interface. That makes it very easy to use (it's excellent!) and the code consistent across projects. However, on the other hand, it also means you are losing the ability to have fine-grained tweaks to how your code should look like.

While I love most of Prettier's decisions, it sometimes makes you upset when you find something you don't want and don't have a workaround.

The Line Wrapping Noise

The main thing that itches me a lot is the auto wrapping / unwrapping based on the length of the code. Prettier has the concept of printWidth, which constrains each line to fit with a certain width (by default, it's 80 characters). It's generally great to have the code fitting in one screen and avoid horizontal scrolls.

However, I often found it hurting the readability and git diffing.

@patak_dev recently brought up an example of that in PR reviewing:

Formatters are awesome, especially when doing PR reviews. They also introduce issues though, for example when an addition triggers a line break. The diff isn't showing what changed here. It would be great if diff viewers would be Prettier-aware, counting line breaks as spacing. pic.twitter.com/ZuApmctllU

— patak (@patak_dev) September 30, 2022

Sometimes when you modify a string literal in JavaScript that may make the line a bit longer than the value of printwidth, Prettier will force wrapping the line. It breaks the inline diffing and make the changes hard to review. Imagine in another pull request, we might reduce the string a bit shorter, Prettier will then unwrap the lines back to one line. Back and forth, it creates a lot of unnecessary noises.

The following image shows another example:

^{The 42 of printWidth is made up for demonstration, but it happens in any printWidth}

On the left is the input code and on the right is the output of Prettier. I don't need to point out but you probably already have the answer of which one is "more pretty". From my point of view, Prettier follows the rule too strict. And in fact it makes the code much harder to read and modify, violating the initial goal of formatting - to make the code more readable.

The real pain point is that this behavior is not optional. You can't disable it completely(#3468). Increasing the printWidth only delays the circumstance and will affect other files that you didn't touch. The only workaround you can do is to use // prettier-ignore, which to me, the "all or nothing" choice loses the point of using Prettier in the first place.

Mess with ESLint

Prettier as a code formatter, only cares about code styles but not the logic. Thus we see it's quite common for projects to use ESLint along with Prettier to also check the logic. If you have ever configured that yourself, you might notice there are some functionality overlaps between them - ESLint can also lint for code styles. The common practice is to use eslint-config-prettier to disable those overlaps rules in ESLint (there are also a few other solutions).

However, the approach creates quite a lot of mess to me:

My points here:

1. Prettier Only is cool - It's out-of-box.
2. If you need to use ESLint, it can do the formatting as good as Prettier - and more configurable

— Anthony Fu (@antfu7) July 3, 2020

3. Prettier + ESLint still needs a lot of configs - It doesn't make your life easier.
4. You can have full control in ESLint but not in Prettier, mixing them together feels weird.
5. I don't think parsing two times can be faster (maybe I am wrong)

— Anthony Fu (@antfu7) July 3, 2020

ESLint's auto fix could also do the formatting just as well as Prettier - with much more freedom of choices.

Alternatives

ESLint is essential to my workflow to ensure the code quality. If ESLint is already capable of doing formatting, the best solution for me is to use it in one go.

I spent some time configuring my ESLint and made it a config preset:

It turns out, the setup configuration can also be very minimal:

npm i -D @antfu/eslint-config

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu({
  // customizations
})

That's all you need. With the IDE extensions, it's also possible to trigger auto fixing on save. It works similarly to Prettier but respects your choices when to break the lines, with many best practices of linting. It's also quite opinionated, but thanks to the new Flat Config, it gives you the full control of customizations over every single bit that you want to change. Moreover, you can always fork it to make your own versions.

Sidenote: You might hear so voicing saying "Don't use ESLint for formatting" - here are some discussions and a response from the ESLint team, for you to make your own judgement.

Wrapping Up

This post is only trying to explain my personal experience and opinions. Of course, you can have different views and don't need to agree with me at all. I am not blaming Prettier for this. Different tools have different purposes and focuses, and there is no better or worse. It's just about using the right tools for the right circumstances. I will still be a happy user of Prettier in usages that I don't need the maximum customizability, and using ESLint exclusively for my projects' source code.

Hope this could make myself clear and maybe give you some insights. Cheers!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/why-reproductions-are-required https://antfu.me/posts/why-reproductions-are-required Mon, 30 May 2022 16:00:00 GMT [[toc]]

中文 Chinese Version

If you have ever browsed the issue lists in my repos or created one, you might sometimes see I reply with the following comment and then close the issue:

I'd first say sorry if it ever makes you feel unpleasant. In this post, let me try to explain the reason behind it.

Open Source Software is served "as-is"

First of all, let's reach a consensus about Open Source Software(OSS). If you look into the MIT License, one of the most popular licenses, you will see it contains the following statement:

The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.

"As is" stands that you are free to use the code, fork it, or modify it as you want with the current state. Meaning the authors are not responsible to fix or improve anything you might have now or in the future. Since it's free and open source, the authors or maintainers gain nothing regardless if you use it or not. There is no such thing as 24-7 customer service. Theoretically, you as a user of open source code, should be responsible to the code you use.

Yeah, that sounds scary. But luckily, things are not that bad in real practice. In many open source projects, we build trust between users and maintainers. Users contribute to projects by reporting issues they faced, or sharing solutions via discussions and pull requests. Maintainers spend their time reviewing, making decisions, managing releases, and doing distributions. Both users and maintainers work voluntarily toward the same wish - to make the software better, for everyone.

Maintainance takes effort, a lot

Software once written, is never finished. Maintainance plays a crucial role to keep a project "alive", getting bug or security fixes on time, and being sustainable in the long run. Things like triaging issues, reviewing PRs, and discussions could take a lot of effort from maintainers. While in open source projects, the ratios of user-to-maintainer are commonly unbalanced. Many popular projects might only have one or two maintainers behind the scene. As a project grows and gains more users, the number of tasks required to maintain the project may easily go beyond one’s capacity.

Why Reproduction

A good minimal reproduction of a potential issue could greatly help maintainers to identify the root cause and land the fix quickly. Without a minimal reproduction, merely from the issue description or a screenshot, maintainers won't even know whether it's a real issue of the project or it's caused by some other factors. To identify that, maintainers might need to spend extra time to find a reproduction themselves, or dive into the giant project people shared as a "non-minimal reproduction". Hours might be spent, but what if it turns out a non-issue or unreproducible? What if there are hundreds of such issues you need to deal with?

In my opinion, asking for minimal reproduction is asking for equity of the effort spent. If everyone could take some time to create a minimal reproduction before opening issues, it would save maintainers hundreds of hours (or even help themselves to find user-land solutions/mistakes, then they don't even need to create the issue). A well-investigated and well-explained issue would also make maintainers more willing to spend their time and effort in return.

I'd say "The best reproductions are the reproductions never sent" - because you've already found the solutions and solved them during the process of trying to reproduce those issues, without need to submit and wait for responses from maintainers. You're effort gets paid off in a much better way.

How to Create a Minimal Reproduction

Failing Test Cases

If you are a developer and familiar with the testing process. The best reproductions are pull requests that add failing test cases. This approach doesn't just highlight the problem, but also clearly depicts the expected behavior. Leveraging the Continuous Integration (CI) system, it also allows verifying the fix upon landing and provides a safeguard against future regressions.

To proceed with this method, initiate by cloning the project's source code and setting up the development environment. Then, create a new branch and navigate to the test folder to introduce a failing test case that mirrors the discrepancy you've observed. Upon successfully making the new test fail -- indicating the bug -- commit the changes, then establish a pull request detailing the issue in its description.

Here are some real world examples:

• vuejs/language-tools #2113
  1. PR created by adding failing test
  2. The maintainer later pushed a fix to make the test pass
  3. PR gets merged, and the tests get improved to cover more cases
• unjs/magicast #62
  1. PR created by adding failing test
  2. The maintainer later pushed a fix to make the test pass
  3. PR gets merged with the improved test case

Please note that this method may not always applicable. If the bug is not been able to be reproduced with a test case, you can try to create a repository reproductions instead, as described below.

Reproducible Projects or Playgrounds

This section is ported from Please include a repro by Rich Harris. Also recommand watching a more detailed explanation by Rich Harris.

In some cases, there will be a project-specific way to demonstrate problems – for example, Rollup, Svelte and Vue all have dedicated REPLs. Use them!

Often, it's not possible to illustrate the problem with a REPL. Here's what you do:

1. Create a sample repo on GitHub or Stackblitz (or wherever)
2. Demonstrate the problem, and nothing but the problem. Whittle it down to the bare minimum of code that reliably demonstrates the issue. Get rid of any dependencies that aren't directly related to the problem.
3. Install all your dependencies to package.json. If the maintainer can't clone the repo and do npm install && npm run build (or similar – see point 4) to see the problem, because the maintainer needs some globally installed CLI tool or whatever, that would make it harder to get to the bottom of the issue.
4. Include instructions in the repo, along with a description of the expected and actual behaviour. Obviously the issue should include information about the bug as well, but it's really helpful if README.md includes that information, plus a link back to the issue. If there are any instructions beyond npm install && npm run build, they should go here.

Wrapping Up

As a maintainer, I appreciate all the issues and pull requests opened. And I believe it's true that some of the issues we closed without reproduction might still have real bugs that need to be fixed. But to not be overwhelmed by the notifications, maintainers need to set the priorities for handling the tasks. Keeping the number of issues in a manageable manner is one of the ways to keep the project healthy in the long run.

I believe open source is about building great stuff together, not solely on maintainers' shoulders. Wish we could make a better and healthier community together. Thanks for reading :)

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/introduction-to-vitest-vue-nation-2022 https://antfu.me/posts/introduction-to-vitest-vue-nation-2022 Wed, 26 Jan 2022 08:00:00 GMT

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/publish-esm-and-cjs https://antfu.me/posts/publish-esm-and-cjs Mon, 29 Nov 2021 16:00:00 GMT [[toc]]

ESM & CJS

• ESM - ECMAScript modules
• CJS - CommonJS

In the past decade, due to the lack of a standard module system of JavaScript, CommonJS (a.k.a the require('xxx') and module.exports syntax) has been the way how Node.js and NPM packages work. Until 2015, when ECMAScript modules finally show up as the standard solution, the community start migrating to native ESM gradually.

// CJS
const circle = require('./circle.js')

console.log(`The area of a circle of radius 4 is ${circle.area(4)}`)

// ESM
import { area } from './circle.mjs'

console.log(`The area of a circle of radius 4 is ${area(4)}`)

ESM enables named exports, better static analysis, tree-shaking, browsers native support, and most importantly, as a standard, it's basically the future of JavaScript.

Experimental support of native ESM is introduced in Node.js v12, and stabilized in v12.22.0 and v14.17.0. As the end of 2021, many packages now ship in pure-ESM format, or CJS and ESM dual formats; meta-frameworks like Nuxt 3 and SvelteKit are now recommending users to use ESM-first environment.

The overall migration of the ecosystem is still in progress, for most library authors, shipping dual formats is a safer and smoother way to have the goods from both worlds. In the rest of this blog post, I will show you why and how.

Compatibility

If ESM is the better and the future, why don't we all move to ESM then? Even though Node.js is smart enough to allow CJS and ESM packages to work together, the main blocker is that you can't use ESM packages in CJS.

If you do:

// in CJS
const pkg = require('esm-only-package')

you will receive the following error

Error [ERR_REQUIRE_ESM]: require() of ES Module esm-only-package not supported.

The root cause is that ESM is asynchronous by nature, meaning you can't import an async module in synchronous context that require is for. This commonly means if you want to use ESM packages, you have to use ESM as well. Only one exception is that you can use ESM package in CJS using dynamic import():

// in CJS
const { default: pkg } = await import('esm-only-package')

Since dynamic import will return a Promise, meaning all the sub-sequential callee need to be async as well (so call Red Functions, or I prefer call it Async Infection). In some case it might work, but generally I won't think this to be an easy approachable solution for users.

On the other hand, if you are able to go with ESM directly, it would be much easier as import supports both ESM and CJS.

import cjs from 'cjs-package'
// in ESM
import { named } from 'esm-package'

Some packages now ship pure-ESM packages advocating the ecosystem to move from CJS to ESM. While this might be the "right thing to do", however, giving the fact that that majority of the ecosystem are still on CJS and the migration is not that easy, I found myself more lean to ship both CJS and ESM formats to make the transition smoother.

package.json

Luckily, Node allows you to have those two formats in a single package at the same time. With the new exports field in package.json, you can now specify multiple entries to provide those formats conditionally. Node will resolve to the version based on user's or downstream packages environment.

{
  "name": "my-cool-package",
  "exports": {
    ".": {
      "require": "./index.cjs", // CJS
      "import": "./index.mjs" // ESM
    }
  }
}

Bundling

So now we have two copies of code with slightly different module syntax to maintain, duplicating them is of course not an ideal solution. At this point you might need to consider introducing some build tools or bundling process to build your code into multiple formats. This might remind you the nightmare of configuring complex Webpack or Rollup, well don't worry, my mission today is to introduce you two awesome tools that make your life so much easier.

• tsup
• unbuild

tsup

tsup by @egoist is one of my most used tools. The features zero-config building for TypeScript project. The usage is like:

$ tsup src/index.ts

And then you will have dist/index.js file ready for you to publish.

To support dual formats, it's just a flag away:

$ tsup src/index.ts --format cjs,esm

Two files dist/index.js and dist/index.mjs will be generated with it and you are good to go. Powered by esbuild, tsup is not only super easy to use but also incredible fast. I highly recommend to give it a try.

Here is my go-to template of package.json using tsup:

{
  "name": "my-cool-package",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
    "watch": "npm run build -- --watch src",
    "prepublishOnly": "npm run build"
  }
}

unbuild

If we say tsup is a minimal bundler for TypeScript, unbuild by the @unjs org is a more generalized, customizable and yet powerful. unbuild is being used to bundle Nuxt 3 and it's sub packages.

To use it, we create build.config.ts file in the root

// build.config.ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: [
    './src/index'
  ],
  declaration: true, // generate .d.ts files
})

and run the unbuild command:

$ unbuild

unbuild will generate both ESM and CJS for you by default!

Stubbing

This is one of the most incredible things that I have found when I first looked into Nuxt 3's codebase. unbuild introduced a new idea called Stubbing. Instead of firing up a watcher to re-trigger the bundling every time you made changes to the source code, the stubbing in unbuild (so call Passive watcher) does not require you are have another process for that at all. By calling the following command only once:

$ unbuild --stub

You are able to play and test out with your library with the up-to-date code!

Want to know the magic? After running the stubbing command, you can check out the generated distribution files:

// dist/index.mjs
import jiti from 'jiti'

export default jiti(null, { interopDefault: true })('/Users/antfu/unbuild-test/src/index')

// dist/index.cjs
module.exports = require('jiti')(null, { interopDefault: true })('/Users/antfu/unbuild-test/src/index')

Instead of the distribution of your code bundle, the dist files are now redirecting to your source code with a wrap of jiti - another treasure hidden in the @unjs org. jiti provides the runtime support of TypeScript, ESM for Node by transpiling the modules on the fly. Since it directly goes to your source files, there won't be a misalignment between your source code and bundle dist - thus there is no watcher process needed! This is a huge DX bump for library authors, if you still not getting it, you shall definitely grab it down and play with it yourself.

Bundleless Build

Powered by mkdist - another @unjs package - unbuild also handles static assets and file-to-file transpiling. Bundleless build allows you to keep the structure of your source code, made easy for importing submodules on-demand to optimizing performance and more.

Config in unbuild will look like:

// build.config.ts
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: [
    // bundling
    'src/index',
    // bundleless, or just copy assets
    { input: 'src/components/', outDir: 'dist/components' },
  ],
  declaration: true,
})

One of the coolest features on this is that it handles .vue file out-of-box. For example, if I have a component MyComponent.vue under src/components with following content:

<!-- src/components/MyComponent.vue -->
<template>
  <div>{{ count }}</div>
</template>

<script lang="ts">
  const count: number | string = 0

  export default {
    data: () => ({ count }),
  }
</script>

Notice that we are using TypeScript in the Vue file, when we do the build, the component will be copied over but with the TypeScript annotation removed along with a MyComponent.vue.d.ts generated.

<!-- dist/components/MyComponent.vue -->
<template>
  <div>{{ count }}</div>
</template>

<script>
  const count = 0
  export default {
    data: () => ({ count }),
  }
</script>

// dist/components/MyComponent.vue.d.ts
declare const _default: {
  data: () => {
    count: number | string
  }
}
export default _default

This way this allows you to use TypeScript in development while not requiring consumers to also have TypeScript in their setup.

P.S. unbuild is working on providing better out-of-box experience by auto infering the entries in package.json, learn more.

Context Misalignment

With either of the tools mentioned above, now we are able to write TypeScript as the single source of truth and made the overall codebase easier to maintain. However, there are still some caveats that you will need to keep an eye on it.

In ESM, there is NO __dirname, __filename, require, require.resolve. Instead, you will need to use import.meta.url and also do some convertion to get the file path string.

So since our code will be compiled to both CJS and ESM, it's better to avoiding using those environment specific context whenever possible. If you do need them, you can refer to my note about Isomorphic __dirname:

import { dirname } from 'node:path'
import { fileURLToPath } from 'node:url'

const _dirname = typeof __dirname !== 'undefined'
  ? __dirname
  : dirname(fileURLToPath(import.meta.url))

For require and require.resolve, you can use

import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

Some good news, if you are using unbuild, you can turn on the cjsBridge flag and unbuild will shims those CJS context in ESM automatically for you!.

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  cjsBridge: true, // <--
})

On the other hand, if you are using tsup, it will shims ESM's import.meta.url for you in CJS instead.

Verify your Packages

Once your published your package, you can verify if it follows the best practices using publint.dev made by @bluwy. It will also give you suggestions of how to improve them further.

Final words

This blog post showcased you only a few features of both tools. Do check their docs for more details. And hope you find these setups useful for building your own libraries. If you have any comments or suggestions, ping me on Twitter @antfu7. Happy hacking!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/icons-in-pure-css https://antfu.me/posts/icons-in-pure-css Sun, 31 Oct 2021 16:00:00 GMT [[toc]]

中文 Chinese Version

In my previous post about Reimagine Atomic CSS, I introduced a preset of UnoCSS that provides the ability to use any icons on-demand in purely CSS. Today in this post, I'd like to share with you how we made it possible.

My Icon Explorations

If you are interested in how I get here, there is an index of my previous post about the stories of my icon explorations and experiments.

• Aug. 2020 - Journey with Icons
• Sep. 2021 - Journey with Icons Continues
• Oct. 2021 - Reimagine Atomic CSS (The CSS Icons Preset)
• Nov. 2021 - Icons in Pure CSS - you are here!

Prior Arts

I know there is a Pure CSS icon solution called css.gg, which is a great idea to use pseudo-elements (::before, ::after) to construct the icons. However, that could require some expert knowledge of how CSS works, but I imagine that approach could be hard to create more complex icons. Instead of the limited choices in a specific set, I am seeking a more general solution that could apply to any icons.

The Idea

The idea come from this feature request created by @husayt to unplugin-icons and the initial implementation in this pull request by @userquin. The idea here is quite straightforward - to generate CSS with the icons in DataURI as the background image.

.my-icon {
  background: url(data:...) no-repeat center;
  background-color: transparent;
  background-size: 16px 16px;
  height: 16px;
  width: 16px;
  display: inline-block;
}

With that, we could use any images inlined in CSS with a single class.

<div class="my-icon"></div>

It's indeed an interesting idea. However, this is more like an image instead of an icon. To me, an icon has to be scalable and colorable (if it's monochrome).

Make it Work

DataURI

Thanks again to Iconify, which unified 100+ icon sets with 10,000+ icons into the consistent JSON format. It allows us to get the SVG of any icon set by simply providing the collection and icon ids. The usage is like this:

import { getIconData, iconToSVG } from '@iconify/utils'

const svg = iconToSVG(getIconData('mdi', 'alarm'))
// (this is not the exact API, simplified here for demo)

Once we got the SVG string, we could convert the it to DataURI:

const dataUri = `data:image/svg+xml;base64,${Buffer.from(svg).toString('base64')}`

Talking about DataURI, it's almost the default choice to use Base64 until I read Probably Don't Base64 SVG by Chris Coyier. Base64 is needed to encode binary data like images to be used in plain text files like CSS, while for SVG, since it's already in text format, the extra encoding to Base64 actually makes the file size larger.

Combine the technique mentioned in Optimizing SVGs in data URIs by Taylor Hunt to improve the output size, further, here is the solution we end up with.

// https://bl.ocks.org/jennyknuth/222825e315d45a738ed9d6e04c7a88d0
function encodeSvg(svg: string) {
  return svg.replace('<svg', (~svg.indexOf('xmlns') ? '<svg' : '<svg xmlns="http://www.w3.org/2000/svg"'))
    .replace(/"/g, '\'')
    .replace(/%/g, '%25')
    .replace(/#/g, '%23')
    .replace(/\{/g, '%7B')
    .replace(/\}/g, '%7D')
    .replace(/</g, '%3C')
    .replace(/>/g, '%3E')
}

const dataUri = `data:image/svg+xml;utf8,${encodeSvg(svg)}`

Scalable

The first step of making the "image" more like an icon, we need to make it scalable to the context.

Luckily we have the first-class support scaling support - the em unit.

.my-icon {
  background: url(data:...) no-repeat center;
  background-color: transparent;
  background-size: 100% 100%;
  height: 1em;
  width: 1em;
}

By changing the height and width to 1em, and the background-size to 100%, we made the image scales based on the parent's font size.

• Small
• Normal
• Large

Colorable

In inlined SVG, we could use fill="currentColor" to make the color of the SVG matches with the current text color. However, when we use it as a background image, it becomes a flat image. The dynamic parts of the SVG are lost, so is the currentColor magic (it's just like you can't override the color of a PNG).

If you do a quick search, you will find that most people are telling you that you can't. Some might offer you the option to assign the colors in the SVG before converting to DataURI, which could solve the specific problem that you want the icon to have color, but not the root cause that the color is not reactive to the context.

Then you might come up with the idea of using CSS filters, like Una Kravets mentioned in Solved with CSS! Colorizing SVG Backgrounds. That sounds valid, but only that you need to calculate the matrix of how to transform the color to the desired ones. Probably feasible by introducing some runtime JavaScript for that? Maybe, if so, we lost the whole point of trying icons in pure CSS.

This sounds like a dead-end to me. Until I accidentally found the article Coloring SVGs in CSS Background Images by Noah Blon. In the article, Noah mentioned a brilliant idea of using CSS masks - a property that I have never heard of before.

.my-icon {
  background-color: red;
  mask-image: url(icon.svg);
}

Instead of using the icon as a background image and figuring out a way to color it, we could actually use the icon as a mask to clip the filled background color. Furthermore, we could now use the currentColor magic to have the icon matching with the parent text color!

.my-icon {
  background-color: currentColor;
  mask-image: url(icon.svg);
}

This is a blue text, with the blue icon

Green

Orange

Icons with Colors

We made the monochrome icons colorable but now it problem comes to the icons with colors. With the mask approach, the colors and content of the icons got lost, for example:

Icon:

Masked:

Yes, I might say it's hard for one approach to cover all the cases.

Unless - you could blend two approaches into one! Remember we just talked about the background image approach serving the icons as images? Isn't that just what we want for colored icons? - We don't need to change the colors after all!

So the solution is actually pretty simple, we just need to find a way to distinguish the monochrome and colored icons smartly. Luckily, since we had access the the SVG content, we could have:

// if an SVG icon have the `currentColor` value,
// it's very likely to be a monochrome icon
const mode = svg.includes('currentColor')
  ? 'mask'
  : 'background-img'

const uri = `url("data:image/svg+xml;utf8,${encodeSvg(svg)}")`

// monochrome
if (mode === 'mask') {
  return {
    'mask': `${uri} no-repeat`,
    'mask-size': '100% 100%',
    'background-color': 'currentColor',
    'height': '1em',
    'width': '1em',
  }
}
// colored
else {
  return {
    'background': `${uri} no-repeat`,
    'background-size': '100% 100%',
    'background-color': 'transparent',
    'height': '1em',
    'width': '1em',
  }
}

And it works surprisingly well! You know, it's now behavior similar to the thing we are using daily - system's native emojis. The color of texts changes based on the context, while emojis stay the colors of their own.

Here are some showcases of what we end up with:

Material Design

Carbon

Tabler

Twemoji

Logos

To see and find all the icons available, you can check out my other project Icônes.

Use It

If you want to try this icons solution in your project, you can install UnoCSS and the icons preset:

npm i -D unocss @unocss/preset-icons @iconify/json

@iconify/json is the package that stores the icon data from Iconify. Alternatively, you could install per icon set, for example, @iconify-json/mdi for Material Design Icons or @iconify-json/carbon for Carbon Icons and so on.

Then in your vite.config.js

import UnocssIcons from '@unocss/preset-icons'
import UnoCSS from 'unocss'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      // when `presets` is specified, the default preset will be disabled
      // so you could only use the pure CSS icons in addition to your
      // existing app without polluting other CSS
      presets: [
        UnocssIcons({
          // options
          prefix: 'i-',
          extraProperties: {
            display: 'inline-block'
          }
        }),
        // presetUno() - if you want to use other atomic CSS as well
      ],
    }),
  ],
})

And that's it for today. Hope you enjoy this icons solution from UnoCSS, or get some inspiration from it for your own projects.

Thanks for reading, and see you :)

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/reimagine-atomic-css https://antfu.me/posts/reimagine-atomic-css Tue, 26 Oct 2021 16:00:00 GMT [[toc]]

This post will be a bit longer than usual. It's quite a big announcement to me, and there are many things I want to talk about. I'll be appreciated if you take the time to read through it. The table of contents is hidden on the left if you are on a desktop. Hope you enjoy :)

中文 Chinese Version

What is Atomic CSS?

Let's first give a proper definition to Atomic CSS:

From this article by John Polacek:

Atomic CSS is the approach to CSS architecture that favors small, single-purpose classes with names based on visual function.

Some might also call it Functional CSS, or CSS utilities. Basically, you can say an Atomic CSS framework is a collection of the CSS like these:

.m-0 {
  margin: 0;
}
.text-red {
  color: red;
}
/* ... */

We have quite a few utilities-first CSS framework like Tailwind CSS, Windi CSS and Tachyons, etc. And there are also some UI libraries that come with some CSS utilities as the complement to the framework, for example Bootstrap and Chakra UI.

We are not going to talk about the pros and cons of using atomic CSS here, as you might hear them many times already. Today, we are going to use a framework author's perspective to see how we make the trade-off building those frameworks you love, their limitations, what we can do better to eventually benefits your daily work.

The Background

Before we start, let's talk a bit about the background. If you don't know me, my name is Anthony Fu, and I am a Vite team member and the creator of Vitesse, one of the most popular starter templates for Vite. I enjoy the speedy development experience of atomic CSS (or CSS utilities), so I chose to use Tailwind CSS as the default UI framework for Vitesse. While Vite should be incredibly fast compared to Webpack and others, Tailwind, which generates megabytes of utility CSS, makes the start-up and HMR on Vite slow as the old days. I once thought this was some kind of trade-off for using atomic CSS solutions - until I discovered Windi CSS.

Windi CSS was a Tailwind CSS alternative that was written from scratch. It has zero dependencies and does not rely on PostCSS and Autoprefixer. More importantly, it features on-demanded usage. Instead of generating all the combinations of utilities that you rarely used to purge later, Windi CSS only generates those actually presented in your codebase. This fits perfectly well with Vite's on-demanded philosophy, and theoretically, it should be way much faster than Tailwind. So I wrote the Vite plugin for it, and it turned out to be 20~100x faster than Tailwind.

It went pretty well, Windi CSS grown into a team, we made many more innovations like Value Infering, Variant Groups, Shortcuts, Design in DevTools, Attributify Mode, etc. As the result, Tailwind was ass kicked to introduce their own on-demand JIT engine.

Breakdown Atomic CSS

Back to the topic, let's take a look at how atomic CSS works first.

Traditional Way

The traditional way of making Atomic CSS is to provide all the CSS utilities you might possibly want, for example, here is something you could generate your own with a preprocessor (SCSS in this case):

// style.scss

@for $i from 1 through 10 {
  .m-#{$i} {
    margin: $i / 4 rem;
  }
}

It will be compiled to:

.m-1 { margin: 0.25 rem; }
.m-2 { margin: 0.5 rem; }
/* ... */
.m-10 { margin: 2.5 rem; }

Great, now you can use class="m-1" to set the margin. But as you might see, with this approach, you can't set the margin outside of 1 to 10, and also, you need to pay the cost of shipping 10 CSS rules even if you have only used one. Later if you want to support different margin directions like mt for margin-top, mb for margin-bottom. With those 4 directions, you are multiplying your CSS size by 5. Then when it comes to variants like hover: and focus: - you know the story. At that point, adding one more utility often means you are going to introduce a few extra kilobytes. Thus, this is also why the traditional Tailwind ships megabytes of CSS.

To solve this, Tailwind came up with the solution by using PurgeCSS to scan your dist bundle and remove the rules you don't need. Now you have only a few KBs of CSS in production. However, note that the purging would only work in the production build, meaning you are still working with the tremendous CSS in development. It wasn't that prominent in Webpack, but it becomes a pain in Vite, given the rest are now coming blazing fast.

While generating and purging approach have its limitations, could we have a better solution?

On-demand Way

The "on-demand" idea introduces a brand new way of thinking. Let's make a comparison of the approaches here.

The traditional way not only costs you unnecessary computation (generated but not in use) but is also unable to satisfy your needs that are not included in the first place.

By flipping the order of "generating" and "usage scanning", the "on-demand" approach saves you the wasted computational and transferring cost, while being flexible to provide the dynamic needs that pre-generating can't possibly be covered. Meanwhile, this approach could be used in both development and production, provide more confidence about the consistency and make HMR more efficient.

To achieve this, both Windi CSS and Tailwind JIT take the approach of pre-scanning your source code. Here is a simple example of that:

import { promises as fs } from 'node:fs'
import glob from 'fast-glob'

// this usually comes from user config
const include = ['src/**/*.{jsx,tsx,vue,html}']

async function scan() {
  const files = await glob(include)

  for (const file of files) {
    const content = await fs.readFile(file, 'utf8')
    // pass the content to the generator and match for class usages
  }
}

await scan()
// scanning is done before the build / dev process
await buildOrStartDevServer()

To provide HMR during development, a file watcher is usually needed:

import chokidar from 'chokidar'

chokidar.watch(include).on('change', (event, path) => {
  // read the file again
  const content = await fs.readFile(file, 'utf8')
  // pass the content to the generator again
  // invalidate the css module and send HMR event
})

As a result, with the on-demand approach, Windi CSS is able to provide about 100x faster performance than the traditional Tailwind CSS.

The Itches

I am now using Windi CSS on almost all my apps, and it works pretty well. The performance is sweet, and the HMR is unnoticeable. Value Auto Infering and Attributify Mode makes my development even faster. I could really take a good sleep and dream about other things then. However, it sometimes itches me from my sweet dream.

The one I found annoying is the unclearness of what I am getting and what to do to make it work. To me, the best ideally atomic CSS should be invisible. Once learned, it should be intuitive and analogous to know the others. It's invisible when it works as you expect and could become frustrating when it doesn't.

For example, you know that in Tailwind's border-2 means 2px of border width, 4 for 4px, 6 for 6px, 8 for 8px, but guess what, border-10 does NOT work (it could also take your time to figure it out!). You might say this is designed on purpose by Tailwind to make the design system consistent and limited. Ok fine, but here is a quick quiz, let's say if you want border-10 to work, how would you do that?

Write your own utility somewhere in your global styles?

.border-10 {
  border-width: 10px;
}

That's pretty fast and straightforward. And importantly, it works. But honestly, if I need to do this manually myself, why would I need Tailwind in the first place?

If you know Tailwind a bit more, you might know it can be configured. So you spend 5 minutes searching for their docs, here is what you end up with:

// tailwind.config.js
module.exports = {
  theme: {
    borderWidth: {
      DEFAULT: '1px',
      0: '0',
      2: '2px',
      3: '3px',
      4: '4px',
      6: '6px',
      8: '8px',
      10: '10px' // <-- here
    }
  }
}

Ah, fair enough, now we could list them all and get back to work... wait, where was I? The original task you are working on gets lost, and it takes time to get back to the context again. Later on, if we want to set border colors, we'd need to look up the docs again to see how it could be configured and so on. Maybe someone would enjoy this workflow, but it's not for me. I don't enjoy being interrupted by something that should intuitively work.

Windi CSS is more relaxed to the rules and will try to provide the corresponding utilities whenever possible. In the previous case, border-10 will work out-of-box on Windi (thank you!). But due to the fact that Windi is compatible with Tailwind, it also has to use the exact same configuration interface as Tailwind. While the number inferring works in Windi, it would still be a nightmare if you want to add custom utilities. Here is an example from Tailwind's docs:

// tailwind.config.js
const _ = require('lodash')
const plugin = require('tailwindcss/plugin')

module.exports = {
  theme: {
    rotate: {
      '1/4': '90deg',
      '1/2': '180deg',
      '3/4': '270deg',
    }
  },
  plugins: [
    plugin(({ addUtilities, theme, e }) => {
      const rotateUtilities = _.map(theme('rotate'), (value, key) => {
        return {
          [`.${e(`rotate-${key}`)}`]: {
            transform: `rotate(${value})`
          }
        }
      })

      addUtilities(rotateUtilities)
    })
  ]
}

That alone is to generate these:

.rotate-1\/4 {
  transform: rotate(90deg);
}
.rotate-1\/2 {
  transform: rotate(180deg);
}
.rotate-3\/4 {
  transform: rotate(270deg);
}

The code to generate the CSS is even longer than the outcome. It could be hard to read and maintain, and meanwhile, it breaks the on-demand ability.

Tailwind's API and plugin system is designed with the traditional mindset and does not really match the new on-demand approach. Core utilities are baked in the generator, and the customization is quite limited. So, I started wondering if we could abandon those debts and redesign it ground-up with the on-demand approach in mind, what would we get?

Introducing UnoCSS

UnoCSS - the instant atomic CSS engine with maximum performance and flexibility.

It started with some random experiments during my national holiday. With the mind of on-demand and the flexibility that I would expect as a user, the experiments turned out to be very good to me in many ways.

The Engine

UnoCSS is an engine instead of a framework because there are no core utilities - all the functionalities are provided via presets or inline configurations.

We are imagining UnoCSS being able to simulate the functionalities of most of the existing atomic CSS frameworks. And possibly have been used as the engine to create some new atomic CSS frameworks! For example:

import PresetAntfu from '@antfu/oh-my-cool-unocss-preset'

import PresetBootstrap from '@unocss/preset-bootstrap'
// the following presets do not exist at this moment,
// contribution welcome!
import PresetTachyons from '@unocss/preset-tachyons'
import PresetTailwind from '@unocss/preset-tailwind'
import PresetWindi from '@unocss/preset-windi'
import UnocssPlugin from '@unocss/vite'

export default {
  plugins: [
    UnocssPlugin({
      presets: [
        // PresetTachyons,
        PresetBootstrap,
        // PresetTailwind,
        // PresetWindi,
        // PresetAntfu

        // pick one... or multiple!
      ]
    })
  ]
}

Let's take a look at how it made them possible:

Intuitive & Fully Customizable

The main goals of UnoCSS are intuitiveness and customization. It allows you to define your own utilities literally in seconds.

Here is a quick guide through:

Static Rules

Atomic CSS might come huge in terms of the amount. It's important to have the rules definition straightforward and easy to read. To create a custom rule for UnoCSS, you can write it as follows:

rules: [
  ['m-1', { margin: '0.25rem' }]
]

Whenever m-1 is detected in users' codebase, the following CSS will be generated:

.m-1 { margin: 0.25rem; }

Dynamic Rules

To make it dynamic, change the matcher to a RegExp and the body to a function:

rules: [
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
  [/^p-(\d+)$/, match => ({ padding: `${match[1] / 4}rem` })],
]

The first argument of the body function is the match result, so you can destructure it to get the RegExp matched groups.

For example, with the usage:

<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    My Button
  </button>
</div>

the corresponding CSS will be generated:

.m-100 { margin: 25rem; }
.m-3 { margin: 0.75rem; }
.p-5 { padding: 1.25rem; }

That's it. You only need to add more utilities using the same pattern, and now you got your own atomic CSS running!

Variants

Variants in UnoCSS are also simple yet powerful. Here are a few examples:

variants: [
  // support `hover:` for all rules
  {
    match: s => s.startsWith('hover:') ? s.slice(6) : null,
    selector: s => `${s}:hover`,
  },
  // support `!` prefix to make the rule important
  {
    match: s => s.startsWith('!') ? s.slice(1) : null,
    rewrite: (entries) => {
      // append ` !important` to all css values
      entries.forEach(e => e[1] += ' !important')
      return entries
    },
  }
]

The configurations of variants could be a bit advanced. Due to the length of the post, I will skip the detailed explanation here, you can refer to the docs for more details.

Presets

Now you can pack your custom rules and variants into presets and share them with others - or create even your own atomic CSS framework on top of UnoCSS!

Meanwhile, we ship with a few presets for you to get your hands on quickly.

One thing worth mentioning is the default @unocss/preset-uno preset (still experimental) is a common superset of the popular utilities-first framework, including Tailwind CSS, Windi CSS, Bootstrap, Tachyons, etc.

For example, both ml-3 (Tailwind), ms-2 (Bootstrap), ma4 (Tachyons), mt-10px (Windi CSS) are valid.

.ma4 { margin: 1rem; }
.ml-3 { margin-left: 0.75rem; }
.ms-2 { margin-inline-start: 0.5rem; }
.mt-10px { margin-top: 10px; }

Learn more about the default preset.

Flexibility

Till now, we are all showcasing how you can use UnoCSS to mimic the behavior of Tailwind - while we made it really easy to mimic Tailwind by your own, that alone probably won't make much difference on the user side.

Let's unleash the true power of UnoCSS:

Attributify Mode

The Attributify Mode is one of the beloved features of Windi CSS. It helps you better organize and group your utilities by using attributes.

It turns your Tailwind code from this:

<button class="bg-blue-400 hover:bg-blue-500 text-sm text-white font-mono font-light py-2 px-4 rounded border-2 border-blue-200 dark:bg-blue-500 dark:hover:bg-blue-600">
  Button
</button>

to:

<button
  bg="blue-400 hover:blue-500 dark:blue-500 dark:hover:blue-600"
  text="sm white"
  font="mono light"
  p="y-2 x-4"
  border="2 rounded blue-200"
>
  Button
</button>

Not only this provide better organization by the categories, but also saves you the repetitive typing of the same prefixes.

In UnoCSS, we implemented the Attributify Mode by using only one variant and one extractor with less than 100 lines of code in total! More importantly, it directly works for any custom rules you have defined!

In addition Windi's Attributify Mode, we also support valueless attributes with a few lines of changes:

<div class="m-2 rounded text-teal-400" />

now can be

<div m-2 rounded text-teal-400 />

Attributify Mode is provided via preset @unocss/preset-attributify, refer to its docs for detailed usages.

Pure CSS Icons

If you've ever read my previous post Journey with Icons Continues you must know that I am very enthusiastic about icons and actively researching for icons solutions. This time with UnoCSS's flexibility, we could even have pure CSS icons! Yes, you read me, it's purely in CSS and zero JavaScript! Let's just see how it looks like:

<!-- A basic anchor icon from Phosphor icons -->
<div class="i-ph-anchor-simple-thin" />
<!-- An orange alarm from Material Design Icons -->
<div class="i-mdi-alarm text-orange-400 hover:text-teal-400" />
<!-- A large Vue logo -->
<div class="i-logos-vue text-3xl" />
<!-- Sun in light mode, Moon in dark mode, from Carbon -->
<button class="i-carbon-sun dark:i-carbon-moon" />
<!-- Twemoji of laugh, turns to tear on hovering -->
<div class="i-twemoji-grinning-face-with-smiling-eyes hover:i-twemoji-face-with-tears-of-joy" />

Hover it

Combining with variants, you can even switch icons based on hovering state or even color schema. Play with the demo above and see. Thanks to the awesome Iconify project, you have access to over 10,000 icons from over 100 popular icon sets on-demand.

Once again, this feature is written with less than 100 lines of code. Check out the preset's implementation @unocss/preset-icons to learn the magic!

Update: Read my new post Icons in Pure CSS to learn more about it!

I hope these presets can give you a general idea of how flexible UnoCSS is. Given it's still in a very early stage, there are many possibilities for us to explore.

Scoping

One other problem that I have faced when using Tailwind/Windi is the preflight. Preflight resets the native elements and provide some fallback for CSS variables, it's great when developing a new app that uses Tailwind/Windi solely, but when you want to have them work with other UI frameworks, or share some components using Tailwind utilities, the preflight often introduce many conflicts that break your existing UI.

So UnoCSS took another aggressive step by not supporting preflights. Instead, it left the control of CSS resetting fully to users (or frameworks on top of UnoCSS) to use the one that fits their needs (Normalize.css, Reset.css, or UI frameworks' resetting, etc.)

This also allows UnoCSS to have more possibilities on CSS Scoping. For example, we have an experimental scoped-vue mode on the Vite plugin to generate scoped styles for each component so you can safely ship them as a component library using atomic CSS without worry about conflicting with users' CSS. For example:

<template>
  <div class="m-2 rounded">
    <slot />
  </div>
</template>

<!-- the following will be inject in the bundler -->
<style scoped>
.m-2 {
  margin: 0.5rem;
}
.rounded {
  border-radius: 0.25rem;
}
</style>

We are also experimenting with more possibilities like Web Components support, CSS code-splitting for MPA, module-level CSS scoping, etc.

Performance

Given all the flexibility and imagination UnoCSS brings, I would frankly think performance can be a less important thing to care about. Just out of curiosity, I wrote a simple benchmark to compare the performances. And surprisingly, here is the result:

10/21/2021, 2:17:45 PM
1656 utilities | x50 runs

none                            8.75 ms /    0.00 ms
unocss       v0.0.0            13.72 ms /    4.97 ms (x1.00)
windicss     v3.1.9           980.41 ms /  971.66 ms (x195.36)
tailwindcss  v3.0.0-alpha.1  1258.54 ms / 1249.79 ms (x251.28)

It turns out, UnoCSS could be 200x faster than Tailwind's JIT and Windi CSS. To be honest, with the on-demand approach, both Windi and Tailwind JIT are already super-fast, the performance gain in UnoCSS might not be very perceivable. However, the nearly zero overhead means you can integrate UnoCSS into your existing project to work with other frameworks as an incremental solution without worrying about the performance loss.

Deep down, UnoCSS did many performance optimizations. In case you wonder, here is a few of them to take away:

No Parsing, No AST

Internally, Tailwind relied on modifying PostCSS's AST, while Windi wrote a custom parser and AST. Given the fact that changes in utilities are not commonly expected during the development, UnoCSS generates the utilities by the very cheap string concatenation instead of introducing a whole parser and generating process. Meanwhile, UnoCSS aggressively caches to the class names with their generated CSS string, allowing it to bypass the entire matching and generating process when seeing the same utilities again.

Single Pass

As mentioned in the previous section, both Windi CSS and Tailwind JIT rely on the pre-scanning for the file system and use fs watcher for HMR. File IO inevitably introduces some overhead, while your build tools are actually needed to load them once again. So why don't we leverage the content that has already been read by the dev tools directly?

Other than the independent generator core, UnoCSS intentionally only provides Vite plugin which allows it to focus on the best possible integration with Vite.

Updates: Now it also provides a Webpack plugin and a CSS-in-JS runtime

In Vite, the transform hook will be iterated over with all the files with their content. So we can write a plugin to collect them like:

export default {
  plugins: [
    {
      name: 'unocss',
      transform(code, id) {
        // filter out the files you don't want to scan
        if (!filter(id))
          return

        // scan the code (also handles invalidate on dev)
        scan(code, id)

        // we just want the content, so we don't transform the code
        return null
      },
      resolveId(id) {
        return id === VIRTUAL_CSS_ID ? id : null
      },
      async load(id) {
        // generated css is provide as a virtual module
        if (id === VIRTUAL_CSS_ID)
          return { code: await generate() }
      }
    }
  ]
}

Given Vite also handles the HMR and will involve the transform hook again of upon file changes, this allows UnoCSS to finish everything in a single pass with no duplication of file IO and fs watcher. In addition to that, with this approach, the scanning relies on the module graph instead of file globing. Meaning that only the modules that been bundled into your app will affect the generated CSS instead of any files under your folders.

There are a few more tricks we have done to squeeze out even more performance. I might do another post about them later, but before that, you can read the code to figure out :)

Can I Use it Now?

For the short answer: Yes, but with cautions.

UnoCSS is still in experiments. But given its simplicity, the generation result is already quite reliable. One thing you need to care about is the APIs are not finalized yet. We will indeed follow semver on releasing, but please expect changes.

It's not designed to be a replacement of Windi CSS or Tailwind (consider waiting for Windi CSS v4). We don't recommend migrating existing projects to UnoCSS completely. You can try it on new projects or use it as a complement along with your existing CSS framework (for example, disable default preset and use the icon preset solely for pure CSS icons, or make your custom rules).

Oh btw, the site you are reading is now solely on UnoCSS, for you to reference :P.

Meanwhile, please feel free to share the presets you are making or help contribute to our default presets. We can't wait to see what you can come up with!

Thanks

Appreciate the early review and feedback provided by (A-Z):

• @alexanderniebuhr
• @ElMassimo
• @harlan-zw
• @QC-L
• @userquin
• @voorjaar
• @wheatjs

Wrapping Up

Thanks a lot for reading through! If it ever got you interested, do remember to check out the repo unocss/unocss for more details and play with it on the Online Playground.

Please feel free to comment or retweet this tweet letting me know what you think! 🙌

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/new-ways-to-vue-london-2021 https://antfu.me/posts/new-ways-to-vue-london-2021 Wed, 20 Oct 2021 08:00:00 GMT

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - presentation slides for developers.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/range-in-javascript https://antfu.me/posts/range-in-javascript Mon, 13 Sep 2021 16:00:00 GMT Credit to GitHub Copilot.

I didn't know you could provide a map function to Array.from as a second argument until today.

Array.from({ length: 10 }, (_, i) => i)
// [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/journey-with-icons-continues https://antfu.me/posts/journey-with-icons-continues Fri, 10 Sep 2021 18:00:00 GMT [[toc]]

About one year ago, I wrote a blog post Journey with Icons, sharing the tools I have made for solving my needs on using icons in frontend projects.

During this period, the Vite along its community has evolved quite a lot. The mindsets of Vite have inspired many projects to come up with efficient and innovative solutions.

In this post, I will share the continuation of my journey with icons and the tools I have ended up with so far.

PurgeIcons & Its Limitations

PurgeIcons is my first attempt to improve the loading speed of Iconify - a united icon library that allows you to use any icons for any framework. The main problem is that it's purely client-side. Even it's flexible to work with any framework, the client-side requests inevitably introduce the flash of missing icons. To solve that, I made PurgeIcons by statically scanning your icon usages and bundle them together with your app, so the Iconify runtime could load them without additional requests.

This solution works, but it only solves the problem partially. As the icons are bundled within JavaScript and functions outside the frameworks, it's not ideal for working with framework-specific features like server-side rendering/generation, props passing, etc. We need to find a better way of doing it.

The New Solution

One of the core-concept of Vite is that everything is on-demand. Modules get transpiled only when they are being requested. In this way, the Vite server starts immediately without the need to bundle your entire app. Additionally, Vite's plugin API is an extension on top of Rollup's plugin system, which allows you to do some custom transformations to the modules.

So, if we think in Vite's way - maybe we could solve this at compile-time instead of client-side! By using virtual modules, I was able to serve the icons as components on-the-fly and made it as
vite-plugin-icons (renamed to unplugin-icons later on).

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    IconsPlugin()
  ]
})

function IconsPlugin() {
  return {
    name: 'vite-plugin-icons',
    // tell Vite that ids start with `~icons/` are virtual files
    resolveId(id) {
      if (id.startsWith('~icons/'))
        return id
      return null
    },
    // custom logic to load the module
    load(id) {
      if (!id.startsWith('~icons/'))
        return
      const [prefix, collection, name] = id.split('/')
      // get icon data from Iconify
      const svg = getIconSVG(collection, name)
      // we compile the SVG as a Vue component
      return Vue3Compiler(svg)
    }
  }
}

And the usage will be like this:

<script setup>
import FaBeer from '~icons/fa/beer'
import MdiAlarm from '~icons/mdi/alarm'
import TearsOfJoy from '~/icons/twemoji/face-with-tears-of-joy'
</script>

<template>
  <MdiAlarm />
  <FaBeer style="color: orange" />
  <TearsOfJoy />
</template>

You might notice the usages are pretty similar to existing solutions like React Icons. However, most of them approaching this by compiling all the icons into multiple files and distribute them as npm packages. Not only does it ships additional bytes for every icon and increases the time for compilers to parsing them, that also means you are limited to what they have offered exclusively.

With unplugin-icons, you can use any icons available in Iconify (which is 100+ icon sets with over 10,000 icons and continue growing) by the following convention:

import Icon from '~icons/[collection]/[name]'

You can learn more about the installation and usage on

Universal

Universal on Icons

The unification or Icons are already done in Iconify by providing the icons in the same, normalized JSON format, so what if we could have it more universally available for the tools we loved?

Universal on Frameworks

Initially, I was made this plugin only for Vue 3 on Vite. But since we are doing the complication on-demand, I figured out that we could actually apply for different compilers based on the frameworks users use. With that idea, now it supports using icons as components for Vue 3, Vue 2, React, Preact and Solid! (Contributions to add more is great welcome!)

function Vue3Compiler(svg) { /* ... */ }
function Vue2Compiler(svg) { /* ... */ }
function JSXCompiler(svg) { /* ... */ }
function SolidCompiler(svg) { /* ... */ }
// ...add more!

function IconsPlugin({ compiler }) {
  return {
    name: 'vite-plugin-icons',
    resolveId(id) { /* ... */ },
    load(id) {
      /* ... */
      // we could apply different compilers here as needed
      return compiler(SVG)
    }
  }
}

With this, you can have it working in React like:

import FaBeer from '~icons/fa/beer'
import MdiAlarm from '~icons/mdi/alarm'
import TearsOfJoy from '~/icons/twemoji/face-with-tears-of-joy'

export function MyComponent() {
  return (
    <>
      <MdiAlarm />
      <FaBeer style="color: orange" />
      <TearsOfJoy />
    </>
  )
}

Universal on Build Tools

In the past few weeks, I have joined NuxtLabs and worked on a universal plugin layer for our various bundling tools - . It allows you to use a unified plugin API to write plugins for Vite, Webpack, Rollup, Nuxt, Vue CLI, and more only once. To make it work, all we need to do is to change our code like:

export function VitePluginIcons() {
  return {
    name: 'vite-plugin-icons',
    resolveId(id) { /* ... */ },
    load(id) { /* ... */ }
  }
}

import { createUnplugin } from 'unplugin'

const unplugin = createUnplugin(() => {
  return {
    name: 'unplugin-icons',
    resolveId(id) { /* ... */ },
    load(id) { /* ... */ }
  }
})

// Use unplugin to generate plugins for different build tools
export const VitePluginIcons = unplugin.vite
export const WebpackPluginIcons = unplugin.webpack
export const RollupPluginIcons = unplugin.rollup

That's cool. With it, you don't need to learn each frameworks' plugin API and publish them in multiple packages - now you got one package for all of them!

Universal Solution

With all the effort above, I converted my vite-plugin-icons, a Vite + Vue 3 specific icon plugin, to unplugin-icons as a universal icons solution.

For what I mean universal, I mean literally, you can use:

• Vue 3 + Vite + Carbon Icons
• React + Next.js + Material Design Icons
• Vue 2 + Nuxt.js + Unicons
• React + Webpack + Twemoji
• Solid + Vite + Tabler
• Vanila + Rollup + BoxIcons
• Web Components + Vite + Ant Design Icons
• Svelte + SvelteKit + EOS Icons
• Any + Any + Any

...really, you made the combinations!

Get it now 👇

One More Thing

Oh, you are still here. So I guess you are looking for something even further.

As you might notice, whenever you want to use an icon, you need to import it first, name it, and then use it. In this case, the icon name has been repeated at least three times. For example:

Vue

<script setup>
import MdiAlarm from '~icons/mdi/alarm'
</script>

<template>
  <MdiAlarm />
</template>

React

import MdiAlarm from '~icons/mdi/alarm'

export function MyComponent() {
  return (
    <div>
      <MdiAlarm />
    </div>
  )
}

So yes, we might need a better way to do this.

Auto-importing

Inspired by which registers components under your ./components directory automatically, I made (yes, another unplugin!) do to compile-time components auto-importing on-demand. With the on-demand natural, we could even make the components resolving on-demand. What a perfect complement for our icon solution!

unplugin-vue-components provide the options resolvers to provide custom functions to resolve where the components should be imported from.

Here is an example configuration for Vite (since both of them are unplugins, you can also use them for Webpack and Rollup):

import IconsResolver from 'unplugin-icons/resolver'
import Icons from 'unplugin-icons/vite'
import Components from 'unplugin-vue-components/vite'
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    /* ... */
    Icons(),
    Components({
      resolvers: [
        IconsResolver({
          // to avoid naming conflicts
          // a prefix can be specified for icons
          prefix: 'i'
        })
      ]
    })
  ]
})

Then we can use them directly in our templates, no more imports and repeats (and you can change the icons much easier as you don't need to update in three places):

<template>
  <!-- both PascalCase and dash-case are supported by Vue -->
  <IMdiAlarm />
  <i-fa-beer style="color: orange" />
</template>

Isn't it perfect?!

Learn more:

Auto-import integrations for @nuxt/components is in progress.

Auto-importing for JSX

Oh, I almost forgot about it. Since JSX is more like plain JavaScript in some ways and JSX components are just functions or classes, the thing is actually a bit simpler. For that, we can use another unplugin I made - .

For some background here, unplugin-auto-import is a compile-time successor of to improve DX of Vue Composition API (directly use of ref, computed, etc.).

With the expansion to a general auto-importing solution for any API sets, it's also possible to do auto-importing for JSX components. in unplugin-auto-import, we implement the same resolver interface for it.

import AutoImport from 'unplugin-auto-import/vite'
import IconsResolver from 'unplugin-icons/resolver'
import Icons from 'unplugin-icons/vite'
// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    /* ... */
    Icons({
      compiler: 'jsx'
    }),
    AutoImport({
      imports: [
        'react' // preset for react
      ],
      resolvers: [
        IconsResolver({
          prefix: 'Icon',
          extension: 'jsx'
        })
      ]
    })
  ]
})

Here is your React component, and you are welcome :)

export function MyComponent() {
  return (
    <>
      <IconMdiAlarm />
      <IconFaBeer style="color: orange" />
    </>
  )
}

Recap

For a quick summary, here is the list of projects mentioned for these solutions:

• - Unified plugin system for Vite, Rollup, Webpack, and more.
• - Access thousands of icons as components on-demand.
• - On-demand components auto importing.
• - Auto import APIs on-demand.

Meanwhile, you might also find these tools from my last journey helpful:

• - Icon Explorer for Iconify with Instant searching and exporting.
• - Iconify IntelliSense for VS Code.

If you enjoy them, you might also want to check my Vue + Vite starter template with them configured in-box.

• - Opinionated Vite Starter Template.
• - Lightweight version of Vitesse.
• - WebExtension Vite Starter Template.
• - Vitesse experience for Nuxt 2 and Vue 2.

Again, thanks for reading through :)

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/isomorphic-dirname https://antfu.me/posts/isomorphic-dirname Mon, 30 Aug 2021 16:00:00 GMT In ESM, you might found your old friends __dirname and __filename are no longer available. When you search for solutions, you will find that you will need to parse import.meta.url to get the equivalents. While most of the solutions only show you the way to get them in ESM only, If you like me, who write modules in TypeScript and transpile to both CJS and ESM at the same time using tools like tsup. Here is the isomorphic solution:

import { dirname } from 'node:path'
import { fileURLToPath } from 'node:url'

const _dirname = typeof __dirname !== 'undefined'
  ? __dirname
  : dirname(fileURLToPath(import.meta.url))

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/github-co-authors https://antfu.me/posts/github-co-authors Tue, 24 Aug 2021 16:00:00 GMT You might found GitHub sometimes shows you a commit with multiple authors. This is commonly happening in squashed pull requests when multiple people are involved with the reviewing and made suggestions or changes. In that situation, GitHub will automatically inject the Co-authored-by: to the commit message. This is a great way to give contributors credits while keeping the commit history clean.

Note that the format is like Co-authored-by: name <name@example.com>, normally GitHub will fill that for you so you don't need to worry about that, but if you want to add it manually, you have to get the email addresses of the contributors. But how do you know their emails?

Well, technically you can indeed find their email by multiple ways, but actually, you don't need to. The easiest way is to copy their user id and append with @users.noreply.github.com that provided by GitHub automatically, for example:

Co-authored-by: antfu <antfu@users.noreply.github.com>

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/async-with-composition-api https://antfu.me/posts/async-with-composition-api Fri, 16 Jul 2021 08:00:00 GMT There is a major caveat when working with asynchronous functions in Vue Composition API, that I believe many of you have ever come across. I have acknowledged it for a while from somewhere, but every time I want to have a detailed reference and share to others, I can't find it's documented anywhere. So, I am thinking about writing one, with a detailed explanation while sorting out the possible solutions for you.

• The Problem
• The Mechanism
• The Limitation
• The Solutions

The Problem

When using asynchronous setup(), you have to use effects and lifecycle hooks before the first await statement. (details)

For example:

import { onMounted, onUnmounted, ref, watch } from 'vue'

export default defineAsyncComponent({
  async setup() {
    const counter = ref(0)

    watch(counter, () => console.log(counter.value))

    // OK!
    onMounted(() => console.log('Mounted'))

    // the await statement
    await someAsyncFunction() // <-----------

    // does NOT work!
    onUnmounted(() => console.log('Unmounted'))

    // still works, but does not auto-dispose
    // after the component is destroyed (memory leak!)
    watch(counter, () => console.log(counter.value * 2))
  }
})

After the await statement,

the following functions will be limited (no auto-dispose):

• watch / watchEffect
• computed
• effect

the following functions will not work:

• onMounted / onUnmounted / onXXX
• provide / inject
• getCurrentInstance
• ...

The Mechanism

Let's take the onMounted API as an example. As we know, onMounted is a hook that registers a listener when the current component gets mounted. Notice that onMounted (along with other composition APIs) are global, for what I mean "global" is that it can be imported and called anywhere - there is no local context bound to it.

// local: `onMounted` is a method of `component` that bound to it
component.onMounted(/* ... */)

// global: `onMounted` can be called without context
onMounted(/* ... */)

So, how does onMounted know what component is being mounted?

Vue takes an interesting approach to solve this. It uses an internal variable to record the current component instance. There is a simplified code:

When Vue mounts a component, it stores the instance in a global variable. When hooks been called inside the setup function, it will use the global variable to get the current component instance.

let currentInstance = null

// (pseudo code)
export function mountComponent(component) {
  const instance = createComponent(component)

  // hold the previous instance
  const prev = currentInstance

  // set the instance to global
  currentInstance = instance

  // hooks called inside the `setup()` will have
  // the `currentInstance` as the context
  component.setup()

  // restore the previous instance
  currentInstance = prev
}

A simplified onMounted implementation would be like:

// (pseudo code)
export function onMounted(fn) {
  if (!currentInstance) {
    warn(`"onMounted" can't be called outside of component setup()`)
    return
  }

  // bound listener to the current instance
  currentInstance.onMounted(fn)
}

With this approach, as long as the onMounted is called inside the component setup(), it will be able to get the instance of the current component.

The Limitation

So far so good, but what's wrong with asynchronous functions?

The implementation would work based on the fact that JavaScript is single-threaded. Single thread makes sure the following statements will be executed right next to each other, which in other words, there is no one could accidentally modify the currentInstance at the same time (a.k.a. it's atomic).

currentInstance = instance
component.setup()
currentInstance = prev

The situation changes when the setup() is asynchronous. Whenever you await a promise, you can think the engine paused the works here and went to do another task. If we await the function, during the time period, multiple components creation will change the global variable unpredictably and end up with a mess.

currentInstance = instance
await component.setup() // atomic lost
currentInstance = prev

If we don't use await to check the instance, calling the setup() function will make it finish the tasks before the first await statement, and the rest will be executed whenever the await statement is resolved.

async function setup() {
  console.log(1)
  await someAsyncFunction()
  console.log(2)
}

console.log(3)
setup()
console.log(4)

// output:
3
1
4
(awaiting)
2

This means, there is no way for Vue to know when will the asynchronous part been called from the outside, so there is also no way to bound the instance to the context.

The Solutions

This is actually a limitation of JavaScript itself, unless we have some new proposal to open the gate on the language level, we have to live with it.

But to work around it, I have collected a few solutions for you to choose from based on your needs.

Remember the Caveat and Avoid It

This is, of course, an obvious "solution". You can try to move your effect and hooks before the first await statement and carefully remember not to have them after that again.

Luckily, if you are using ESLint, you can have the vue/no-watch-after-await and vue/no-lifecycle-after-await rules from eslint-plugin-vue enabled so it could warn you whenever you made some mistakes (they are enabled by default within the plugin presets).

Wrap the Async Function as "Reactive Sync"

In some situations, your logic might be relying on the data that fetched asynchronously. In this way, you could consider using the trick I have shared on VueDay 2021 to turn your async function into a sync reactive state.

const data = await fetch('https://api.github.com/').then(r => r.json())

const user = data.user

const data = ref(null)

fetch('https://api.github.com/')
  .then(r => r.json())
  .then(res => data.value = res)

const user = computed(() => data?.user)

This approach make the "connections" between your logic to resolve first, and then reactive updates when the asynchronous function get resolved and filled with data.

There is also some more general utilities for it from VueUse:

useAsyncState

import { useAsyncState } from '@vueuse/core'

const { state, ready } = useAsyncState(async () => {
  const { data } = await axios.get('https://api.github.com/')
  return { data }
})

const user = computed(() => state?.user)

useFetch

import { useFetch } from '@vueuse/core'

const { data, isFetching, error } = useFetch('https://api.github.com/')

const user = computed(() => data?.user)

Explicitly Bound the Instance

Lifecycle hooks actually accept a second argument for setting the instance explicitly.

export default defineAsyncComponent({
  async setup() {
    // get and hold the instance before `await`
    const instance = getCurrentInstance()

    await someAsyncFunction() // <-----------

    onUnmounted(
      () => console.log('Unmounted'),
      instance // <--- pass the instance to it
    )
  }
})

However, the downside is that this solution does not work with watch / watchEffect / computed / provide / inject as they does not accept the instance argument.

To get the effects work, you could use the effectScope API in the upcoming Vue 3.2.

import { effectScope } from 'vue'

export default defineAsyncComponent({
  async setup() {
    // create the scope before `await`, so it will be bond to the instance
    const scope = effectScope()

    const data = await someAsyncFunction() // <-----------

    scope.run(() => {
      /* Use `computed`, `watch`, etc. ... */
    })

    // the lifecycle hooks will not be available here,
    // you will need to combine it with the previous snippet
    // to have both lifecycle hooks and effects works.
  }
})

Compile-time Magic!

In the recent <script setup> proposal update, a new compile-time magic is introduced.

The way it works is to inject a script after each await statement for restoring the current instance state.

<script setup>
  const post = await fetch(`/api/post/1`).then((r) => r.json())
</script>

import { withAsyncContext } from 'vue'

export default {
  async setup() {
    let __temp, __restore

    const post
      = (([__temp, __restore] = withAsyncContext(() =>
        fetch(`/api/post/1`).then(r => r.json())
      )),
      (__temp = await __temp),
      __restore(),
      __temp)

    // current instance context preserved
    // e.g. onMounted() will still work.

    return { post }
  }
}

With it, the async functions will just work when using with <script setup>. The only shame is it does not work outside of <script setup>.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/get-package-root https://antfu.me/posts/get-package-root Wed, 14 Jul 2021 16:00:00 GMT When you want to get the real file path of a certain package, you could use require.resolve to fetch their main entry path.

> require.resolve('vite')
'/Users/.../node_modules/vite/dist/node/index.js'

> require.resolve('windicss')
'/Users/.../node_modules/windicss/index.js'

However, when you want to get the root directory of the package, you will find the result of require.resolve could vary based on different packages' configurations.

A trick for this is to resolve the package.json instead, as the package.json is always located at the root of the package. Combining with path.dirname, you could always get the package root.

> path.dirname(require.resolve('vite/package.json'))
'/Users/.../node_modules/vite'

Update: or you can use my package local-pkg now :)

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/optimize-await https://antfu.me/posts/optimize-await Thu, 01 Jul 2021 16:00:00 GMT async / await in ES7 is truly a life-saver for the JavaScript world. It allows you to avoid callback hell in your code and make it more readable. However, a common pitfall is that when you await a huge asynchronous task that takes very long time, it blocks the following code and could potentially make your app slow.

For example:

const app = await createServer()
const middlewareA = await resolveMiddlewareA()
const middlewareB = await resolveMiddlewareB()

app.use(middlewareA)
app.use(middlewareB)

We have used three await in the example, while the three async function does not actually relying on each other, having them sequentially we are possibility wasted some time of the operations that could be parallelized (IO, Network, etc.)

So we can use Promise.all to optimize the code:

const [app, middlewareA, middlewareB] = await Promise.all(
  [
    createServer(),
    resolveMiddlewareA(),
    resolveMiddlewareB(),
  ],
)

app.use(middlewareA)
app.use(middlewareB)

In another example, you might relying on the async result, but sometime not that urgent:

async function createPlugin() {
  const toolkit = await initToolKit()

  return {
    onHookA() {
      toolkit.invokeA()
    },
    onHookB() {
      toolkit.invokeB()
    },
  }
}

const plugin = await createPlugin()

Even though you don't need toolkit immediately, you are still forced to use async function because the initToolKit is async. To avoid this, we could make the promise been resolved in the hooks instead

function createPlugin() {
  const toolkitPromise = initToolKit()

  return {
    async onHookA() {
      const toolkit = await toolkitPromise
      toolkit.invokeA()
    },
    async onHookB() {
      const toolkit = await toolkitPromise
      toolkit.invokeB()
    },
  }
}

// now it's sync!
const plugin = createPlugin()

Since a Promise could only be resolved once, using multiple await for a single Promise instance is totally fine - it will return the resolved result immediate if the Promise is allready settled.

To be more generalized, we could have an utility function like:

export function createSingletonPromise<T>(fn: () => Promise<T>) {
  let _promise: Promise<T> | undefined

  return () => {
    if (!_promise)
      _promise = fn()
    return _promise
  }
}

This function is also available in my utilities collection @antfu/utils

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/about-yak-shaving https://antfu.me/posts/about-yak-shaving Wed, 19 May 2021 16:00:00 GMT [[toc]]

中文原文 Original in Chinese

I recently visited Zhihu occasionally and saw many questions about how to start open source, or how to make open source projects successful. I kinda had similar doubts for a long time, so I thought that maybe I could share some of my rough views on this.

If you don't know me, I am a team member of Vue, Vite, wenyan-lang, WindiCSS, Intlify, and the author of VueUse, Slidev, Type Challenges and i18n Ally. I also have some small open source tools under my personal GitHub account, you can have a look at my full project list. Since I started doing open source in earnest almost two years ago, even though those contributions aren't that impressive, they still managed to allow me to work full-time on open source development and maintenance through sponsorships.

Many people probably gonna tell you that the success of a project depends on opportunity, marketing, branding, or documentation, ecosystem, technical innovation, code quality, etc. All of these are indeed important, but for me, the most important thing is the motivation to start a project and the drive to do it well. For me, the best way to get the power is via Yak Shaving.

Yak Shaving

Yak Shaving refers to a series of actions when you're working on one task and then you find another task that's not finished, you tackle that one first, and while you're working on that one, you find another task to do... and so forth, so that you stray from the work that should have been done, and end up not getting nothing finished. Here is a real-world example:

You want to bake an apple pie, so you head to the kitchen.

In the hallway, you notice some paint chipping on the wall.

So you walk to the hardware store for some paint.

On the way, you pass a bakery and stop in for a cupcake.

While eating the cupcake, you feel a pain in your mouth. It’s that cavity that you’ve been putting off.

You pick up your phone to call the dentist to make an appointment, but you see a notification from your friend Cher, who’s having a party.

You don’t want to show up empty-handed, so you stop for a bottle of wine…

An example that more relevant to developers might be: You planned to write a blog today, but you found out none of the existing tools are good enough for you. Then you spend a month writing your own static website generator, but end up with the generator unfinished and forgetting about writing the blog.

I guess we all had similar experiences more or less. Yak Shaving usually refers to something negative, emphasizing inattentiveness or lack of clarity of purpose. But I kinda think it's also an important source of motivation for many things. When a person needs a tool, they are most motivated to solve it and make it happen. I, not coincidentally, am an obsessive Yak Shaving fan.

Maybe I'll share some of my stories with you to give you a better idea of what I'm trying to express:

The story of how I started doing open source

In my senior year of college, I went on a graduation trip to the Philippines with a group of college friends. Because of the various problems of exchanging foreign currency, an operation down to Taiwan dollars, US dollars, Philippine pesos and different exchange rates each time, making the record of public accounts and settlement very complicated. After we came back from the trip, we came up with the idea of making an app to solve this problem.

To make the app reach a large enough audience, multilingual internationalization is something we have to consider. As there are many foreign language departments in our college, we thought we could use our resources to get our friends to help on translating the App into multiple languages. However, it is obviously unrealistic to have foreign language students write JSON with bare hands, so we had to find something a little easier. Luckily, I found think2011/vscode-vue-i18n, which looks great, but lacks some features we needed. So I contacted the author and got fork permission, and then, here comes the i18n Ally project.

The later stage of App development coincided with the Composition API RFC of Vue 3. The new API seemed to solve many of the pain points in our development. In the spirit of experimentation, we installed the Vue 2 plugin and started to try it out. In the process of using it, we found out there are quite some functions we are commonly used, and also inspired by react-use, I extracted them out and made VueUse.

Given that Vue 3 was still in Alpha at the time, and the community needs to gradually migrate from Vue 2 to Vue 3 for a long time in the future. I made VueUse intentionally as a universal library for Vue 2 and Vue 3 so that people could migrate seamlessly. The initial solution was to publish two packages for Vue 2 and 3 under different npm tags. As Vue 3 matured, more and more libraries wanted to go the same way to reduce the cost of maintaining two codebases at the same time. Then I thought, maybe I can find a general solution from VueUse, so that everyone could get benefit from it. And then, vue-demi comes out. As a result, it also allows VueUse to publish one version that supports both Vue 2 and 3 at the same time.

VueUse's support for Vue 2 relies on the @vue/composition-api library, at some point, there are some inconsistencies in the plugin with the latest Vue 3 changes. Which results in VueUse's development being hampered. After a quite long time of no response to the PR from the repository, I thought I might be able to help out a bit, so I posted an issue in the repository saying I would like to volunteer myself maintaining the project. And that's also the opportunity for me to join the Vue team.

In the end, our App didn't work out, but I gained a lot of valuable experience solving problems and working on open source projects along the way. i18n Ally started out as a vue-i18n specific extension and now supports over 20 major frameworks, with over 60,000 downloads of VS Code. VueUse started as a simple toolset and now it becomes a GitHub Organization with 10 members and 8 ecosystem packages.

I could probably tell stories like these for a whole day, and behind almost every project there is such a motivation to try to solve a certain problem. After all of this harangue, the point I'm trying to make is that Yak Shaving can be a great engine for progressing when used properly.

And here are my methods of how to make Yak Shaving a good thing:

Shave the Good Yak

Identify Problems

I spent every day of my four years in college thinking if I could make an interesting open source project that everyone needed and live as a full-time open sourceror with freedom. The difference is that the four years I was thinking about how to make something that other people wanted, but later I was solving the actual problems that I encountered. As said, when you need a tool, you have the most motivation to make it. And also as a user, you know the best where the pain points and needs are. When you encounter this problem, others might have just encountered a similar one.

Solve the Problem

The most basic rule to start trying to solve a problem is to look for existing solutions, if the problem has been well solved, which meets your all needs, then just use it. Reinventing wheels might be a good way to learn, but since the wheels are already there, there has to be someone thinking about how to build a car, right?

When you find that there is no solution to the problem, or that the existing solutions don't work for you, while you have a great idea in your mind. Congratulations, you've found a great Yak.

Good Enough

The most important part of making Yak Shaving great is to just be good enough -- do not have too much expectation, if the idea is verified feasible, make it just good enough; if the idea does now work, don't be discouraged, just throw it away, maybe one day you can pick it back up again with new ideas. It's not necessary to be perfect at the beginning. You don't have to draw a grand blueprint or plan, you don't have to set a huge goal of how many stars or how many users - you are doing it for yourself, and make it just good enough to solve your own problems. The important thing is to not spending too much time on a single idea, and get back to what you should have been doing in time.

Refine the Project

As the first user of your own product, you will find a lot of things for improvement in the process of using it, go and modify it from time to time and do some improvements. If you got more time, you can add a README describing the problems you encountered and the motivation for doing the project, which may be helpful to someone who faced similar problems.

In the end, when using the project makes you feel that it's a pretty good idea, while you have completed the work that should have been done, you may wish to spend some time writing a document, improve the implementations, and promote a little. It's best if it has been recognized, but if not, just treat it as an exercise, and at least you've your own problems solved. If the responses went well, then someone will start to raise issues and send PRs. Which more enhancements and features coming, you will also gradually find the future direction of the project. Besides that, those changes and enhancements from the community may end up being a better solution to the problems you encountered at the beginning.

Identify More Problems

The way to find more problems is simple, learn more and try more. In the process of solving and improving the problem, you will likely find new problems that could potentially be solved. Issues from the community can also help you find more inspiration. Anyway, congratulations on entering the positive cycle!

Wrapping Up

Hopefully, this insight could give you some inspiration on solving your own problems, or making a good open source product, in one way or another.

I also recommend some awesome Yak Shaving masters, maybe their projects and experiences can give you some inspiration as well:

• Sindre Sorhus - actively maintains 1100+ npm packages, Webpack and Babel both rely on 100+ of his packages
• TJ Holowaychuk - Author of koa, mocha, express, etc.
• Luke Edwards - Author of polka, uvu, klona, etc.
• Egoist - Author of poi, cac, saber, etc.
• Hiroki Osame - Author of esbuild-loader, vue-2-3, etc.

Cheers, and happy hacking!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/composable-vue-vueday-2021 https://antfu.me/posts/composable-vue-vueday-2021 Wed, 28 Apr 2021 16:00:00 GMT [[toc]]

This is the transcript of my talk Composable Vue at VueDay 2021

Slides: PDF | SPA

Recording: YouTube

Made with Slidev - a slides maker for developers that I am working on recently.

Transcript

My sharing today is Composable Vue, some pattens and tips that might be able to help you writing better composable logic in Vue.

VueUse

It all started with me made this project called VueUse, which is a collection of Vue composable utilities. Initially, I was making this to share some of the functions I wrote with Vue Composition API to be used across apps. Till now, it grows much bigger with the community, we are now an organization on GitHub with 9 team members, 8 add-ons packages for different integrations like motions and document head management. We also have more than 100 functions in the core package that work for both Vue 2 and 3. I have really appreciated all the contributors and the awesome community.

vueuse/vueuse

In today's talk, I will share with you the patterns and tips that I have learned during developing VueUse and using it to make apps in Composition API.

Composition API

Let's have a quick look at the Composition API itself. BTW, please note today's talk will be a little bit advanced, which I would assume you already have a basic knowledge of what the Vue Composition API is. But don't worry if you don't, I believe you will still get some basic images of the methodology and you can also find the slides and transcript on my site after the talk.

Ref vs Reactive

Well, let's start with Ref and Reactive. I bet many of you have wondered the difference between them and which one should you choose.

You can think refs as variables and reactives as objects. When you do the assignment, one is assigning "value" while the other one is assigning properties. While the usage of them can really dependents on what you gonna use them, but if we really need to pick one from them, I'd say go with ref whenever you can.

With ref, you will need to use .value to access and assigning values, but this also gives you more explicit awareness of when you are tracking and triggering the reactivity system.

import { ref } from 'vue'

let foo = 0
let bar = ref(0)

foo = 1
bar = 1 // ts-error

As you can see the example here, I actually got an error by accidentally assigning ref with a value, and here I can change the code to fix it.

import { reactive } from 'vue'

const foo = { prop: 0 }
const bar = reactive({ prop: 0 })

foo.prop = 1
bar.prop = 1

On the other hand, when using reactive you actually can't tell the difference between a plain object and a reactive object without looking for the context, which could sometimes make the debugging a little bit harder.

Also note in reactive objects, there are several caveats you need to take care about. Like you can't do object destructure without toRefs otherwise they will lose the reactivity. And you will also need to wrap with a function when using with watch and so on, where ref does not have such limitations.

Ref Auto Unwrapping

When using with refs, a big obstacle that people facing is the annoying .value. But actually, in many cases, you can omit it and make your code looks cleaner.

const counter = ref(0)

watch(counter, (count) => {
  console.log(count) // same as `counter.value`
})

The watch function accepts ref as the watch source directly, and it will return the unwrapped new value of the ref in the callback. So in this case, there is zero .value needed.

<template>
  <button @click="counter += 1">
    Counter is {\{ counter }}
  </button>
</template>

The other one is the nature of Vue, in the template, all the refs are auto unwrapped, even assignments!

import { reactive, ref } from 'vue'

const foo = ref('bar')
const data = reactive({ foo, id: 10 })
data.foo // 'bar'

And whenever you feel like to better work with objects, you can pass the ref into the reactive object, and when you access the property, reactive will unwrap the ref automatically for you. Changes to the original ref will also reflect to the reactive object!

unref - Oppsite of Ref

unref is another Composition API I would like to introduce. As the name unref sounds, it's kinda the opposite of ref. While the ref() function takes a value and turns it into a ref, unref() takes a ref and returns its value.

function unref<T>(r: Ref<T> | T): T {
  return isRef(r) ? r.value : r
}

The interesting part of it is that if you pass a plain value to unref it will return the value as-is to you, you can see the implementation is basically this.

import { ref, unref } from 'vue'

const foo = ref('foo')
unref(foo) // 'foo'

const bar = 'bar'
unref(bar) // 'bar'

This is not a big feature, but a good tip to unify your logic which I will show you soon

Patterns & Tips

That's the tips for using ref and reactive. Here I'd like to share with you some patterns of writing composable functions.

What's composable Functions

So what's composable functions?

It's actually kind of hard to give a proper definition, but I'd think it's like sets for reusable logic to make your code better organized, and separate the concerns.

export function useDark(options: UseDarkOptions = {}) {
  const preferredDark = usePreferredDark() // <--
  const store = useStorage('vueuse-dark', 'auto') // <--

  return computed<boolean>({
    get() {
      return store.value === 'auto'
        ? preferredDark.value
        : store.value === 'dark'
    },
    set(v) {
      store.value = v === preferredDark.value
        ? 'auto'
        : v ? 'dark' : 'light'
    },
  })
}

Here is an example, the useDark function in VueUse is provided as a simple toggle to enable or disable the dark mode for apps. There are actually two variables involved, one is the system's preference and one is users' manual overrides. System preference can be got using media queries, while we would also need to use localStorage to read and store the user's preference of different modes.

As you can see in this code snippet, I have used two other composable functions usePreferredDark and useStorage, they will return two refs that reflecting on their states. Detailed things like monitoring the media query changes, the timing to read and write the storage are left to them. And all I need to do is logically composing their relationship into a single ref.

You can see the full code or directly use it in VueUse with the link below.

Think as "Connections"

The first methodology I want to share today is to think as "connections". Unlike hooks in React that will run on each updates, the setup() function in Vue only runs once on component initialization, to construct the relations between your state and logic.

You can think the equations in mathematics, where the left hand side and right hand side are always equal. Here we have z=x^2+y^2, while x and y are independent variables, and z is a controlled variables relying on x and y. Whenever I changed any of them, z will be updated accordingly (DEMO). Which is also similar to the formula in spreadsheets.

So in composable functions, we could think arguments are input and the returns as the output. The output should be able to reflect on input changes automatically. A bit complicated? I will walk with you on that later with examples.

One Thing at a Time

Another aspect is to do one thing at a time - which is the same as how you write any code. No need for me to spend too much time on this, but basically they are listed here.

• Extract duplicated logics into composable functions
• Have meaningful names
• Consistent naming conversions - useXX createXX onXX
• Keep function small and simple
• "Do one thing, and do it well"

Note it's also important to have a consistent naming conversion, like prefixed with useXX or createXX and so on to make those composable functions distinguishable from other functions.

Passing Ref as Arguments

Alright, let's start our first pattern today - Passing refs as arguments.

function add(a: number, b: number) {
  return a + b
}

const a = 1
const b = 2

const c = add(a, b) // 3

Here we have a plain add function that sums up the two arguments a and b. You can also see the example on the right.

function add(a: Ref<number>, b: Ref<number>) {
  return computed(() => a.value + b.value)
}

const a = ref(1)
const b = ref(2)

const c = add(a, b)
c.value // 3

And then we can make this function accepting refs, and return a computed ref with their sum. Then we can pass the refs to it as we normally would with plain values. The difference here is that the returned value is also a ref, but it will always be up-to-date with the ref a and b.

function add(
  a: Ref<number> | number,
  b: Ref<number> | number
) {
  return computed(() => unref(a) + unref(b))
}

const a = ref(1)

const c = add(a, 5)
c.value // 6

And remember the unref function we mentioned before? We can actually make this function more flexible, by accepting both refs and plain values. And use unref to get their values. We can also make the addition possible between a ref and a value.

MaybeRef

type MaybeRef<T> = Ref<T> | T

Here is a simple TypeScript's type helper called MaybeRef that we have used a lot in VueUse. It's a union of generic T and Ref<T>.

export function useTimeAgo(
  time: Date | number | string | Ref<Date | number | string>,
) {
  return computed(() => someFormating(unref(time)))
}

import type { Ref } from 'vue'
import { computed, unref } from 'vue'

type MaybeRef<T> = Ref<T> | T

export function useTimeAgo(
  time: MaybeRef<Date | number | string>,
) {
  return computed(() => someFormating(unref(time)))
}

In this case, we have the function useTimeAgo that accepts a wide range of Date-like types as an argument. Normally if you want to accept refs, you would need to write them again as Ref versions. With this helper, you can make the type shorter and more readable (change code). A cool point it that this works great with unref, it can infer the correct type for MaybeRef.

Make it Flexible

Think your functions like LEGO, there should have many different ways of composing them for different needs.

import { useTitle } from '@vueuse/core'

const title = useTitle()

title.value = 'Hello World'
// now the page's title changed

Here we take useTitle function from VueUse as an example. Basically when you call it, you will get a special ref that binds to your page's title. Whenever you change the ref's value, the page's title will also be updated. Similarly, when the page's title changed externally, the change will also be reflect to the ref's value.

Looks good, right? But It creates a new ref whenever you call it. To make it more flexible, we can actually bind an existing ref, even computed!

import { useTitle } from '@vueuse/core'
import { computed, ref } from 'vue'

const name = ref('Hello')
const title = computed(() => {
  return `${name.value} - World`
})

useTitle(title) // Hello - World

name.value = 'Hi' // Hi - World

Here you can see, I constructed a computed with a ref, when I change the source ref, the computed get re-evaluated so as the page's title.

useTitle Case

You must be wondering how could this be implemented. Let's take a look at a simplified version of it.

import type { MaybeRef } from '@vueuse/core'
import { ref, watch } from 'vue'

export function useTitle(
  newTitle: MaybeRef<string | null | undefined>
) {
  const title = ref(newTitle || document.title) // <-- 1

  watch(title, (t) => { // <-- 2
    if (t != null)
      document.title = t
  }, { immediate: true })

  return title
}

It's actually only two statements! How?

At the first line, unified the ref from the user, or create a new one. And on the second line, it watches the changes to the ref and sync up with page's title.

Emm, maybe it's a little bit hard to catch on what's happened in the first line, let me explain a bit.

Reuse Refs

Here, we utilized an interesting behavior of the ref function.

Similar to unref - ref also checks whether the passed value is ref or not. If you passed a ref to it, it will it as-is - since it's already a ref, there is no need to make another.

const foo = ref(1) // Ref<1>
const bar = ref(foo) // Ref<1>

foo === bar // true

function useFoo(foo: Ref<string> | string) {
  // no need!
  const bar = isRef(foo) ? foo : ref(foo)

  // they are the same
  const bar = ref(foo)

  /* ... */
}

This could also be extremely useful in composable functions that take MaybeRef as argument types.

ref / unref

Let's do a quick summary so far.

• MaybeRef<T> works well with ref and unref.
• Use ref() when you want to normalized it as a Ref.
• Use unref() when you want to have the value.

type MaybeRef<T> = Ref<T> | T

function useBala<T>(arg: MaybeRef<T>) {
  const reference = ref(arg) // get the ref
  const value = unref(arg) // get the value
}

We can use MaybeRef in arguments to make the function flexible, and use ref() when you want to normalized it as a Ref and use unref() when you want to get the value. Both of them are universal and no conditions needed.

Object of Refs

Another pattern today is to use objects of refs. When you need to return multiple data entries in a composable function, consider returns an object composed by refs.

import { reactive, ref } from 'vue'

function useMouse() {
  return {
    x: ref(0),
    y: ref(0)
  }
}

const { x, y } = useMouse()
const mouse = reactive(useMouse())

mouse.x === x.value // true

In this way, users can have the full features of ES6 object destructure. The restructure values are refs, so the reactivity still remains, and users can also rename them, or take only partial of what they want.

On this other hand, it's also flexible enough when users want to use it as a single object, simply wrap it with the reactive function, the refs will get unwrapped as a property automatically.

That said, users can get benefits from both ref and reactive as need.

Async to "Sync"

Since we are constructing "connections" using Composition API, we can actually make async functions to "sync" by building the connections first before it resolves.

const data = await fetch('https://api.github.com/').then(r => r.json())

// use data

Let's say we want to request some data use the fetch API. Normally we need to await the request been responded and data been parsed, before we can use the data. With Composition API, we can make the data as a ref of null, then be fulfilled later.

const { data } = useFetch('https://api.github.com/').json()

const user_url = computed(() => data.value?.user_url)

This can make your apps take the time to handle other stuff while waiting for the data to be fetched. The idea is similar to react's stale-while-revalidate, but with much easier implementation.

useFetch Case

The implementation can be simplified down to this, all you have to do is to assign the value to ref when the promise got resolved.

export function useFetch<R>(url: MaybeRef<string>) {
  const data = shallowRef<T | undefined>()
  const error = shallowRef<Error | undefined>()

  fetch(unref(url))
    .then(r => r.json())
    .then(r => data.value = r)
    .catch(e => error.value = e)

  return {
    data,
    error
  }
}

In the real world, we might also need some flags to show the current state of the request, where you can find the full code in VueUse.

Side-effects Self Cleanup

watch and computed functions in Vue will stop themselves automatically along with the components unmounting. We'd recommend following the same pattern for your custom composable functions.

By calling the onUnmounted hooks inside your composable functions, you can schedule the effect clean-up logic.

import { onUnmounted } from 'vue'

export function useEventListener(target: EventTarget, name: string, fn: any) {
  target.addEventListener(name, fn)

  onUnmounted(() => {
    target.removeEventListener(name, fn) // <--
  })
}

For example, it's common to use addEventListener to register the handler to DOM events. When you finish the usage, you would also need to remember to unregister it using removeEventListener. In this case, we can have a function useEventListener that unregister itself along with the component so you don't need to worry about it anymore.

effectScope RFC Upcoming

While side-effects auto clean-up is nice, sometimes you might want to have better controls over when to do that. I drafted an RFC proposing a new API called effectScope to collect those effects into a single instance, that you can stop them together at the time you want. This is likely to be implemented and shipped with Vue 3.1. Check out for more details if it get you interested.

// effect, computed, watch, watchEffect created inside the scope will be collected

const scope = effectScope(() => {
  const doubled = computed(() => counter.value * 2)

  watch(doubled, () => console.log(double.value))

  watchEffect(() => console.log('Count: ', double.value))
})

// dispose all effects in the scope
stop(scope)

Typed Provide / Inject

We have a set of new APIs called provide and inject. It's basically for sharing some context for the component's children to consume and reuse. They are two separate function, which means TypeScript can't actually infer the types for each context automatically.

But here we have a solution for that. Vue provided a type helper called InjectionKey where you can define a symbol that carries the type you want, and then it will hint provide and inject to have proper autocompletion and type checking.

// context.ts
import type { InjectionKey } from 'vue'

export interface UserInfo {
  id: number
  name: string
}

export const injectKeyUser: InjectionKey<UserInfo> = Symbol()

For example, here I defined an interface UserInfo which contains two properties. And I exported a symbol with the InjectionKey type.

// parent.vue
import { provide } from 'vue'
import { injectKeyUser } from './context'

export default {
  setup() {
    provide(injectKeyUser, {
      id: '7', // type error: should be number
      name: 'Anthony'
    })
  }
}

In usage, I can use the provide function to provide the data with key. Can you see here I get a type error that the id should be a number. So I can catch up the error right away before it goes to production.

// child.vue
import { inject } from 'vue'
import { injectKeyUser } from './context'

export default {
  setup() {
    const user = inject(injectKeyUser)
    // UserInfo | undefined

    if (user)
      console.log(user.name) // Anthony
  }
}

And in the child component, we can use the inject function with the key as well. You can see it correctly infers the type UserInfo and so as its property.

Shared State

With the flexibility of Vue's Composition API, sharing state is actually quite simple.

// shared.ts
import { reactive } from 'vue'

export const state = reactive({
  foo: 1,
  bar: 'Hello'
})

You can declare some ref or reactive state in a js module, and import them to your components. Since they are using the same instance, the state will be just in sync.

// A.vue
import { state } from './shared.ts'

state.foo += 1

// B.vue
import { state } from './shared.ts'

console.log(state.foo) // 2

But please note this is actually not SSR compatible. In SSR your server will create a new app on each request, where this approach will keep the state persistent across multiple rendering. And normally it's not what we would expect.

Shared State (SSR friendly)

Let's see if we can make a solution for it to work with SSR.

export const myStateKey: InjectionKey<MyState> = Symbol()

export function createMyState() {
  const state = {
    /* ... */
  }

  return {
    install(app: App) {
      app.provide(myStateKey, state)
    }
  }
}

export function useMyState(): MyState {
  return inject(myStateKey)!
}

By using provide and inject, to share the state one the App context, which means it will be created every time when the server doing the rendering. You can see here I have two function, createMyState and useMyState. createMyState will returns a Vue plugin that provide the state to the App. While useMyState is just a wrapper of inject using the same key.

// main.ts
const App = createApp(App)

app.use(createMyState())

// A.vue

// use everywhere in your app
const state = useMyState()

In usage, we can create the state in the main entry and pass it to app.use. Then you can use the hook useMyState everywhere in your components.

If you have ever tried Vue Router v4, it actually uses a similar method to do that like createRouter and `useRouter.

useVModel

One last tip I'd like to share is a utility called useVModel.

export function useVModel(props, name) {
  const emit = getCurrentInstance().emit

  return computed({
    get() {
      return props[name]
    },
    set(v) {
      emit(`update:${name}`, v)
    }
  })
}

It's just a simple wrapper to the component model to bind with props and emit. This is actually a lifesaver to me.

export default defineComponent({
  setup(props) {
    const value = useVModel(props, 'value')

    return { value }
  }
})

We can take a look at the code, you can see we used a writable computed. When accessing the value, we forward the value of props to it, and when writing, we emit out the update event automatically so you can use just like a normal ref.

<template>
  <input v-model="value">
</template>

Even more, we can actually bind into our children elements's v-model very easily.

Vue 2 & 3

That's all the tips and patterns I have for today.

As you might think those are for Vue 3 only, but actually they also applies for Vue 2!

@vue/composition-api Lib

In case you didn't know that, if you are still on Vue 2 but want to start using the Composition API, here we offered an official plugin that enables the Composition API for your Vue 2 app. Give it a try if you haven't.

vuejs/composition-api

import VueCompositionAPI from '@vue/composition-api'
import Vue from 'vue'

Vue.use(VueCompositionAPI)

import { reactive, ref } from '@vue/composition-api'

Vue 2.7 Upcoming

We also announced our plan for Vue 2.7 recently. Vue 2.7 will be the last minor version of Vue 2 with long time support for existing projects and those who still need IE 11 support. We will back-port Vue 3's new features to Vue 2.7 and migrate the @vue/compositon-api plugin into it. Stay tuned on that.

• Backport @vue/composition-api into Vue 2's core.
• <script setup> syntax in Single-File Components.
• Migrate codebase to TypeScript.
• IE11 support.
• LTS.

Vue Demi Lib

If you are a library author want your libraries to support Vue 2 and 3 with the same codebase. You can try Vue Demi, which eases out the difference between Vue 2 and 3 and auto-detects users' environment.

vueuse/vue-demi

// same syntax for both Vue 2 and 3
import { defineComponent, reactive, ref } from 'vue-demi'

Thank you!

That's all for today.

Due to the time limit, it's a shame that I can not share all I have learned with you. As the Vue composition API is still fairly new, I believe there are more patterns and better practices for us to found.

To find more information, do check out the VueUse org on GitHub and its awesome ecosystem, and follow us on Twitter @vueuse to keep up-to-date with news and tips.

Thank you!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/vue-beijing-2021 https://antfu.me/posts/vue-beijing-2021 Sun, 28 Mar 2021 16:00:00 GMT

This is the transcript of my talk at Vue Beijing

Slides: English ver. | 中文 ver.

Recording: YouTube (English)

Transcript

I guess many of you have already heard about Vite, as the next thing replacing other bundlers like Webpack. Well, it's actually not 100% true. While we are used to "Build with Webpack", and now, more precisely, we are Developing with Vite.

Today I am going to present you with a brief introduction to Vite, the next-generation development tools. And I believe you will find out the answer after it.

What is Vite?

Vite is a French word meaning fast. The initial motivation of it is that Evan You, the creator of Vue, got an idea of making a dev server with hot reload for Vue Single File Component without a bundler. And yeah, after a few days, Vite comes out.

With the name of fast, it has to be fast. And it is.

Let me show you a quick demonstration of how fast it is. On the left-hand side, we have Create React App, and on the right we have Vite. And you can see during I am introducing to them, the Vite app is already ready and playable, while the other one just finishes installing its dependencies. In this demo, we can see we have over 4x faster boot-up speed improvement over Create React App, on the single component starter template. And actually, it's not even showing the full potential of Vite.

So how could Vite be so fast?

First, Vite is opinionated on providing better DX. It assumes that you are using modern browsers for development, so we don't need to have complex transpiling and polyfills involved. Also since your browser already understands Native ES module, we can even skip the bundling process and let the browser do it for us. We also involved with some optimizations to make it even faster, which I will go through them later.

We have a build mode for production powered by rollup. The difference between development and production make Vite capable of having good experiences for both of them.

The Dev Server

In a traditional bundle-based dev server, when we start the server, it will bundle your entire app and the server is ready only until the bundling is finished. In a large-scale app, it could take quite a lot of time.

Native ESM bases server, on the other hand, does need to do the bundling at all. The server is ready immediately and it will only transpile the modules of the pages you have opened on-demanded. So even you have a huge app with thousands of pages, it will be constantly fast as it only needs to transpile the modules for one page.

The transpling is powered by esbuild. It is a transpiler and bundler written in Go and build to native code. It is optimized with speed in mind and utilizes the potential of parallelism. It claims that it can be 10-100x faster than the traditional build tools.

With the support esbuild, we are able to support JSX, TypeScript out-of-the-box.

Dependencies Pre-bundling

Another optimization of Vite is the dependencies pre-bundling. Normally, your dependencies do not change really often unless you are upgrading them, but on the other hand, your user code can change everyday.

So by treating the user code and dependencies differently, we pre bundles your dependencies into a single file standard ESM that can be understood by the browser. In this way, we ease out the difference of packages shipping different js formats like cjs or node favored modules. It also reduced HTTP request overhead and importing waterfall.

And this bundling process is also powered by esbuild, with over 20x faster performance.

Hot Module Replacement

Another important part of Vite is that it has out-of-box hot module replacement support. Whenever you made a change to your code, the HMR is triggered. It's smart enough to know which modules would be affected by the changes and replace them efficiently. And we have first-party support for Vue single-file components and React Refresh.

As Vite is made by Evan, you may think it's only Vue. Well, initially, it was kind of true, but things are different now.

From Vite 2.0, it's now framework-agnostic and Vue is supported through a plugin. It also comes with a bunch of new features and improvements, for example the universal plugin system and first-class SSR. For more details, you check out the links in the slide.

You can use npm init to create the starter project with the official templates. As you can see, we have supported Vue, React, Preact, Lit Element, Svelte, and even vanilla. It's not limited to these, we will keep adding more as we go.

---

Powerful Plugins System

Vite's plugins are compatible with Rollup plugins. This means you can use the huge amount of existing plugins from rollup on Vite.

You can check out this Vite Rollup Plugins site by our team member @patak-js. It lists all the compatibility of popular rollup plugins with some demo and guides of how to use them.

We also have an awesome list that lists Vite plugins for different ecosystems. Check it out, I believe you will find some of them useful to you.

---

Fresh Vue Authoring Experience

I'd like to feature some Vite plugins for Vue that provide the Fresh authoring experience on creating Vue apps.

vite-plugin-pages by @hannoeru

It provides Nuxt.js-like file base routing, with dynamic routes support that can be accessed as the props in the page component.

Only with 3 lines of code, you can set up this feature and use it immediately.

import routes from 'virtual:generated-pages'
import { createRouter } from 'vue-router'

const router = createRouter({ routes })

Check its docs for more.

vite-plugin-components by @antfu

In Vue, writing the name of the component four times in order to import them is kind of a pain for me. So I made this plugin to do the component auto-importing. Now you can put your components under src/components and then use them everywhere without needing to import them. We also have built-in support for auto importing component libraries with minimal configurations. For now, we have supported Vuetify, Ant Design Vue, Element Plus, Vant, and so on.

From:

<script>
import HelloWorld from './src/components/HelloWorld.vue'

export default {
  components: {
    HelloWorld,
  },
}
</script>

<template>
  <HelloWorld msg="Hello Vue 3.0 + Vite" />
</template>

To:

<template>
  <HelloWorld msg="Hello Vue 3.0 + Vite" />
</template>

vite-plugin-icons by @antfu

Another one is vite-plugin-icons. It allows you to use icons from any icon set, for example, Material design icons and Font awesome. Which the on-demand spirit of Vite, this will only ship with the icons that you actually use. So you can say goodbye to the old-school icon font approach that downloads a huge font with all the icons that you don't actually need.

It also works well with the component auto importing, and you can use them like magic.

<template>
  <i-carbon-accessibility />
  <i-mdi-account-box style="font-size: 2em; color: red" />
</template>

vite-plugin-windicss by @antfu

If you have ever used Tailwind CSS, you must aware it's actually quite slow in the dev server as it ships all the utilities with megabytes of CSS to your client. This becomes the slowest part of my Vite app.

Luckily, we have a new thing called Windi CSS, which you can think of it as the on-demand Tailwind CSS. Instead of shipping all the combinations of classes and purge them down later. It only generates the classes you actually use. Turns out it can be 20-100x faster than the traditional Tailwind. While it's on-demand, it also opens up more features like unit auto-inferring. Do check it out if you are using Tailwind.

Try them all

If you found them interesting and want to try it yourself, I also made a starter template call Vitesse, with all of them included and more features. Pull it down and check out.

These are only a small part of our plugins ecosystem, we have more of them available in the awesome list do remember to check them out.

Vue 2 for Vite

If you are still using Vue 2, no worries, we have your covered!

While the official Vue plugin is for Vue 3. Another Vite team member @underfin made the plugin vite-plugin-vue2 for Vue 2. With a single line in the config, you are good to go. It's been wildly adapted already, for example, Nuxt 2 for Vite is powered on it.

In the awesome list, we have marked the compatibility for each plugin of the Vue 2 support. Many of them are isomorphic to both Vue 3 and 2. If you are going to try Vue 2, you don't want to miss it.

Legacy Browser Support

Vite uses native ESM on both development and production, but if you want to enable legacy browsers that do not support ESM, no problem, we have it.

There is an official plugin @vitejs/plugin-legacy that uses Babel and System JS to transform the modules for legacy support.

// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default {
  plugins: [
    legacy({
      targets: ['defaults', 'not IE 11']
    })
  ]
}

Check out the docs for more details.

---

Ecosystem and Community

Then, let's talk a bit about the community.

I bet you already have this question - Vite is great, but what does Vite mean for the existing Vue ecosystem? Let me help you to find it out.

How about VuePress? It's actually already supported Vite in the version 2 beta! In v2, you can swap the engine between Webpack and Vite, and have the instant reload from Vite. Check out the docs for how it works!

As for Nuxt, we actually have some exciting news! The upcoming Nuxt 3 will support interchangeable engines between Webpack and Vite. And you can get the benefit of the huge Nuxt community. It will be available as a public beta at Q2 this year. They also release an experimental project for Nuxt 2 to support Vite where you can try it today.

About Vue CLI, as Evan mentioned, we weren't intended to replace Vue CLI with Vite, but it turns out it could be. The long-term goal of Vue CLI is to support Vite with a powerful scaffolding capability and easier to get started.

We also have a community plugin vue-cli-plugin-vite that enables Vite support in Vue CLI that you can play with it today.

---

Higher-level Integrations

We also have a community plugin that enables Vite support in Vue CLI that you can try today. And on top of Vite, we are now having some cool higher-level integrations tools.

The first one is VitePress, a Vite and Vue powered static site generator. Similar to VuePress, but with more opinionated pre-configuration. This project is still experimental but already served as the generator for many official documentation sites, including the Vite docs itself.

Ream is a Vite-based framework with the support of fast SSR built-in by @egoist. At the time I am preparing these slides, it's doing a rewrite to make not only for Vue but also for any frameworks. Stay tuned on that.

Edge side rendering becomes quite popular recently, and we are also having a tool called Vitedge by @frandiox to bring it to Vite. Take a look at its repo as well.

Vite also supports backend integrations, now we already have Vite Ruby by @ElMassimo and Laravel Viteby @innocenzi in the community. They leverage Vite to serve the front-end and benefit from Vite's fast performance.

You can also set up your own backend integrations easily by following the docs below.

---

Upcoming

Not only for Vue and the new tools. The tools you love are also going to support Vite. Here are some news for upcoming things I'd like to share with you.

Svelte Kit is the next official build tools for Svelte, and they are moving from Snowpack to Vite. It's in the early beta now and you can check it out if it got you interested.

Cypress is also adding the first-class Vite support. I believe we can see it ready within this year.

And Storybook is also exploring the interchangeable engines for Vite and Snowpack. You can also keep an eye on that.

---

Start Vite today!

We are waiting for you to join our community and start playing with us!

Just firing up this command in your terminal to get the first impressions!

npm init @vitejs/app

That's all for today. Join the discord to chat with us and follow us on Twitter to get the latest news.

See you in the community, thank you!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/reflection-of-speaking-in-public https://antfu.me/posts/reflection-of-speaking-in-public Sat, 27 Mar 2021 16:00:00 GMT

Disclaimer: All the words are only representing my opinions. None of them applies to the Windi CSS's author nor the team.

The past two weeks have been tough for me. I have caused some drama where it might not need to be like that. The guilty keeps spinning around my head, asking myself if I made the right decisions, or what can be better if I am not taking it this way.

I guess I am still immature and naive to the community. I was so lucky to get so many of you enjoying my work, subscribing to my feeds, more than I could ever imagine. I was not aware of how the expression of myself could have so much effect on others.

I couldn't help myself not to think about what's the best outcome we could possibly have, if both of us could make better decisions. Maybe we can have a world that Windi and Tailwind JIT could co-exist, helping and inspiring each other, like react and preact. Windi could be the community-driven playground/experiment field to try out new ideas and ships rapidly, and Tailwind could take those good enhancements that have been proven in Windi and make it more solid and ready for production. That might be the things we should see them happen in the open-source rather than the current drama and sadness.

Not saying I think what Tailwind does is acceptable to me. I believe there isn't something called "original ideas" - we are all learning and inspiring from others. Giving proper credit to where the inspirations come from is the least thing we can do to make open source a better place and encourage more people to share their ideas/code in the public space.

But after these days of reflection, I think I could be more mature and calm to handle this better and prevent all of these from happening. Here are some thoughts for myself to be aware of not doing the same thing again.

• I should have more active communication with Adam and Tailwind on this thing before I spoke it out in public. Or even better before they make the announcement.
• I should not take this personally and emotionally, and not assail Adam and the Tailwind team.
• When Tailwind appended the mention in the comments, I should call it over and move on. Instead of bringing this up once again.
• I should ask for the opinions from the Windi team before going public.

I had failed to make none of these, resulting in the worst outcome. I was irresponsible to do this for both the community and the Windi team who have trusted me.

My sincere apologies to Adam, the Tailwind team, the Windi team, and everybody involved with this drama.

I don't know what this will end with, but fighting is definitely not something I meant to see. This drama was started by me, and I wish we can call it an end. I don't really want to see such things happening again, but I truly wish I can handle it better next time taking the lesson I have learned today. After all, I still believe people here in open source are with good willing to make things better for everyone.

Thank you for reading through. And hope you could understand and forgive this naive and immature boy.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/type-your-config https://antfu.me/posts/type-your-config Wed, 24 Mar 2021 16:00:00 GMT Configurations can be quite complex, and sometimes you may want to utilize the great type checking that TypeScript provided. Change your xxx.config.js to xxx.config.ts is not an ideal solutions as you will need to have a Node.js register involved to transpile it into JavaScript and some tools might not support doing that way. Fortunately, TypeScript also support type check in plain JavaScript file with JSDoc. Here is an example of Webpack config with type checks:

// webpack.config.js
// @ts-check

/**
 * @type {import('webpack').Configuration}
 */
const config = {
  /* ... */
}

module.exports = config

Prefect. Everything should work and you can already call it a day.

I have never thought about we can do better, until I saw Vite's approach. In Vite, you can simply have:

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  /* ... */
})

No JSDocs, no need to declare a variable first then export it. And since TypeScript will infer the types even you are using plain JavaScript, it works great with both.

How? The defineConfig is literally a pass-through, but brings with types:

import type { UserConfig } from 'vite'

export function defineConfig(options: UserConfig) {
  return options
}

defineConfig exists in the runtime, so it works for JavaScript even if the types get truncated. This is really just some small details of DX, but I would wish more tools could adapt this approach and make the type checking more approachable and simpler.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/windicss-and-tailwind-jit https://antfu.me/posts/windicss-and-tailwind-jit Thu, 18 Mar 2021 16:00:00 GMT

Disclaimer: All the words are only representing my opinions. None of them applies to the Windi CSS's author nor the team.

Congrats Tailwind, and thanks for NOT mentioning Windi CSS at all for your new ideas.

I appreciated how did Tailwind power my apps and make my life easier. But this really changed my mind about how I see the people behind it.

Check out https://t.co/kcEzm5Ickp by @satireven. https://t.co/tkJCy8Pgb3

— Anthony Fu (@antfu7) March 15, 2021

I spoke out for Windi CSS just because keeping silence on this also means we are encouraging such things to happen again in the open-source community.

Tailwind was once my favorite CSS framework and I was really happy to see we made it works on Vite much faster with @voorjaar's astonishing Windi CSS compiler. But I was totally unexpected to see that end up being like this. Don't get me wrong, it's great to see Tailwind's long pain get solved officially with Tailwind JIT and benefit the community. What I am saying is that Tailwind used/inspired by Windi's idea without even mentioning Windi CSS once and claiming it's their own ideas (until 20min after my tweets about that, they appended two tweets in the comments, mentioned about Windi but still implies it's their idea. That's all we got). No official reply of this whole thing, not updates to their repo's README, at all.

I don't want to speculate what's the reasons or motivations behind it, all I know is that I will not use any products from Tailwind Labs anymore. If you think I was reacting too much or it was not a big deal, then I truly wish such things would never happend on you once again.

I remember the day when Windi got blown up on Twitter, @adamwathan called me and asked me about how Windi CSS works and he is happy to make it official. And yeah, I was excited to see things are improving for the whole community, so I shared all I know with him.

1/n https://t.co/Ho1DddqA33

— Anthony Fu (@antfu7) March 15, 2021

It's almost impossible for a small org like us to fight with the giant Tailwind. But we will not give up just because of this.

Let's see and good luck.

— Anthony Fu (@antfu7) March 15, 2021

On the bright side, Windi pushed Tailwind to make the JIT and improved the DX and Tailwind forced Windi to be independent and evolving to not being a "Tailwind accessory" any longer.

There is another community based CSS-in-JS alternative called Twind, which you definitely want to check out (they are working closely with Windi to bring an uniformed community standard/spec of our DSL, cheers @sastan!).

As for myself, I will spend more time on working with Windi CSS to make it even better. Here is some of exciting things we are working on:

Spoiler of the new piece of our playground - interactive selector.

I always find myself trouble picking the directions of rounded corners and looking up for a huge table of all the possible combinations could be inefficient. So yeah :)

rounded-1/2 is new in Windi CSS btw 😉 https://t.co/f841k9BgPF pic.twitter.com/pVIlB2X1nY

— Anthony Fu (@antfu7) March 16, 2021

Limitation? Let's break it!💥

Upcoming feature in @windi_css 🍃
"Design in DevTools"!

Whenever you made changes to the classes in DevTools, the CSS updates automatically for you, on-demand as always :)

Idea credit goes to @maximomussini 🙌 pic.twitter.com/DHf2h5wroM

— Anthony Fu (@antfu7) March 17, 2021

Thanks for reading though. Don't feel any pressure about using any tools that you needed. I choose not to use them just because my personal preference. I don't want to force anyone to switch their stack because reading this post, we will keep improve it and show you which is the better one you should use :)

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/typed-provide-and-inject-in-vue https://antfu.me/posts/typed-provide-and-inject-in-vue Fri, 05 Mar 2021 16:00:00 GMT I didn't know that you can type provide() and inject() elegantly until I watched Thorsten Lünborg's talk on Vue Amsterdam.

The basic idea here is the Vue offers a type utility InjectionKey will you can type a Symbol to hold the type of your injection values. And when you use provide() and inject() with that symbol, it can infer the type of provider and return value automatically.

For example:

// context.ts
import type { InjectionKey } from 'vue'

export interface UserInfo {
  id: number
  name: string
}

export const InjectKeyUser: InjectionKey<UserInfo> = Symbol()

// parent.vue
import { provide } from 'vue'
import { InjectKeyUser } from './context'

export default {
  setup() {
    provide(InjectKeyUser, {
      id: '117', // type error: should be number
      name: 'Anthony',
    })
  },
}

// child.vue
import { inject } from 'vue'
import { InjectKeyUser } from './context'

export default {
  setup() {
    const user = inject(InjectKeyUser) // UserInfo | undefined

    if (user)
      console.log(user.name) // Anthony
  },
}

See the docs for more details.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/color-scheme-for-vscode-ext https://antfu.me/posts/color-scheme-for-vscode-ext Mon, 01 Mar 2021 16:00:00 GMT There is currently no API to access colors of current theme in VS Code Extensions, nor the meta information of them. It frustrated me for a long while, until today I came up with a dirty but working solution.

Since most of the themes follow the conversions of having Light or Dark in their names. Then we can have:

import { workspace } from 'vscode'

export function isDarkTheme() {
  const theme = workspace.getConfiguration()
    .get('workbench.colorTheme', '')

  // must be dark
  if (theme.match(/dark|black/i) != null)
    return true

  // must be light
  if (theme.match(/light/i) != null)
    return false

  // IDK, maybe dark
  return true
}

Simple, but surprisingly, it works really well. This is used for my Browse Lite extension to inject the preferred color schema matching with VS Code's theme. And also Iconify IntelliSense for VS Code to update icons color with the theme.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/types-for-sub-modules https://antfu.me/posts/types-for-sub-modules Mon, 01 Mar 2021 16:00:00 GMT When you build multiple entries in a single package, you exports them with exports syntax. Like

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./foo": {
      "types": "./dist/foo.d.ts",
      "import": "./dist/foo.mjs",
      "require": "./dist/foo.cjs"
    }
  }
}

Then tho you provide types field for the sub modules, most of the users still got the error:

Cannot find module 'my-pkg/foo' or its corresponding type declarations.

Well that's because the types field in exports will only be resolved when you add "moduleResolution": "NodeNext" to the tsconfig.json file. Which might cause more issue since not all the packages are up to date.

So when you trying to import my-pkg/foo, TypeScript actually looking for the foo.d.ts file under your package root instead of your dist folder. One solution I been used for a long time is to create a redirection file that published to npm, like:

// foo.d.ts
export { default } from './dist/foo.d.ts'
export * from './dist/foo.d.ts'

Which solve the problem, but also making your root directory quite messy.

Until @tmkx shared me this solution:

{
  "typesVersions": {
    "*": {
      "*": [
        "./dist/index.d.ts",
        "./dist/*"
      ]
    }
  }
}

Good day! Reference

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/match-quotes-in-pairs https://antfu.me/posts/match-quotes-in-pairs Sun, 28 Feb 2021 16:00:00 GMT In JavaScript, single quotes('') and double quotes("") are interchangeable. With ES6, we now even have backticks(``) for template literals. When you want to write a quick script to find all the strings without introducing a heavy parser, you may think about using RegExp. For example, you can have:

/['"`](.*?)['"`]/g

It works for most of the case, but not for mixed quotes:

'const a = "Hi, I\'m Anthony"'.match(/['"`](.*)['"`]/)[1] // "Hi, I"

You have to make sure the starting quote and ending quote are the same type. Initially I thought it was impossible to do it in RegExp, or we have to do like this:

/'(.*?)'|"(.*?)"|`(.*?)`/g

That's definitely a bad idea as it makes you duplicated your notations. Until I found this solution:

/(['"`])(.*?)\1/g

\1 is a Backreferences to your first group, similarly you can have \2 for the second group 2 and \3 for the third, you got the idea. This is exactly what I need! Take it a bit further, to exclude the backslash escaping, now we can have a much reliable RegExp for extracting quoted texts from any code.

/(["'`])((?:\\\1|(?:(?!\1)|\n|\r).)*?)\1/g

You can find it running in action on my vite-plugin-windicss.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/match-chinese-characters https://antfu.me/posts/match-chinese-characters Thu, 25 Feb 2021 16:00:00 GMT When you need to detect if a string contains Chinese characters, you would commonly think about doing it will RegExp, or grab a ready-to-use package on npm.

If you Google it, you are likely end up with this solution:

/[\u4E00-\u9FCC\u3400-\u4DB5\uFA0E\uFA0F\uFA11\uFA13\uFA14\uFA1F\uFA21\uFA23\uFA24\uFA27-\uFA29]|[\uD840-\uD868][\uDC00-\uDFFF]|\uD869[\uDC00-\uDED6\uDF00-\uDFFF]|[\uD86A-\uD86C][\uDC00-\uDFFF]|\uD86D[\uDC00-\uDF34\uDF40-\uDFFF]|\uD86E[\uDC00-\uDC1D]/

It works, but a bit dirty. Fortunately, I found a much simpler solution today:

/\p{Script=Han}/u

!!'你好'.match(/\p{Script=Han}/u) // true

It's called Unicode property escapes and already available in Chrome 64, Firefox 79, Safari 11.1 and Node.js 10.

All available scripts here.

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/netlify-redirects https://antfu.me/posts/netlify-redirects Sat, 20 Feb 2021 16:00:00 GMT Domains Redirects

On Netlify, you can setup multiple domains for a site. When you add a custom domain, the xxx.netlify.app is still accessible. Which would potentially cause some confusion to users. In that way, you can setup the redirection in your netlify.toml file, for example:

[[redirects]]
from = "https://vueuse.netlify.app/*"
to = "https://vueuse.org/:splat"
status = 301
force = true

• * and :splat mean it will redirect all the sub routes as-is to the new domain.
• force = true specifying it will always redirect even if the request page exists.

Site Names Redirects

2021/02/20

Unlike domain redirection, sometimes you would need to rename the Netlify subdomain name (a.k.a site name), for example xxx.netlify.app to yyy.netlify.app. After you do the rename, people visiting xxx.netlify.app will receive a 404. And since you no longer have controls over xxx.netlify.app, you can't just setup a redirect in your new site.

A solution here is to create a new site with your original name xxx and upload the redirection rules. In this case, we can have netlify.toml like this:

[[redirects]]
from = "*"
to = "https://yyy.netlify.app/:splat"
status = 301
force = true

Note you don't have to link a repo to that, Netlify offers a great feature that let you drag and drop for static files and serve as a site. So you can just save netlify.toml and upload it, rename the site to your original name. The redirection is done!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/rewrite-in-vite https://antfu.me/posts/rewrite-in-vite Sun, 31 Jan 2021 16:00:00 GMT [[toc]]

The page you are looking at is now powered by Vite. This is something I want to do for a long while since Vite came out, and it's finally done. As I have mentioned in my first blog post, it was powered Gridsome using Vue 2. With this overhaul, I can now take full advantage of Vue 3 and the Composition API with the new <script setup> SFC style.

The reason for it taking me so long to do this is because I am busy (enjoy) doing yak shaving, for the tools I need to build this site.

Fundamentals

It begins with me trying to improve the DX using icons in this post. At that time, Vue 3 just into RC, and Vite didn't reach 1.0 yet. Hearing a lot of how good Vue 3 and Vite are, I decided to give them a try on building the icon site I want to build for a long time. Since Vite is such a brand new thing, there aren't many tools/plugins out there, the ecosystem was way far from what Webpack has. I took that as a chance for me to dive deep into how Vite works while doing some contributions the ecosystem. Here is a few tools I made while building the app Icônes:

• vite-plugin-components - On-demand components auto importing for Vite.
• vite-plugin-pwa - Zero-config PWA for Vite.
• vite-plugin-purge-icons - Bundles icons on demand, with a Vite plugin.

Also found some awesome tools form the community:

• Iconify - Universal icon framework, by @cyberalien.
• vite-plugin-voie - File system based routing for Vite, by @brattonross.
• vite-plugin-pages - Another file system based route generator, by @hannoeru.

With them, I got the fundamentals of a Vite project setup. Nuxt-liked file-based routing and component auto importing. I was quite satisfied with it as I could focus more on the content and logic rather than getting distracted by the routes setup and component registration.

I also learned Tailwind CSS as a replacement of the missing UI component libraries for Vue 3. It turns out that I really enjoy Tailwind's way of rapid prototyping. As I got more control over styling things, it makes me think more about the design rather than just applying the default theme of the components library I use.

Dark Mode

Dark mode is supported as an experimental feature in Tailwind CSS v1.8 and shipped in v2.0. It supports two modes for you to choose from - media and class. media is something that works out-of-box, it changes based on users' system preference. But the limitation is that you can't toggle it manually as you want. So I went with class mode where I have more controls over it. But that also means I would need to implement the toggling logic myself.

With the power of Vue's Composition API, I am able to combine the best parts of them - reactive to the system's preference while being able to override manually.

import { usePreferredDark, useStorage } from '@vueuse/core'

const preferredDark = usePreferredDark()
const colorSchema = useStorage('color-schema', 'auto')

export const isDark = computed({
  get() {
    return colorSchema.value === 'auto'
      ? preferredDark.value
      : colorSchema.value === 'dark'
  },
  set(v: boolean) {
    if (v === preferredDark.value)
      colorSchema.value = 'auto'
    else
      colorSchema.value = v ? 'dark' : 'light'
  },
})

watch(
  isDark,
  v => document.documentElement.classList.toggle('dark', v),
  { immediate: true },
)

Click it to try 👇🏼

If you would like to use it in your own apps, I also extract the logic above into useDark() in VueUse. Where you can simply use like this:

import { useDark, useToggle } from '@vueuse/core'

const isDark = useDark()
const toggleDark = useToggle(isDark)

Markdown

After building Icônes, I started working on the Codecember project with @octref, an initiative of learning and creating generative arts in December. With the spirit of dogfooding, we chosen Vite for building the site. In Codecember we will need to have a prompt every day with some texts, code snippets, and demos. This comes with the problem that Vite does not have a plugin for handling markdown files at that moment, so of course, I made one myself.

• vite-plugin-vue-markdown - Markdown for Vite.

Basically, it uses markdown-it to transform markdown into HTML and feed it into Vue's template compiler. As the generated template is handled by Vue, we can easily support Vue components inside Markdown.

Syntax Highlighting

Getting syntax highlight works in dark mode isn't an easy task as well. Shiki inlined all the colors into the HTML so you would not be bored by the CSS namespace pollution, but that also means it will be really hard to get the colors aware of your global color scheme. Prism on the other hand, uses the classes combining the CSS theme to do the job. It's easier to merge two color schemes and make them aware of the dark trigger. The bad thing is, themes are often wrote by different authors with different styles of coloring and styling things. Sometimes, even the font and spacing could be different across different themes. If you ever ran into a similar situation, you should know what I mean. If you don't (lucky you!), see Prism's themes collection(prism-vs.css and prism-vsc-dark-plus.css for example).

Fight with them for a while you might be able to ease the misalignment eventually. But what if we can have a smarter way to do this?

• prism-theme-vars - A customizable Prism.js theme using CSS variables.

Instead of dealing with the lengthy CSS theme, now you can have one in less than 20 lines of CSS variables. For example:

@import 'prism-theme-vars/base.css';

:root {
  --prism-foreground: #393a34;
  --prism-background: #fbfbfb;
  --prism-comment: #b8c4b8;
  --prism-string: #c67b5d;
  --prism-literal: #3a9c9b;
  --prism-keyword: #248459;
  --prism-function: #849145;
  --prism-deleted: #a14f55;
  --prism-class: #2b91af;
  --prism-builtin: #a52727;
  --prism-property: #ad502b;
  --prism-namespace: #c96880;
  --prism-punctuation: #8e8f8b;
}

To have it supports dark mode is extremely simple as well:

html:not(.dark) {
  --prism-foreground: #393a34;
  --prism-background: #f8f8f8;
  --prism-comment: #758575;
  --prism-namespace: #444444;
  --prism-string: #bc8671;
  --prism-punctuation: #80817d;
  --prism-literal: #36acaa;
  --prism-keyword: #248459;
  --prism-function: #849145;
  --prism-deleted: #9a050f;
  --prism-class: #2b91af;
  --prism-builtin: #800000;
}

html.dark {
  --prism-foreground: #d4d4d4;
  --prism-background: #1e1e1e;
  --prism-namespace: #aaaaaa;
  --prism-comment: #758575;
  --prism-namespace: #444444;
  --prism-string: #ce9178;
  --prism-punctuation: #d4d4d4;
  --prism-literal: #36acaa;
  --prism-keyword: #38a776;
  --prism-function: #dcdcaa;
  --prism-deleted: #9a050f;
  --prism-class: #4ec9b0;
  --prism-builtin: #d16969;
}

That's all. You can also play with the themes in the Playground and make some your own within 5 mins. I created my first code theme in my life using it, which is also exactly what you are looking at :)

Serve-Side Generatation (SSG)

While Codecember is more like a site than an app, we would need to do some server-side generation to improve our SEO. Read quite a lot of code from VitePress, I came up with this plugin:

• vite-ssg - Server-side generation for Vite.

The idea here is fairly simple: bundle the app entry, then for each route, dump the app using APIs from the @vue/server-renderer package. Simplified code here:

import { renderToString } from '@vue/server-renderer'

const createApp = required('dist-ssr/app.js')

await Promise.all(
  routes.map(async (route) => {
    const { app, router, head } = createApp(false)

    router.push(route)
    await router.isReady()

    const appHTML = await renderToString(app)
    const renderedHTML = renderHTML(indexHTML, appHTML)

    await fs.writeFile(`${route}.html`, renderedHTML, 'utf-8')
  })
)

The full code can be found here.

With the @vueuse/head package made by @egoist, I made the document head/meta manipulation in SSG with ease. Combining with vite-plugin-vue-markdown, you can even use the frontmatter to set the meta (title, description, og:image, etc.).

<script setup>
  import { useHead } from '@vueuse/head'

  useHead({
    title: 'Website Title',
    meta: [
      {
        name: 'description',
        content: 'Website description',
      },
    ],
  })
</script>

The Vite Template

I found myself making small web apps frequently. Setting up plugins and configs for Vite kinda becomes the bottleneck for me to make my idea landded. So combining with those tools I am using, I made an opinionated template for myself but unexpectedly got quite some good feedback:

• Vitesse - Opinionated Vite Starter Template

This Website

This site is made from Vitesse combining with all the tools I mentioned above. To be honest, even making a static site generator right is something hard to me, not to mention that most of the hard parts are already handled by Vite. I am really happy to see so many things I have learned and crafted along the way. And glad I can make these contributions to the Vite ecosystem, that someone could find my work useful for building their apps.

Thanks

I can't make all these happened without the help/support from the great community, thank y'all!

Also want to have some special thanks to people made significant contributions towards these projects 🙌 (A-Z)

• @hannoeru
• @matias-capeletto
• @privatenumber
• @sibbng

Appreciation to my sponsors as well for supporting my works:

And thank you for reading through!

This site is now open sourced at antfu/antfu.me

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/destructuring-with-object-or-array https://antfu.me/posts/destructuring-with-object-or-array Wed, 21 Oct 2020 16:00:00 GMT [[toc]]

Destructuring is a JavaScript language feature introduced in ES6 which I would assume you already familiar with it before moving on.

We see it quite useful in many scenarios, for example, value swapping, named arguments, objects shallow merging, array slicing, etc. Today I would like to share some of my immature thoughts on "destructuring" in some web frameworks.

I am a Vue enthusiast for sure and I wrote a lot of my apps using it. And I did write React a while for my previous company reluctantly. As the Vue 3.0 came out recently, its exciting Composition API provides quite similar abilities for abstracting. Inspired by react-use, I wrote a composable utility collection library early this year called VueUse.

Similar to React hooks, Vue's composable functions will take some arguments and returns some data and functions. JavaScript is just like other C-liked programming languages - only one return value is allowed. So a workaround for returning multiple values, we would commonly wrap them with an array or an object, and then destructure the returned arrays/objects. As you can already see, we are having two different philosophies here, using arrays or objects.

Destructuring Arrays / Tuples

In React hooks, it's a common practice to use array destructuring. For example, built-in functions:

const [counter, setCounter] = useState(0)

Libraries for React hooks would natural pick the similar philosophy, for example react-use:

const [on, toggle] = useToggle(true)
const [value, setValue, remove] = useLocalStorage('my-key', 'foo')

The benefits of array destructuring is quite straightforward - you get the freedom to set the variable names with the clean looking.

Destructuring Objects

Instead of returning the getter and setter in React's useState, in Vue 3, a ref is created combining the getter and setter inside the single object. Naming is simpler and destructuring is no longer needed.

// React
const [counter, setCounter] = useState(0)
console.log(counter) // get
setCounter(counter + 1) // set

// Vue 3
const counter = ref(0)
console.log(counter.value) // get
counter.value++ // set

Since we don't need to rename the same thing twice for getter and setter like React does, in VueUse, I implemented most of the functions with object returns, like:

const { x, y } = useMouse()

Using objects gives users more flexibility like

// no destructing, clear namespace
const mouse = useMouse()

mouse.x

// use only part of the value
const { y } = useMouse()

// rename things
const { x: mouseX, y: mouseY } = useMouse()

While it's been good for different preferences and named attributes can be self-explaining, the renaming could be somehow verbose than array destructuring.

Support Both

What if we could support them both? Taking the advantages on each side and let users decide which style to be used to better fit their needs.

I did saw one library supports such usage once but I can't recall which. However, this idea buried in mind since then. And now I am going to experiment it out.

My assumption is that it returns an object with both behaviors of array and object. The path is clear, either to make an object like array or an array like object.

Make an object behaves like an array

The first possible solution comes up to my mind is to make an object behaves like an array, as you probably know, arrays are actually objects with number indexes and some prototypes. So the code would be like:

const data = {
  foo: 'foo',
  bar: 'bar',
  0: 'foo',
  1: 'bar',
}

let { foo, bar } = data
let [foo, bar] = data // ERROR!

But when we destructure it as an array, it will throw out this error:

Uncaught TypeError: data is not iterable

Before we working on how to make an object iterable, let's try the other direction first.

Make an array behaves like an object

Since arrays are objects, we should be able to extend it, like

const data = ['foo', 'bar']
data.foo = 'foo'
data.bar = 'bar'

let [foo, bar] = data
let { foo, bar } = data

This works and we can call it a day now! However, if you are a perfectionist, you will find there is an edge case not be well covered. If we use the rest pattern to retrieve the remaining parts, the number indexes will unexpectedly be included in the rest object.

const { foo, ...rest } = data

rest will be:

{
  bar: 'bar',
  0: 'foo',
  1: 'bar'
}

Iterable Object

Let's go back to our first approach to see if we can make an object iterable. And luckily, Symbol.iterator is designed for the task! The document shows exactly the usage, doing some modification and we get this:

const data = {
  foo: 'foo',
  bar: 'bar',
  * [Symbol.iterator]() {
    yield 'foo'
    yield 'bar'
  },
}

let { foo, bar } = data
let [foo, bar] = data

It works well but the Symbol.iterator will still be included in the rest pattern.

let { foo, ...rest } = data

// rest
{
  bar: 'bar',
  Symbol(Symbol.iterator): ƒ*
}

Since we are working on objects, it shouldn't be hard to make some properties not enumerable. By using Object.defineProperty with enumerable: false:

const data = {
  foo: 'foo',
  bar: 'bar',
}

Object.defineProperty(data, Symbol.iterator, {
  enumerable: false,
  * value() {
    yield 'foo'
    yield 'bar'
  },
})

Now we are successfully hiding the extra properties!

const { foo, ...rest } = data

// rest
{
  bar: 'bar'
}

Generator

If you don't like the usage of generators, we can implement it with pure functions, following this article.

Object.defineProperty(clone, Symbol.iterator, {
  enumerable: false,
  value() {
    let index = 0
    const arr = [foo, bar]
    return {
      next: () => ({
        value: arr[index++],
        done: index > arr.length,
      })
    }
  }
})

TypeScript

To me, it's meaningless if we could not get proper TypeScript support on this. Surprisingly, TypeScript support such usage almost out-of-box. Just simply use the & operator to make insertion of the object and array type. Destructuring will properly infer the types in both usages.

type Magic = { foo: string, bar: string } & [ string, string ]

Take Away

Finally, I made it a general function to merge arrays and objects intro the isomorphic destructurable. You can just copy the TypeScript snippet below to use it. Thanks for reading through!

Please note this does NOT support IE11. More details: Supported browers

function createIsomorphicDestructurable<
  T extends Record<string, unknown>,
  A extends readonly any[]
>(obj: T, arr: A): T & A {
  const clone = { ...obj }

  Object.defineProperty(clone, Symbol.iterator, {
    enumerable: false,
    value() {
      let index = 0
      return {
        next: () => ({
          value: arr[index++],
          done: index > arr.length,
        })
      }
    }
  })

  return clone as T & A
}

Usage

const foo = { name: 'foo' }
const bar: number = 1024

const obj = createIsomorphicDestructurable(
  { foo, bar } as const,
  [foo, bar] as const
)

let { foo, bar } = obj
let [foo, bar] = obj

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/watch-with-reactivity https://antfu.me/posts/watch-with-reactivity Fri, 18 Sep 2020 00:00:00 GMT [[toc]]

As you probably know, the things I excited most in Vue 3 are the Composition API and the reactivity system. With the Composition API we can reuse logics and states across components or even apps. What's better? The underhood reactivity system is decoupled from Vue, which means you can use it almost everywhere, even without UI.

Here are some proof of concepts for using the reactivity system outside of Vue:

• @vue/lit is a minimal framework wrote by Evan combining @vue/reactivity and lit-html. It can run directly in browsers, with the almost identical experience as Vue Composition API.

• ReactiVue ports Vue Composition API to React. It also provides React's lifecycles in the Vue style.

Furthermore, you can even use Vue's libraries in them. Tested with VueUse and pinia in ReactiVue, and they just work. You can find more details and examples here.

I am also experimenting more possibility of Vue reactivity in other scenarios, for example reactive file system, in a project called tive. It's currently a WIP private repo, but keep tuned, I get more to come 😉!

Understanding @vue/reactivity

"reactive objects" returned by ref() or reactive() are actually Proxies. Those proxies will trigger some actions to track the changes on properties accessing or writing.

For a simplified example,

function reactive(target) {
  return new Proxy(target, {
    get(target, prop, receiver) {
      track(target, prop)
      return Reflect.get(...arguments) // get the original data
    },
    set(target, key, value, receiver) {
      trigger(target, key)
      return Reflect.set(...arguments) // set the original data
    }
  })
}

const obj = reactive({
  hello: 'world'
})

console.log(obj.hello) // `track()` get called
obj.hello = 'vue' // `trigger()` get called

So in this way, vue can be notified when those properties get accessed or when they be modified.

For more detailed explanations, check out the official docs

Computed

Since we are able to know those events, we can start diving into the computed which is where the "reactive" magic start shining.

computed is like a getter that auto collects the reactive dependencies source and auto re-evaluate when they get changed.

For example,

const counter = ref(1)
const multiplier = ref(2)

const result = computed(() => counter.value * multiplier.value)

console.log(result.value) // 2
counter.value += 1
console.log(result.value) // 4

To know how the computed work, we need to dig into the lower level API effect first.

Effect

effect is a new API introduced in Vue 3. Underneath, it's the engine powers the "reactivity" in computed and watch. For the most of the time, you don't need to directly use it. But knowing it well helps you understand the reactivity system much easier.

effect takes the first argument as the getter and a second argument for the options. The getter is the function that collect its deps on each run via their track() hooks. The field scheduler in options provides a way to invoke a custom function when the deps change.

So basically, you can write a simple computed on your own like:

function computed(getter) {
  let value
  let dirty = true

  const runner = effect(getter, {
    lazy: true,
    scheduler() {
      dirty = true // deps changed
    }
  })

  // return should be a `Ref` in real world, simplified here
  return {
    get value() {
      if (dirty) {
        value = runner() // re-evaluate
        dirty = false
      }
      return value
    }
  }
}

If you really interested in how it works in Vue, check out the source code here

Build yourself a watch

We have done the most important APIs in @vue/reactivity now, which is ref reactive effect computed.

Oh wait, we are missing the watch here!

import { watch } from '@vue/reactivity' // does NOT exist!

If you take a look at Vue 3's source code, you will find that watch is actually implemented in @vue/runtime-core, along with the Vue's component model and lifecycles. The main reason for this is that watch is deep bound with the component's lifecycles (auto dispose, invalidate, etc.). But it shouldn't be the thing to keep you from using it outside of Vue.

Let's implement the watch our own!

The Basic

Let's take a look at Vue's watch interface first

const count = ref(0)

watch(
  () => count.value,
  (newValue) => {
    console.log(`count changed to: ${newValue}!`)
  }
)

count.value = 2
// count changed to: 2!

With the knowledge of effect, it's quite straight forward to implement

function watch(getter, fn) {
  const runner = effect(getter, {
    lazy: true,
    scheduler: fn
  })

  // a callback function is returned to stop the effect
  return () => stop(runner)
}

Watch is lazy by default in Vue, you can add the third options to give control to the users.

Watch for Ref

You may also notice that the Vue's watch also allows passing the ref directly to it.

watch(
  count,
  () => { /* onChanged */ }
)

For that, just wrap it into a getter will do

function watch(source, fn) {
  const getter = isRef(source)
    ? () => source.value
    : source

  const runner = effect(getter, {
    lazy: true,
    scheduler: fn
  })

  return () => stop(runner)
}

Watch Deeply

One other great feature about watch is that it allows you to watch on deep changes.

const state = reactive({
  info: {
    name: 'Anthony',
  }
})

watch(state, () => console.log('changed!'), { deep: true })

state.info.name = 'Anthony Fu'
// changed!

To implement this feature, you need to collect the track() events on every nested property. We can achieve that with a traverse function.

function traverse(value, seen = new Set()) {
  if (!isObject(value) || seen.has(value))
    return value

  seen.add(value) // prevent circular reference
  if (isArray(value)) {
    for (let i = 0; i < value.length; i++)
      traverse(value[i], seen)
  }
  else {
    for (const key of Object.keys(value))
      traverse(value[key], seen)
  }
  return value
}

function watch(source, fn, { deep, lazy = true }) {
  let getter = isRef(source)
    ? () => source.value
    : isReactive(source)
      ? () => source
      : source

  if (deep)
    getter = () => traverse(getter())

  const runner = effect(getter, {
    lazy,
    scheduler: fn
  })

  return () => stop(runner)
}

Done! The thing left to do is to polish, adding overloads to make it more flexible, add more options to get better control, and handle some edge cases. Then you should get yourself a good start for using a custom watch!

Lifecycles

In Vue, computed and watch will automatically bind their effect runner to the current component instance. When the component get unmounted, the effects bond to it will be auto disposed. More specially, you can read the source code here.

Since we don't have an instance, if you want to stop those effects, you have to do them manually. When you have multiple effects in used, to stop them together, you have to manually collect them together. One easier way is to mock similar lifecycles like Vue. This requires some amount of works, I will explain that in another blog post. Please keep tuned.

Take Away

Thanks for reading! And hope it is helpful for you to understand and better play with the Vue reactivity system. If you want to have the watch outside of Vue, I made one for you (much more robust than the examples above for sure).

npm i @vue-reactivity/watch

Have fun ;P

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/journey-with-icons https://antfu.me/posts/journey-with-icons Sun, 16 Aug 2020 16:00:00 GMT [[toc]]

Update Sep. 2021: Journey with Icons Continues

TL;DR

To solve the pain I faced in using icons for the web, I built the following tools to make the DX better.

Apps

• Icônes - Icon Explorer with Instant Fuzzy searching
• Iconify IntelliSense - VS Code Extension for inline icon previewing
• Vitesse - An Opinionated Vite Starter Template

Tools

• PurgeIcons - Bundles icons on demand
• SVG Packer - Pack SVGs to Icon Fonts - In Browser

Would be nice if you are willing to give them a try. As there are still a lot of works to be done, contributions are greatly welcome :)

Journey with Icons

I make websites and small web-based utilities from time to time. Every time I build them, I take care of the design by myself. Amount of the different aspects, icons always play a big role to me. Material Design Icons is the icon set I used most overtime, it has an excellent design foundation from Google and a wide range of icons maintained by the community. And the most important fact is that it has a complete tooling ecosystem - svgs with js, web fonts or even being built-in supported by Vuetify. I could just plugin it in most any kind of apps with very low effort.

However, if you want to try some other icon sets for different looks & feels, you may not be that lucky. Many awesome icon-sets only offer SVGs for download and need to be manually imported to your projects. This could be a laborious and time-consuming work, even just preview them on your apps.

Fortunately, I found Iconify - a unified icons framework that offers over 6,000 icons from 80+ popular icon sets with a single CDN entry and on demand loading. The usage would be something like this:

<!--Import Framework-->
<script src="https://code.iconify.design/1/1.0.7/iconify.min.js"></script>

<!--Use an icon from Font Awesome-->
<span class="iconify" data-icon="fa:home"></span>

<!--Use another icon from Material Design Icons-->
<span class="iconify" data-icon="mdi:flask"></span>

It's done. You get access to all the 6,000 icons with in an unfied syntax. As it's on-demand, you can switch your icon systems whenever you want without worrying about the setup or the bundle size. It's also framework independent, which means you can use it in Vue, React, Svelte, plain html or whatever you want.

This looks so good and the story should end here, however, it does have some limitations. As it's loaded on demand via web queries with its icon services, there will be a visible delay for icons to be loaded on the first page, especially when users have unstable connections to the Iconify servers. Also, you might have some logic to change icons with user interactions, Iconify will only start to request the icon when you actually rendered the id into the DOM. This causes some flickers on the icon switching which you possibly want to avoid.

The solution for this is quite straightforward, preloading the icons and the icon rendering could become synchronized. However, loading the entire icon set will impact your bundle size while manually picking what you used could be laborious and make it less flexible.

PurgeIcons

Inspired by PurgeCSS, I made the tool called PurgeIcons. It statical analyzes your code and generates the icon bundle on-demand.

Along with the Vite plugin, you can simplify import this inline in your app's entry, and the icons you use will be bundled into your code and load them synchronously.

import { createApp } from 'vue'
import App from './App.vue'

import '@purge-icons/generated' // <-- This

createApp(App).mount('#app')

It also provides a CLI tool and plugins for Webpack and Rollup. More frameworks support like Vue CLI, Nuxt, Gridsome or even plain html are coming soon.

With it, the tooling is kinda perfect to me now - I can use any icons without any compromise in the runtime. If you want to give it a try, I also made a pre-configured start template 🏕 Vitesse with PurgeIcons built-in.

Icon Searching

The tooling gets solved, here comes to my another pain for a long time - searching for icons.

I live in China, my network conditions are usually quite unstable for oversee connections. It often took me around 30 seconds to get the searching in Material Design Icons or Iconify. And for most of the time, you won't get the perfect icons on your first try. Repeating searching for multiple times with a huge delay is just killing me.

And so, I finally get some time and motivation to work on making one my own recently. Also considering this being a chance for me to try Vue 3 + Vite and to learn Tailwind CSS.

Icônes

By the power of Iconify, I can only ship with the icon IDs and leave the icon loading task to Iconify. In this way, searching could be done locally - instantly.

With Iconify's data collection, it can get access to all the 80+ icon sets within a single place.

I also made a small utility called SVG Packer for Icônes. With it, you can select the icons you want and pack them into ready to used icon fonts.

Tips: You can also copy the icons as Vue or React components

Try it out if you haven't. A fully-offline electron version is also coming soon.

Editor Support

Browsing and searching for icons are good to me now. Now comes to the editor integration. It's actually kinda hard to know what the icons look like from their IDs. Auto-completion for IDs is also a good feature I would love to have.

Iconify IntelliSense for VS Code

With a lot of inspirations from the VS Code extension for MDI, Iconify IntelliSense was born.

Loading icon data and cache them on demand, it encoded svgs into data urls to be displayed as images in VS Code. With the TextEditorDecoration API, I achieve the feature to replace the icon IDs with the icon image itself in place. The icons will become visible and editable when you move the cursor around them.

Auto-completion with icon preview is also available. By typing the icon set id and the following delimiter colon :, a list of icons in the set will popup and you may continue type to do a simple search.

Journey is not ended

These apps and tools solved my long pain with icons. I can focus on bringing ideas to life much more efficiently. I will call it a page for no. However, the journey is not yet ended. I am still passionate about exploring how the tooling for icons could go. And also, keep polishing these tools to make them easier to use and integrate. I wish they could benefit more developers and designers and make site building more simple and pleasant.

Glad if you found them useful to you as well. And thanks for reading XD.

Continues

Enjoy the journey and the tools? Here is how it continues in Sep. 2021:

Journey with Icons Continues

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/make-libraries-working-with-vue-2-and-3 https://antfu.me/posts/make-libraries-working-with-vue-2-and-3 Wed, 01 Jul 2020 14:00:00 GMT Today, Evan has announced that the first RC of Vue 3 will be released in mid-July. The post suggests library/plugin authors to start migrating the support for Vue 3. But as the APIs and behaviors have changed a lot, is that possible to make our libraries support Vue 2 and 3 at the same time?

Universal Code

The most simple way is to write universal code that works in both versions without any additional modification, just like people would do for Python 2 and 3. Simple does not mean it's easy. Write such components requires you to avoid things that newly introduced in Vue 3 and things that deprecated from Vue 2. In other words, you can't use:

• Composition API
• .sync .native modifiers
• Filters
• 3rd-parties vendor objects
• etc. (let me know if I missed anything and I will update the list)

This just makes life harder and you can't benefit from the new awesome APIs in Vue 3.

Use Branches

A reply to this problem from a core team member suggests using different branches to separate your support for each targeting version. I think it's a good solution for existing and mature libraries as their codebases are usually more stable and version targeting optimization might require them to have better code isolations.

The drawback of this is that you will need to maintain two codebases which double your workload. For small scale libraries or new libraries that want to support both versions, doing bugfix or feature supplements twice is just no ideal. I would not recommend using this approach at the very beginning of your projects.

Build Scripts

In VueUse, I wrote some build scripts to make the code imports from the target version's API while building. After that, I would need to publish two tags vue2 vue3 to distinguish different version supports. With this, I can wite the code once and make the library supports both Vue versions. The problem of it is that I need to build twice on each release and guide users to install with the corresponding plugin version (and manually install @vue/composition-api for Vue 2).

---

It has been several months since I wrote VueUse. During this period, I am always trying to figure out a proper way to extract the logic from VueUse, so it can be reused and benefit other library authors. But after all, I still think it's just too complicated to be used in general.

However, at the moment I started to write this post, I came up with the idea - providing the universal interface for both versions. If it works, in this way, authors are no need to worried about the users' environments anymore.

And after some experiments...

🎩 Introducing Vue Demi

Vue Demi is a developing utility that allows you to write Universal Vue Libraries for Vue 2 and 3. Without worrying about users' installed versions.

When you are going to create a Vue plugin/library, simply install vue-demi as your dependency and import anything related to Vue from it. Publish your plugin/library as usual, your package would become universal!

{
  "dependencies": {
    "vue-demi": "latest"
  }
}

import Vue, { reactive, ref } from 'vue-demi'

Underhood, it utilized the postinstall npm hook. After all packages get installed, the script will start to check the installed Vue version and redirect the exports to based on the local Vue version. When working with Vue 2, it will also install @vue/composition-api automatically if it doesn't get installed.

You can also check the working examples, where I created a demo library @vue-demi/use-mouse with just a single file entry.

Please keep in mind that Vue Demi is experimental and there will definitely be some glitches. Feel free to give it a try and let me know if anything goes wrong.

Thanks and happy hacking!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/vue-3-notes https://antfu.me/posts/vue-3-notes Wed, 01 Jul 2020 00:00:00 GMT

Note: This is my personal notes/tips for migrating to Vue 3 and will be updated overtime. Please refer to the official docs for the complete changelog.

Sorted by the importance of my personal sense.

💫 use markRaw for vendor objects

The new reactivity system proxied the object passed to the Vue context. For vendor objects or class instances, you need to wrap it with markRaw in order to disable the reactivity injection.

// works in Vue 2
this.codemirror = CodeMirror.fromTextArea(el)

// in Vue 3 you need to use markRaw()
// otherwise the CodeMirror won't work as expected
this.codemirror = markRaw(CodeMirror.fromTextArea(el))

I think this is a pretty tricky one. You won't see any warn or error on initialization, but the internal state of the vendor object might be messed up. You might face errors that comes from the libraries while couldn't find out why (the example above took me one hour of debugging to find out).

💫 .sync → v-model:

.sync modifier is unified by v-model:

<!-- Vue 2 -->
<Component name.sync="name" />

<!-- Vue 3 -->
<Component v-model:name="name" />

v-model on native element would be value/input while on custom components, it changed to modelValue and update:modelValue

💫 shims-vue.d.ts

Update: now you can use @vuedx/typescript-plugin-vue for better type inference with SFC (no need for shims-vue.d.ts then)

Changed to this:

declare module '*.vue' {
  import { defineComponent } from 'vue'

  const Component: ReturnType<typeof defineComponent>
  export default Component
}

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/type-inferencing-in-vue https://antfu.me/posts/type-inferencing-in-vue Sun, 28 Jun 2020 00:00:00 GMT [[toc]]

As you may or may not know, I am working on preparing to release the v1.0 version for @vue/composition-api recently. One of the current problems is that the type inference does not play well #338. So I get a chance to have a deeper look at vue-next's type implementations. I will tell you what I learned and how magic works in Vue.

Forget about the setup() function and Composition API for now, let talk about the options API in Vue 2 that everybody familiar with. In a classical example, we would have data, computed, methods and some other fields like this:

export default {
  data: {
    first_name: 'Anthony',
    last_name: 'Fu',
  },
  computed: {
    full_name() {
      return `${this.first_name} ${this.last_name}`
    },
  },
  methods: {
    hi() {
      alert(this.full_name)
    }
  }
}

It works well in JavaScript and putting all the context into this is pretty straightforward and easy to understand. But when you switch to TypeScript for static type checking. this will not be the context you expected. How can we make the types work for Vue like the example above?

Type for this

To explicitly assign the type to this, we can simply use the this parameter:

interface Context {
  $injected: string
}

function bar(this: Context, a: number) {
  this.$injected // ok
}

The limitation of this approach is that we will lose the signature of the method when working with a dict of methods:

type Methods = Record<string, (this: Context, ...args: any[]) => any>

const methods: Methods = {
  bar(a: number) {
    this.$injected // ok
  }
}

methods.bar('foo', 'bar') // no error, the type of arguments becomes `any[]`

We would not want to ask users to explicitly type this in every method in order to make the type checking works.
So we will need another approach.

ThisType

After digging into Vue's code, I found an interesting TypeScirpt utility ThisType. The official doc says:

This utility does not return a transformed type. Instead, it serves as a marker for a contextual this type.

ThisType would affect all the nested functions. With it, we can have:

interface Methods {
  double: (a: number) => number
  deep: {
    nested: {
      half: (a: number) => number
    }
  }
}

const methods: Methods & ThisType<Methods & Context> = {
  double(a: number) {
    this.$injected // ok
    return a * 2
  },
  deep: {
    nested: {
      half(a: number) {
        this.$injected // ok
        return a / 2
      }
    }
  }
}

methods.double(2) // ok
methods.double('foo') // error
methods.deep.nested.half(4) // ok

The typing works well, but it still requires users to define the type interface of Methods first. Can we make it infer itself automatically?

We can do that with function inference:

type Options<T> = {
  methods?: T
} & ThisType<T & Context>

function define<T>(options: Options<T>) {
  return options
}

define({
  methods: {
    foo() {
      this.$injected // ok
    },
  },
})

There is only one step left, to make context object dynamic inference from data and computed.

The full working demo would be:

/* ---- Type ---- */
export type ExtractComputedReturns<T extends any> = {
  [key in keyof T]: T[key] extends (...args: any[]) => infer TReturn
    ? TReturn
    : never
}

type Options<D = {}, C = {}, M = {}> = {
  data: () => D
  computed: C
  methods: M
  mounted: () => void
  // and other options
}
& ThisType<D & M & ExtractComputedReturns<C>> // merge them together

function define<D, C, M>(options: Options<D, C, M>) {}

/* ---- Usage ---- */
define({
  data() {
    return {
      first_name: 'Anthony',
      last_name: 'Fu',
    }
  },
  computed: {
    fullname() {
      return `${this.first_name} ${this.last_name}`
    },
  },
  methods: {
    notify(msg: string) {
      alert(msg)
    }
  },
  mounted() {
    this.notify(this.fullname)
  },
})

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/domain-email https://antfu.me/posts/domain-email Wed, 17 Jun 2020 16:00:00 GMT Saw a tweet from Evan You about the hey.com mail service recently. I got interested in having a short and nice email address. My current one in Hotmail is just too long to even being spell out in talk. hey.com looks very nice but $99/year is not a very good deal to me. I decide to use my own domain for receiving emails.

I did this a couple years ago for another domain, I kinda remember an open-source tool allowing forwarding emails by just adding DNS record. I took some time to search for it but I didn't find the page matched with my memory. I went GitHub to search in my stared projects, it turns out the tool now becomes and Freemium SaaS forwardemail.net with a fresh new logo and website design that I can't even recognize it.

The DNS forwarding feature just works the same, but it requires you to log in and register your domain now. I am glad it now being more well documented and charging for premium supports which can help it sustain.

The config is quite simple as usual, with just 3 DNS record:

MX   @  mx1.forwardemail.net  10
MX   @  mx2.forwardemail.net  20
TXT  @  forward-email=youremail@example.com

That’s it! It also provides some advanced configs, you can check the doc here.

While setting up and reading the docs, I learned that you can explicitly purge the cache for Cloudflare DNS and Google DNS. That's a very good-to-know tip!

And now, you can say hi to me at hi@antfu.me!

]]> hi@antfu.me (Anthony Fu) https://antfu.me/posts/new-house https://antfu.me/posts/new-house Fri, 12 Jun 2020 16:00:00 GMT I always feel that I need a blog but I never have one.

So I took some time to rewrite my homepage and adding the blog section. and Hi, here I am :)

This time I gave a try on Gridsome and it works petty well. I do love the <static-query> custom block that works even in components. The progressive image also solves my years of pain in making a photography portfolio (and I have never finished one).

While I was browsing Gridsome's starter templates, I found a great website Forestry.io. It's a Git-backed CMS that I can write and manage my blog posts in a nice GUI website and then commit back to GitHub. This is the feature that I wish to have for a long time, did not expect to see such a well built and nicely designed service out there.

As for the blog, I am likely to do some bilingual stuff in the future. Some posts will be written in English, some might be in Chinese. A switch button will be shown then. Also planned to post my photos in this site, which I would need to implement the gallery page for it.

The site is still WIP, if you have any thoughts or suggestions, please tell me via email or on Twitter. Thanks!

:)

]]> hi@antfu.me (Anthony Fu)