DEV Community: Daishi Kato

How Jotai Was Born

Daishi Kato — Tue, 13 Aug 2024 05:49:16 +0000

Is it just an alternative to Recoil?

Introduction

In this post, I would like to share the story of why I started developing Jotai. While Jotai is often seen as a similar solution to Recoil, there is a longer history behind its development.

React Hooks

It was October 2018 when React Hooks were first announced. I liked the idea of developing logic outside of React components, and believed that many libraries would soon adopt this approach. I wanted to develop something, and global state management was one field I picked. My motivation was to avoid Redux selectors, also known as mapStateToProps at that time. In my work experience, I found that it's pretty hard for beginners to understand referential equality. To avoid extra re-renders, we may need to use memoization libraries such as reselect. It felt unnecessary if the computation of selectors themselves was fairly lightweight.

Reactive React Redux

My initial goal was to develop a binding library using React Hooks for React Redux that avoided the need for selectors. To be clear, selectors themselves are fine. What I wanted to avoid was using selectors only for render optimization. What I reached for was Proxies. Proxies allow us to track the access of state objects, and we can only trigger re-renders if the accessed properties are changed. This eliminated the need for selectors for render optimization. It automatically optimized re-renders. Some people liked the idea, but meanwhile, the official React Redux binding provided a useSelector hook and it became the de-facto standard. Eventually, my library was marked as unmaintained.

https://github.com/dai-shi/reactive-react-redux

React Tracked

With Redux having its own Hooks library, I decided to move away from Redux and develop a library that focused on the React Context pattern. A naive solution with useState (or useReducer) with React Context has the extra re-render issue. This library took the same approach as the previous one and overcame the issue. The biggest benefit of this library is that it doesn't change the semantics from the naive solution. If people had already used useState and propagated the state through the context, introducing the library is very easy and renders are optimized automatically. This library is called React Tracked.

https://github.com/dai-shi/react-tracked

I put much effort into this library, did benchmarks, wrote documentation, set up the website, and wrote a bunch of blog posts. Some people really liked it and it was used in production. However, something was missing to get more attention. The negative feedback was that it worked too magically behind the scenes, and some people hesitated to use Proxies.

Recoil

I had been exploring ways to avoid using Proxies while maintaining the goal of no selectors for render optimization. In May 2020, Recoil was presented at the React Europe conference. That was exactly what I wanted. The reason I made React Tracked with React Context was to make it compatible with Concurrent Mode. Recoil was said to be compatible with Concurrent Mode. The atom model was slightly different from observables, and focused on the React use case.

https://www.youtube.com/watch?v=_ISAA_Jt9kI

I was kind of shocked that I didn't come up with similar ideas. The fundamental technique wasn't very new. MobX did something pretty similar. As Recoil was announced, I half gave up creating my own library. I thought we could just use it. But that didn't stop me from thinking about it and experimenting with something similar. One thing I didn't like about Recoil was that an atom required a string key. The API didn't feel right. While it's understandable that it's for serialization, that actually convinced me that Recoil would never allow omitting string keys. So, I decided to develop my own library.

Jotai

Jotai was obviously inspired by Recoil, but there are several key differences. Beyond omitting string keys, its design philosophy focuses on a small API surface and a minimal core. Any additional features should be implemented outside the core. Jotai was first announced on September 9, 2020. At that point, it was very uncertain how people would consider it. I thought Recoil was like Flux and there would be many Recoil-like libraries. The goal was to promote the idea of the atom model.

https://github.com/pmndrs/jotai

After the first announcement, there was some positive feedback and I continued to develop it, reached v1, and then reached v2. There were more contributors coming and we now maintain the project as a group. We have docs and a website. We also have many integration libraries around the minimal core, maintained by several contributors.

Current Status

We've addressed various bugs, and Jotai is now quite stable. My current focus is on making the core more maintainable by contributors. The core code is very complex, and my challenge is to make it more readable and understandable. More integration libraries would be nice and they are increasing, actually.

Thanks to all Jotai users and contributors. I'm very grateful for it.

Originally published at https://blog.axlight.com on August 9, 2024.

How Zustand Was Born

Daishi Kato — Tue, 23 Jul 2024 03:42:56 +0000

More precisely, since Zustand v3

Introduction

In this post, I would like to share the story behind Zustand's development. To be precise, I wasn't the original author of Zustand, and when Zustand v0 was born, I was developing other global state libraries, especially React-Tracked. By the way, I now consider myself a (secondary) author of Zustand.

I found my tweet mentioning Zustand, comparing it with other libraries, including mine.

// Detect dark theme var iframe = document.getElementById('tweet-1141004414129324032-103'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1141004414129324032&theme=dark" }

My belief at that point was that the global state should be passed via React Context so that it works with React Concurrent Mode. So, I made a comparison table to differentiate my library and others, and Zustand was one of them. This was in the year 2019.

Zustand v3

In 2020, I joined the Poimandres group and took over Zustand's development. My interest back then was to make global state libraries work with React Concurrent Mode. It wasn't possible to get the full benefit from Concurrent Mode, but there was an experimental API called useMutableSource to make the global state compatible with Concurrent Mode.

I was experimenting with many things using a React Context-based solution with React-Tracked and wondered what we could do with the global state without React Context. Zustand was one year old, but nobody was maintaining it. So, I decided to take it over.

The experimental useMutableSource API wasn't ready, so the first task was to update various things and fix some bugs. This was when Zustand v3 was born. My hope was to soon release v4 with useMutableSource, but it didn't happen. There's another story behind it.

Nowadays, it's a well-known pattern to have the global state outside and optionally use React Context to pass its store. Zustand was a pioneer in this pattern. People were very skeptical about not having the global state in React Context, and we had a hard time explaining that it's a valid pattern.

Current Status

One of the things I care about with Zustand is its simple implementation and its small bundle size. If you look at the source code, you'll see it's nothing more than just using React hooks with a minimal store implementation.

As of writing, Zustand v4 is the latest version, which has very advanced TypeScript support, and the code is almost entirely rewritten from v3. We have Zustand v5 almost ready for the next release.

Last but not least, there are several contributors who maintain this project. I didn't expect this would happen when I took over the project. I'm very grateful for it. Thanks, everyone.

Originally published at https://blog.axlight.com on July 14, 2024.

Jotai Tips

Daishi Kato — Wed, 24 Apr 2024 22:46:49 +0000

Learn Jotai with handy tips!

Introduction

I've been sharing tips about Jotai on Twitter, calling them "Jotai tips." As tweets tend to get lost over time, I thought it would be good to have all these tips in one place.

So, here we go.

Tip 1: Primitive-like atoms

// Detect dark theme var iframe = document.getElementById('tweet-1694494217379459573-419'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1694494217379459573&theme=dark" }

Tip 2: Early return

// Detect dark theme var iframe = document.getElementById('tweet-1694876971367555217-269'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1694876971367555217&theme=dark" }

Tip 3: Promise value

// Detect dark theme var iframe = document.getElementById('tweet-1695745037194436939-591'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1695745037194436939&theme=dark" }

Tip 4: Store API

// Detect dark theme var iframe = document.getElementById('tweet-1695966656563196044-963'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1695966656563196044&theme=dark" }

Tip 5: useAtom

// Detect dark theme var iframe = document.getElementById('tweet-1696317745426747625-150'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1696317745426747625&theme=dark" }

Tip 6: Derived-like atoms

// Detect dark theme var iframe = document.getElementById('tweet-1697051518976114798-172'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1697051518976114798&theme=dark" }

Tip 7: Atom depending on props

// Detect dark theme var iframe = document.getElementById('tweet-1697396138578759985-440'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1697396138578759985&theme=dark" }

Tip 8: Atom with local storage

// Detect dark theme var iframe = document.getElementById('tweet-1697797840796635393-492'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1697797840796635393&theme=dark" }

Tip 9: Swap atom

// Detect dark theme var iframe = document.getElementById('tweet-1699032814128443658-724'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1699032814128443658&theme=dark" }

Tip 10: Write chain

// Detect dark theme var iframe = document.getElementById('tweet-1699391498985595310-543'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1699391498985595310&theme=dark" }

Tip 11: Promise.all in async atoms

// Detect dark theme var iframe = document.getElementById('tweet-1699553010245067022-318'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1699553010245067022&theme=dark" }

Tip 12: Toggle atom

// Detect dark theme var iframe = document.getElementById('tweet-1699970779373592963-887'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1699970779373592963&theme=dark" }

Tip 13: Two args

// Detect dark theme var iframe = document.getElementById('tweet-1700295758325682522-580'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1700295758325682522&theme=dark" }

Tip 14: Selected item atom

// Detect dark theme var iframe = document.getElementById('tweet-1700500246143660300-460'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1700500246143660300&theme=dark" }

Tip 15: Optimize rendering with two atoms

// Detect dark theme var iframe = document.getElementById('tweet-1701133210212831674-756'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1701133210212831674&theme=dark" }

Tip 16: Use atom conditionally

// Detect dark theme var iframe = document.getElementById('tweet-1701955150724690192-231'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1701955150724690192&theme=dark" }

Tip 17: Atom creator

// Detect dark theme var iframe = document.getElementById('tweet-1702511436373872783-619'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1702511436373872783&theme=dark" }

Tip 18: Refresh atom

// Detect dark theme var iframe = document.getElementById('tweet-1713395849454395741-993'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1713395849454395741&theme=dark" }

Tip 19: Default atom

// Detect dark theme var iframe = document.getElementById('tweet-1714126922542964899-547'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1714126922542964899&theme=dark" }

Tip 20: Async only initially

// Detect dark theme var iframe = document.getElementById('tweet-1722543472874594334-490'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1722543472874594334&theme=dark" }

Closing notes

How was it? Did you enjoy the Jotai puzzle?

Why useSyncExternalStore Is Not Used in Jotai

Daishi Kato — Sun, 05 Nov 2023 12:14:27 +0000

How about Zustand and Valtio

Introduction

Jotai is developed to solve an extra re-render issue with React Context. A major challenge in its development has been the support of both Suspense and Concurrent rendering. Otherwise, it would have been a simpler implementation and its implementation would closely resemble that of any observable-like libraries.

As of writing, Jotai is fully compatible with Suspense and Concurrent rendering with some exceptions. There's a repo to evaluate some details.

https://github.com/dai-shi/will-this-react-global-state-work-in-concurrent-rendering

But, in this post, we focus on two things; tearing and time slicing.

React 18 introduces useSyncExternalStore hook. This is a solution for external stores to avoid tearing. Jotai is technically an external store and suffers from tearing. However, useSyncExternalStore isn't a silver bullet. It's not named as useExternalStore. As I understand, the "Sync" part basically means it's incompatible with "time slicing" and it's also refered as "de-opt".

We knew it while introducing the useSyncExternalStore hook. In my talk at React Conf 2021, there's a mention that "useState is sometimes desirable (more than useSyncExternalStore)". It refers to the time slicing, but it's not very clear unfortunately. The purpose of the talk is to introduce the new hook, and didn't spend time on the benefit of useState.

Check out the talk if you are interested.

This subtle difference is why Jotai uses useState (useReducer).

What's the actual issue

The difference between 1) a userland solution with useState (useReducer) & useEffect, and 2) useSyncExternalStore, is temporary tearing. With the userland solution, it can tear for a short period of time, and then it will be consistent afterwards.

Someone posted a reproduction in the Jotai GitHub Discussions.

https://github.com/pmndrs/jotai/discussions/2137

You can check it out: https://codesandbox.io/s/2pfr7t

What's more important than temporary tearing

As noted, Jotai supports Suspense and Concurrent rendering, specifically the use of useTransition. Moreover, the API is designed to be used with useTransition, like it doesn't have a pending state.

Zustand, which uses useSyncExternalStore, has a behavioral issue with useTransition.

Check out the demo:
https://codesandbox.io/s/9ss9r6

The expected behavior is to show "Pending...", but it doesn't, and instead show the Suspense fallback.

Zustand is explicitly designed as an external store, so this is somewhat acceptable.

On the other hand, Jotai is modeled after useState and we expect useTransition to behave likewise. This is more important than temporary tearing.

Ideally, if React provides a building-block function to allow creating a custom useState-like hook (that requires state versioning), Jotai can do it better. It's very unlikely that it will happen. So, it's a trade-off.

Closing notes

When I started developing Jotai, not many people cared about Suspense and Concurrent rendering. It's nice to see recently people are interested in it and discuss on it.

This applies to Zustand and I developed another library that with useState (useReducer) instead of useSyncExternalStore.

https://github.com/dai-shi/use-zustand

There's also Valtio version.

https://github.com/dai-shi/use-valtio

By the way, you may have noticed that I refered to it as "useState (useReducer)". I actually use useReducer instead of useState. There's another reason but it's out of the scope of this post. For someone interested, you will see, if you implement it with useState, some of Jotai tests fail.

Originally published at https://blog.axlight.com on October 28, 2023.

How to Use Jotai and useTransition for Mutation

Daishi Kato — Tue, 01 Aug 2023 02:49:59 +0000

The power of promise values

Introduction

Jotai is a powerful library designed for seamless integration with React Suspense. Unlike Zustand, Jotai's primary focus is React Suspense from the beginning.

In its simplest form, Jotai effortlessly works with Suspense, and gives superior developer experience and user experience with async data.

https://codesandbox.io/s/vjfpcd

import { Suspense } from "react";
import { atom, useAtomValue, useSetAtom } from "jotai";

const id = 1;

const postAtom = atom(async (get) => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const data = await res.json();
  return data;
});

const Post = () => {
  const { title } = useAtomValue(postAtom);
  return <div>Title: {title}</div>;
};

const App = () => (
  <Suspense fallback="Loading...">
    <div>
      <Post />
    </div>
  </Suspense>
);

export default App;

There are no issues so far.

This blog post explores Jotai's strength in handling mutations using promise values in atoms and useTransition. Let's learn how to leverage React Suspense with Jotai to handle async data.

The problem

Now, if we want to mutate the server data, our first option would be a derived atom with an async write function. For simplicity, let's use a write-only atom.

https://codesandbox.io/s/z84n9x

import { Suspense, useTransition } from "react";
import { atom, useAtomValue, useSetAtom } from "jotai";

const id = 1;

const mutationResultAtom = atom<{ title: string } | null>(null);

const postAtom = atom(async (get) => {
  const mutationResult = get(mutationResultAtom);
  if (mutationResult) {
    return mutationResult;
  }
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const data = await res.json();
  return data;
});

const mutateAtom = atom(null, async (get, set, title) => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ title })
  });
  const data = await res.json();
  set(mutationResultAtom, data);
});

const Post = () => {
  const { title } = useAtomValue(postAtom);
  return <div>Title: {title}</div>;
};

const Mutate = () => {
  const mutate = useSetAtom(mutateAtom);
  const handleClick = () => {
    mutate("changed title");
  };
  return (
    <div>
      <button onClick={handleClick}>Click me</button>
    </div>
  );
};

const App = () => (
  <Suspense fallback="Loading...">
    <div>
      <Post />
      <Mutate />
    </div>
  </Suspense>
);

export default App;

Currently, it doesn't suspend during mutation, which causes it to not work well with useTransition.

What we would like to do is the following:

  const [isPending, startTransition] = useTransition();
  const handleClick = () => {
    startTransition(() => {
      mutate("changed title");
    });
  };

However, it's a NO-OP because we resolve a promise before updating the post atom. We need to avoid resolving a promise in the write function, and resolve the promise in the read function to make an atom to suspend.

The solution

We want to tell React to suspend on mutation. How can we achieve that?

The solution is to store a promise value in an atom, and resolve it in the read function.

Let's see what it looks like.

https://codesandbox.io/s/fkjvrg

import { Suspense, useTransition } from "react";
import { atom, useAtomValue, useSetAtom } from "jotai";

const id = 1;

const mutationResultAtom = atom<Promise<{ title: string }> | null>(null);

const postAtom = atom(async (get) => {
  const mutationResult = await get(mutationResultAtom);
  if (mutationResult) {
    return mutationResult;
  }
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const data = await res.json();
  return data;
});

const mutateAtom = atom(null, (get, set, title) => {
  const data = fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ title })
  }).then((res) => res.json());
  set(mutationResultAtom, data);
});

const Post = () => {
  const { title } = useAtomValue(postAtom);
  return <div>Title: {title}</div>;
};

const Mutate = () => {
  const mutate = useSetAtom(mutateAtom);
  const [isPending, startTransition] = useTransition();
  const handleClick = () => {
    startTransition(() => {
      mutate("changed title");
    });
  };
  return (
    <div>
      <button onClick={handleClick}>Click me</button>
      {isPending && "Pending..."}
    </div>
  );
};

const App = () => (
  <Suspense fallback="Loading...">
    <div>
      <Post />
      <Mutate />
    </div>
  </Suspense>
);

export default App;

Now, it works with useTransition, and it shows "Pending..." while performing mutations.

This pattern also works well when a mutation doesn't return updated data. In such cases, we can discard the mutation result and fetch the data again.

A more complex case

In many cases, an async atom depends on another atom. In our example, let's assume the id is in an atom idAtom.

We need a small trick, but this is how it works.

https://codesandbox.io/s/jpfqwy

import { Suspense, useTransition } from "react";
import { atom, useAtomValue, useSetAtom } from "jotai";

const idAtom = atom(1);

const mutationResultAtom = atom<{
  id: number;
  data: Promise<{ title: string }>;
} | null>(null);

const postAtom = atom(async (get) => {
  const id = get(idAtom);
  const mutationResult = get(mutationResultAtom);
  if (mutationResult && mutationResult.id === id) {
    return mutationResult.data;
  }
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const data = await res.json();
  return data;
});

const mutateAtom = atom(null, (get, set, title) => {
  const id = get(idAtom);
  const data = fetch(`https://jsonplaceholder.typicode.com/posts/${id}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ title })
  }).then((res) => res.json());
  set(mutationResultAtom, { id, data });
});

const Post = () => {
  const { title } = useAtomValue(postAtom);
  return <div>Title: {title}</div>;
};

const Next = () => {
  const setId = useSetAtom(idAtom);
  const [isPending, startTransition] = useTransition();
  const handleClick = () => {
    startTransition(() => {
      setId((id) => id + 1);
    });
  };
  return (
    <div>
      <button onClick={handleClick}>Next Post</button>
      {isPending && "Pending..."}
    </div>
  );
};

const Mutate = () => {
  const mutate = useSetAtom(mutateAtom);
  const [isPending, startTransition] = useTransition();
  const handleClick = () => {
    startTransition(() => {
      mutate("changed title");
    });
  };
  return (
    <div>
      <button onClick={handleClick}>Change title</button>
      {isPending && "Pending..."}
    </div>
  );
};

const App = () => (
  <Suspense fallback="Loading...">
    <div>
      <Post />
      <Next />
      <Mutate />
    </div>
  </Suspense>
);

export default App;

The trick is to associate the mutation result with the corresponding id. This technique can be applied to handle more complex scenarios as well.

Closing notes

Jotai's seamless integration with useTransition also works for handling mutations. By leveraging promise values, we can develop better user experience, even with complex state models.

Hope you find it useful and discover the true power of Jotai.

Originally published at https://blog.axlight.com on July 27, 2023.

Why Zustand Typescript Implementation Is So Ugly

Daishi Kato — Sun, 23 Jul 2023 10:57:44 +0000

BTW, JavaScript implementation is so clean

Introduction

Note: This post focuses on Zustand library's implementation in TypeScript. It does not affect the user code, which should be kept clean.

Zustand's JavaScript implementation is very small, as seen in the following tweet.

// Detect dark theme var iframe = document.getElementById('tweet-1583082766081531905-654'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1583082766081531905&theme=dark" }

However, its TypeScript implementation is quite complicated. There are several reasons, one of which we explore in this post.

SetStateInternal type

Let's take a closer look at the SetStateInternal type.

(Keep in mind that it's intended for internal use, as we recommend using StoreApi['setState'] for public APIs.)

https://github.com/pmndrs/zustand/blob/f11cc7f37ad0a53f49370c0e4e659690a1c1a721/src/vanilla.ts#L1-L6

type SetStateInternal<T> = {
  _(
    partial: T | Partial<T> | { _(state: T): T | Partial<T> }['_'],
    replace?: boolean | undefined
  ): void
}['_']

What are those simily characters ['_']?

It's a TypeScript hack, and the actual character used (in this case, _) is not significant; any word would work. We don't go into TypeScript technical details, but let's see what happens if we don't use such a hack.

What we would imagine is the following type as a simpler alternative.

type SetStateInternal2<T> = (
  partial: T | Partial<T> | ((state: T) => T | Partial<T>),
  replace?: boolean | undefined
) => void

This doesn't work for certain cases. Let's explore how it fails with contrived examples.

The first one is the following:

type State = { name: string; age: number };

declare function run<Fn extends SetStateInternal<unknown>>(fn: Fn): void;
declare function run2<Fn extends SetStateInternal2<unknown>>(fn: Fn): void;
declare const setState: SetStateInternal<State>
declare const setState2: SetStateInternal2<State>
run(setState);
run2(setState2);

run2 causes a type error.

The second one is the following:

type NameOnlyState = { name: string };
type StoreApi<T> = { setState: SetStateInternal<T> };
type StoreApi2<T> = { setState: SetStateInternal2<T> };
declare const store: StoreApi<State>;
declare const store2: StoreApi2<State>;
const nameOnlyStore: StoreApi<NameOnlyState> = store;
const nameOnlyStore2: StoreApi2<NameOnlyState> = store2;

Assigning to nameOnlyStore2 fails.

You can find the full reproduction in the TypeScript playground: https://tsplay.dev/NBVO4N

As a library consumer, you don't need to know why this happens or how to resolve it. It's something TypeScript magicians should take care of.

Closing notes

This post has highlighted one of the reasons behind the complexity of Zustand's TypeScript implementation. There are other reasons, which could be addressed in a future post.

Originally published at https://blog.axlight.com on July 19, 2023.

Why You Don't Need Signals in React

Daishi Kato — Thu, 18 May 2023 00:31:56 +0000

Because we have Jotai

Introduction

In the world of web frontend development, signals have become a popular topic. At their core, signals are used to represent changes in state over time. Some developers have discussed the potential of using signals in conjunction with React.

Signals are actually an older concept, and it's uncertain how they are understood by modern web developers. Initially, I was confused about the characteristics of signals, but I later realized that they can be boiled down to two main aspects:

a) Reactive primitives
b) Bypassing diffing

Daishi Kato

@dai_shi

What I'm confused is people see signals with two aspects: a) reactive primitives, and b) bypassing diffing.

Jotai atoms and useAtom hook work well enough for a). The same should apply to observable family in general.

b) is not the goal of React in the first place. twitter.com/acdlite/status…

01:15 AM - 24 Feb 2023

Andrew Clark @acdlite
I really don't mean to be too dismissive of the enthusiasm around signals. I just prefer to imagine a world where the main thing you think about when building components is something other than optimizing update performance. https://t.co/2elo1vB0Rq

In this blog post, we'll explore these two aspects and their relevance in the context of React. Note that we'll only be discussing these two aspects of signals and won't consider other potential uses which might be more important for someone.

Reactive primitives

Reactivity is a key feature of React. Components are re-rendered when state changes. With useState, you can create reactive primitives by defining state that triggers re-rendering on updates. This makes your components reactive. Additionally, you can define derived state in render functions.

Here's an example usage of useState:

const Component = () => {
  const [count, setCount] = useState(0);
  const doubleCount = count * 2; // derived state
  // ...
};

However, it's important to note that useState only creates local state. This can make it difficult to share state between components, and you may need to use prop drilling or context propagation to accomplish this.

To simplify the process of defining and using global state, third-party libraries like Jotai can be useful. With Jotai, you can easily share state between components without relying on prop drilling or context propagation.

To define global state with Jotai, you can use atoms. These atoms represent definitions of pieces of state that you can use in your components. For example, here's how you can define a primitive atom:

const countAtom = atom(0);

You can also define derived atoms that depend on other atoms, like this:

const doubleCountAtom = atom((get) => get(countAtom) * 2);

While the syntax of atoms may look a bit different from typical signal syntax, the mental model is quite similar. We define primitives and compose them for complex state. You can define as many atoms as you need to represent a data graph, making it easy to manage complex state in your application.

The following shows how to use Jotai atoms in your components:

const Component = () => {
  const [count, setCount] = useAtom(countAtom);
  const [doubleCount] = useAtom(doubleCountAtom); // derived state
  // ...
};

Unlike useState, useAtom is not local state and you can use it in another component to share the atom state:

const AnotherComponent = () => {
  const [count, setCount] = useAtom(countAtom);
  // ...
};

You may have noticed that Jotai atoms work similarly to signals when it comes to reactive primitives. However, Jotai offers additional benefits through React hooks like useAtom, which follow React conventions. These hooks allow you to share state between components without the need for prop drilling or context propagation, simplifying your code and making it easier to reason about. Moreover, Jotai has Provider to isolate state for subtrees, which is not possible with truly global signals.

Bypassing diffing

Another key feature of React is updating of the DOM
achieved through a process called "diffing." By comparing the previous and current representations of your UI, React determines what has changed and updates only those parts of the DOM, resulting in better performance and a more responsive UI.

However, diffing does come at a cost, and there may be cases where bypassing diffing can be more efficient. For example, if you're updating only one part of the UI and are certain that everything else is unchanged, updating the UI directly without diffing may be more efficient.

To demonstrate that it's technically possible to bypass diffing, we have an experimental library called jotai-signal. We also have a blog post discussing its internals: Demystifying Create React Signals Internals

However, bypassing diffing goes against React's core principles of declarative programming. While it may be tempting to bypass diffing for performance reasons, doing so risks introducing inconsistencies in your UI and making your application harder to reason about.

Before deciding to bypass diffing, it's important to thoroughly assess the performance benefits and weigh them against the potential risks. It's also worth considering whether there are other ways to optimize your application's performance.

In general, it's recommended to follow React's best practices and use diffing appropriately to ensure that your UI remains consistent and predictable.

Summary

In conclusion, while signals are an interesting concept in web development, Jotai offers a simpler and more intuitive way to manage state in React applications. With Jotai, you can easily create and use global state through atoms, eliminating the need for prop drilling or context propagation. Atoms are conceptually very similar to signals in terms of reactive primitives.

While it's technically possible to bypass React's diffing algorithm in a sense, doing so goes against the principles of declarative programming and can introduce inconsistencies in your UI. It's important to thoroughly assess the potential benefits and risks before making the decision to bypass diffing.

By following React's best practices and leveraging the power of Jotai, you can create maintainable and performant React applications.

Originally published at https://blog.axlight.com on April 23, 2023.

Demystifying Create React Signals Internals

Daishi Kato — Thu, 16 Mar 2023 02:49:22 +0000

How jotai-signal, valtio-signal and zustand-signal work

Introduction

When I first saw SolidJS and Preact Signals, I thought they are interesting but they are different from React. What made me motivated is @preact/signals-react. I didn't like the original implementation using REACT INTERNALS, and that drove me to create something.

We already had Jotai. Jotai atoms are like signals, representing reactive sources, and allowing to form a dependency graph or a data flow. The missing piece was signal-like syntax without hooks.

The initial version of jotai-signal library was developed as a proof of concept. It provided a custom JSX transfomer to hide hooks behind the scene. It was using experimentl_use to read React context.

I also developed jotai-uncontrolled to bypass diffing, which is another aspect of signals. While jotai-signal was a syntax sugar, jotai-uncontrolled has a performance benefit.

Meanwhile, the next version of jotai-signal uses Jotai v2 API, and avoids experimental_use by exposing Store interface. This allows us to consider using it more seriously. Furthermore, when discussing internally, I got an idea to combine jotai-signal and jotai-uncontrolled. We can bypass diffing automatically in some cases.

Along with it, I developed valtio-signal and zustand-signal by almost copying code from jotai-signal. This made me think it would be possible to create an abstract layer, and create-react-signals was born.

This post will explain how create-react-signals work internally.

What are signals?

In the context of create-react-signals, a signal is kind of a store that has three functions:

subscribe: a function to add a callback which will be invoked when a signal value changes.
getValue: a function to return the signal value.
setValue: a function to update the signal value.

Using a signal with a custom hook should be pretty easy.

const [value, setValue] = useSignal(signal);

You can just subscribe in the hooks and return the current value. Implementation should be trivial with useSyncExternalStore.

But, we want to just use the signal so that it automatically subscribes and updates value.

It could be done with a compiler at build time, but our approach is a runtime transformation.

How does it transform code?

Let's assume we have a simple signal. Suppose countSignal contains a number.

Our component would look like this:

const Component = () => {
  return (
    <div>{countSignal}</div>
  );
};

React doesn't understand this, because countSignal is a special object that can't be rendered.

We transform the code into something like the following.

const SignalsRerenderer = ({ signal, render }) => {
  const [, rerender] = useReducer((c) => c + 1), 0);
  useEffect(() => signal.subscribe(), [signal]);
  return render();
};

const Component = () => {
  return SignalsRerenderer({
    signal: countSignal,
    render: () => (
      <div>{countSignal.getValue()}</div>
    ),
  });
};

.subscribe. and .getValue methods are pseudo code, as a signal doesn't explicitly have such methods. There are other simplifications, like only handling one signal and omitting memoization code.

To implement the transformation, create-react-signals creates a custom createElement from original React.createElement.

Overriding the original React.createElement might be one solution, but it seems too hacky.

Why custom JSX transfomer?

Forunately, we can customize JSX transfomer. The recent bundler supports @jsxImportSource.

You can also specify a pragma in your source code.

/** @jsxImportSource jotai-signal */

This technique is used in some projects, for example, Emotion.

One of the biggest questions in this approach is that specifying the custom transformer can be seen unusual. (Well, it's a hack after all, so it's not usual.)

How can signals create signals?

What if a signal value is an object? Suppose personSignal has a value { firstName: 'first', lastName: 'last' }.

Using an object signal in JSX like the following doesn't work.

const Component = () => {
  return (
    <div>{personSignal}</div>
  );
};

As an object can't be rendered, we need to do something like the following.

const Component = () => {
  return (
    <div>{personSignal.firstName}</div>
  );
};

Now, to make that work, personSignal.firstName shouldn't be a string. It has to be another signal. Otherwise, we can't subscribe to it.

How do we solve it? Our current solution is Proxies. When there's a property access to a signal, it will create a new signal. This is done recursively.

If personSignal.firstName is used in JSX, it will skip updating when only lastName changes.

(Note that object signals are currently not supported in jotai-signal.)

How does it skip diffing?

As noted previously, jotai-uncontrolled allows skipping diffing. It works like uncontrolled components. The technique is using ref and manipulating DOM directly.

This post doesn't go too much in details about the implementation of uncontrolled components.

There's fallback mechanism if uncontrolled components don't work.

// Detect dark theme var iframe = document.getElementById('tweet-1616639032418799619-688'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1616639032418799619&theme=dark" }

This approach is still considered experimental and might have a pitfall.

What are difficulties?

One of unsolved issues is how to get signal values outside JSX. Our signal has getValue function, so we have to call it.

There are some options:

// callable signal
const value = countSignal();

// string property access
const value = countSignal.value;

// symbol property access
const value = countSignal[VALUE_SYMBOL];

So, how is it difficult? Consider the personSignal case.

// callable signal
const value = personSignal.firstName();

// string property access
const value = personSignal.firstName.value;

// symbol property access
const value = personSignal.firstName[VALUE_SYMBOL];

At first, the callable signal style looked the best, but it can't be typed in TypeScript.

The string property looks the most familiar, but it can cause naming conflict.

The symbol property has no drawbacks, but not very handy.

The same problem applies to setValue.

// callable signal
const value = personSignal.firstName('newValue');

// string property access
const value = personSignal.firstName.value = 'newValue';

// symbol property access
const value = personSignal.firstName[VALUE_SYMBOL] = 'newValue';

We could change our mind and use a property to return a signal.

const countValue = countContainer.value;
const countSignal = countContainer.signal;

In summary, it's still an open problem.

Closing notes

In addition to jotai-signal, valtio-signal and zustand-signal, we can technically create redux-signal.

// Detect dark theme var iframe = document.getElementById('tweet-1629482966895448064-92'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1629482966895448064&theme=dark" }

I think signals in React are still a open research field.

If React will provide a new primitive such as use(Observable), we could explore this approach further.

// Detect dark theme var iframe = document.getElementById('tweet-1628951555658620930-171'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1628951555658620930&theme=dark" }

Until then, let's play with userland solutions.

Originally published at https://blog.axlight.com on February 26, 2023.

You Might Not Need React Query for Jotai

Daishi Kato — Sat, 04 Feb 2023 14:57:15 +0000

Explore data fetching solution with atoms

Introduction

When Jotai development was started (before releasing v1), it has a simple goal. It optimizes re-renders, which was often a problem with useState and useContext using a big state object. We also wanted to avoid using selector function, which is popularized by Redux and widely used.

In the early days, I wanted to have data fetching solution, but didn't want to complicate Jotai itself.
So, jotai/query package was created. It's an integration with React Query v3. It went well, but I noticed a certain mismatch with users. While my mental model was to create a data fetching API for Jotai, people want full features from React Query. I had been struggling with the mismatch, and ended up with creating a new library jotai-tanstack-query. It integrates TanStack Query v4 and covers full features.

So, now I'm back to the original challenge. What would be a data fetching API for Jotai? This post is to explore that road. We may not reach a conclusion that works right away, but let's start.

What Jotai can do

Jotai has a store internally, which holds values of atoms. It's implemented with WeakMap whose key is an atom itself, and its value of an atom is the latest value. The use of WeakMap allows to avoid memory leaks. The store has only one value per atom. It doesn't keep the history of changes.

In Jotai v2 API, createStore is exposed and we can directly read and write atom values.

import { createStore, atom } from 'jotai/vanilla';

const store = createStore();

const atom1 = atom();
const atom2 = atom();

store.set(atom1, 'hello');
store.set(atom2, 'world');

console.log(store.get(atom1)); // ---> 'hello'

We could use the store for caching. Atoms can be defined with async functions. Here's a simple data fetching example.

const idAtom = atom(1);
const dataAtom = atom(async (get) => {
  const id = get(idAtom);
  const res = await fetch(`https://reqres.in/api/posts/${id}`);
  const data = await res.json();
  return data;
});

dataAtom depends on idAtom and it will be only re-evaluated when a dependency changes. So, it works like a very basic cache capability.

The strength is that we can derived another atom from dataAtom. It allows to form so-called data flow graph.

We can also use some utils like atomWithDefault so that we can override the cache value.

The point is, once dataAtom is defined, we could do everything with full Jotai functionalities. From the library perspective, it doesn't know if dataAtom is a cache data from somewhere else.

What Jotai can't do

It seems like we can do very simple data fetching only with Jotai. So, what's missing? Well, there are so many things, but let's focus on something. My motivation for the original jotai/query is richer caching.

Because Jotai store can only hold current value, it's very limited for caching. Let's revisit the previous example.

const idAtom = atom(1);
const dataAtom = atom(async (get) => {
  const id = get(idAtom);
  const res = await fetch(`https://reqres.in/api/posts/${id}`);
  const data = await res.json();
  return data;
});

If we change the value of idAtom from 1 to 2, the async function will be invoked and the value of dataAtom will be updated. What if we change it back from 2 to 1? Because Jotai store holds only the latest value of dataAtom, it will re-invoke the async function with id=1, which it did previously. This is not ideal, because our async function is fetching data from a server, and data fetching is usually costly.

A side note: The previous data can actually be cached in browser or somewhere. However, having async value (= promise) is not nice in React, because it will trigger render twice. The newly proposed use hook might mitigate this issue.

Having only the latest values s one of huge limitations with Jotai store, if we use it for cache for data fetching. But, it's by design. How can we overcome such a limitation?

jotai-cache package

Jotai's API is very minimal and it encourage adding features outside. Atoms are composable and we can implement various features. There are many libraries to provide various features.

jotai-cache is one of such libraries that tries to add richer caching feature for Jotai atoms.

https://github.com/jotaijs/jotai-cache

As of writing, it has atomWithCache function. It solves the caching problem described in the previous section. Its basic usage is straightforward. Just replace atom with atomWithCache.

import { atomWithCache } from 'jotai-cache';

const idAtom = atom(1);
const dataAtom = atomWithCache(async (get) => {
  const id = get(idAtom);
  const res = await fetch(`https://reqres.in/api/posts/${id}`);
  const data = await res.json();
  return data;
});

Now, if we change the value of idAtom from 2 back to 1, it won't re-invoke the async function, but will use cached value.

This is just one capability for data fetching and it's the start. We hope to have more features in this lib.

atomWithCache is something I wanted when I created jotai/query. We would like to explore Jotai oriented solutions for data fetching.

Closing notes

Well, it's still something in progress. From Jotai point of view, atoms are building blocks, and we should be able to create data fetching solution. That doesn't mean it can reach the level of TanStack Query. They have more features. For examples, infinite query, mutation, and optimistic updates are probably tough ones. There are probably lots to learn from existing solutions. We wouldn't need to implement all the features. If our app is 99% with Jotai and want to add data featching solution, a small missing capability would be nice to fulfill our requirements. On the other hand, you might not need Jotai if TanStack Query covers your needs.

Originally published at https://blog.axlight.com on January 31, 2023.

Why We Need Jotai v2 API

Daishi Kato — Thu, 08 Dec 2022 02:34:38 +0000

It will be incompatible with Recoil

Introduction

Jotai is a library for React state management.

The API (let's call it v1 API) is designed to a) be friendly with Concurrent React, and b) be compatible with Recoil as much as possible.

What does it mean? First, atom read function is evaluated in the render phase in React.

For example, consider a simple derived atom.

const countAtom = atom(0);
const doubleAtom = atom((get) => get(countAtom) * 2);

In the example, (get) => get(countAtom) * 2 is the read function. When countAtom is updated, the library doesn't invoke the read function of doubleAtom immediately. Instead, it triggers the component that uses doubleAtom to re-render. The component re-renders eventually, and it's when the read function of doubleAtom is invoked. The benefit of this behavior might be hypothetical, but React allows to schedule re-renders, which means it can skip invoking read functions in concurrent rendering.

Another behavior in v1 API is that async atoms can suspend and replay.

For example, let's see an example.

const countAtom = atom(0);
const asyncAtom = atom(async (get) => {
  const isEven = get(countAtom) % 2 === 0;
  await someAsyncFunction();
  return isEven;
});
const derivedAtom = atom((get) => {
  const isEven = get(asyncAtom);
  return isEven ? "even" : "odd";
});

It might be a little complex. The first atom is a primitive atom, the second atom is an async atom that depends on the first atom, and the third atom is a "sync" atom that depends on the second atom which is "async".

When countAtom is changed and the read function of derivedAtom is invoked, then the read function of asyncAtom is evaluated and, it suspends because it returns a promise. When the promise is resolved, asyncAtom has a resolved value, and the Jotai library re-evaluates the read function of derivedAtom.

The read function of derivedAtom may return the same value when countAtom value is increased by say two. In such a case, the rendering bails out and it doesn't make changes to DOM.

That is basically how v1 API is designed. It's been a while since the initial release, and it turns out that v1 API has some limitations.

Two major problems

Evaluating the read function is intentional as described, but the behavior is a little difficult to understand.
Consider the following example:

const countAtom = atom(0);
const derivedAtom = atom((get) => {
  const isEven = get(countAtom);
  return isEven ? "even" : "odd";
});

When the countAtom value is increased by two, the read function of derivedAtom is re-evaluated, but it returns the same value as before. In React 17, it can't be observed because of early bail out in useReducer.

In React 18, the useReducer behavior is changed and it does't early bail out. It's a good thing for the Jotai library, because we want to delay the evaluation of read functions. However, this behavior is very confusing to many developers, because people often use console.log to debug rendering behaviors.

The `use` RFC

The RFC is here: https://github.com/reactjs/rfcs/pull/229

As of writing, that RFC is not yet finalized, but it's enough to make us re-think the Jotai API. The new use hook can resolve a promise with the suspend-and-replay behavior, just like we could throw a promise previously.
However, it doesn't allow to use use anywhere. You can only use use in other hooks. It means that the suspend-and-replay behavior that's done in Jotai library can't be replaced with use.

Furthermore, the RFC states we should prefer async/await if possible, and the use hook is an unavoidable solution for now.

This made us to consider new Async API.

New Async API

We already distinguish sync atoms and async atoms.

const syncAtom = atom(() => 0); // Atom<number>
const asyncAtom = atom(async () => 0); // Atom<Promise<number>>

However, when we use get function to get atom values, it returns same values.

const derived1 = atom((get) => get(syncAtom)); // Atom<number>
const derived2 = atom((get) => get(asyncAtom)); // Atom<number>

This is possible because it suspends and replays with async atoms. It means the derived2 can suspend because it depends on an async atom even though the signature of derive2 is a sync atom.

The new API avoids such behavior and just expose promises. It doesn't do anything special to handle promises. The get function returns a value even if it's a promise, instead of resolving the promise.

// New API
const derived1new = atom((get) => get(syncAtom)); // Atom<number>
const derived2new = atom((get) => get(asyncAtom)); // Atom<Promise<number>>

With the new API, it's explicit what atoms will suspend from their types. Only atoms with promise values can suspend.

What's the downside of the new API? We can no longer read async atom values in sync, obviously.

To use async atom values in sync, loadable util may help to certain extent.

// New API
const derived3new = atom((get) => get(loadable(asyncAtom))); // Atom<Loadable<number>>>

We also consider adding a new util called unwrap (tentative name).

// New API
const derived4new = atom((get) => get(unwrap(asyncAtom, -1))); // Atom<number>>

Note that -1 is a default value which is used while asyncAtom doesn't have a value initially.

We will release the new Async API in v2. While the v1 API is heavily inspired by Recoil, the v2 API is not inspired by Recoil, and is incompatible with Recoil API. (The sync atom behavior is probably compatible.)

We will learn how the v2 API goes. There might be some difficulties. Having that said, it seems promising at the moment, because the async behavior is rather straightforward without "suspend and replay". It makes it possible to expose the store API, which is a long awaited feature for some Jotai users.

The biggest problem is that the new Async API is breaking change. Most importantly, the syntax isn't changed, and only behavior is changed. Hopefully, most Jotai users would use TypeScript, and in such case, it's a little easier to notice the change because TypeScript complier complains the invalid usage.

Migration strategy

It would have been easier if the change were in syntax, and we could have both new one and old one and deprecate the old one.

The thing is it's only breaking for async atoms. We assume quite a few users use Jotai only with sync atoms, and there's nothing breaking with sync atoms.

We need a major version up for the new API, thus it's going to be v2 API.

To mitigate migrating to the new API, we will provide it in different entry points.

// New API
import { atom } from 'jotai/vanilla';
import { useAtom } from 'jotai/react';

This allows us to pre-release the new API in v1.

There's another reason why we provide it in different entry points. It would allow using Jotai in non-React environments. For example, there's a project to run Jotai apps without React. See a PR of the project.

We considered if we should deprecate v1 API before jumping to v2, but it would just be a trouble for sync atom users. Some feedbacks suggested to directly jumping to v2.

So, our plan is to pre-release the new API in v1, and later release v2 to have only the new API.

// In v2
import {
  atom, // same as import { atom } from 'jotai/vanilla';
  useAtom, // same as import { useAtom } from 'jotai/react';
} from 'jotai';

That way allows for sync atom users to simply update to v2 without any problems.

It also allows async atom users to try the new API in v1 and migrate to it, and the migrated code will work in v2 too.

Closing note

We already tried the new API with various integration libraries as follows:

We encourage all Jotai users, whether they use async atoms or sync only, to try the new Async API (a.k.a. v2 API) pre-released since jotai v1.11.0.

Originally published at https://blog.axlight.com on December 6, 2022.

How Jotai Specifies Package Entry Points

Daishi Kato — Tue, 19 Apr 2022 02:31:00 +0000

Support CJS and ESM as much as possible

Introduction

If someone has already looked into package.json in the jotai library, they may find "exports" field.

https://github.com/pmndrs/jotai/blob/v1.6.4/package.json#L18-L31

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./index.d.ts",
      "module": "./esm/index.js",
      "import": "./esm/index.mjs",
      "default": "./index.js"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "module": "./esm/utils.js",
      "import": "./esm/utils.mjs",
      "default": "./utils.js"
    },

In the Node.js docs, it is described as Package entry points. Node.js v12.7.0 started implementing it. Nowadays, it's used also by bundlers like webpack and vite.

We use package entry points for separating modules. For example, jotai is a core module exporting core functions. jotai/utils is a separate module which exports additional functions based on core functions. (By the way, another option is to publish two packages instead. But, we prefer multiple entry points in a single package.)

This article describes about how the entry point work. It's based on our observation and might not be 100% accurate.

Fallback structure

First of all, for tools that don't understand "exports", we place CJS files traditionally.

./index.js
./utils.js

This will support file based resolution.

require('jotai') points to ./index.js
require('jotai/utils') points to ./utils.js

Old Node.js works with this and maybe old bundlers do too.

"exports" with default

With "exports", we can export subpath entry points along with main entry point. We want to support both CJS and ESM, and conditional exports should do. Conditional exports accepts "default" as last element for fallback. We use CJS for fallback because that's the default if "type" in package.json is omitted.

This will bring to the following config at minimum:

  "exports": {
    ".": {
      "default": "./index.js"
    },
    "./utils": {
      "default": "./utils.js"
    },

We have other subpaths than "utils". For example, adding "devtools" becomes like this:

  "exports": {
    ".": {
      "default": "./index.js"
    },
    "./utils": {
      "default": "./utils.js"
    },
    "./devtools": {
      "default": "./devtools.js"
    },

Note that if subpath patterns is supported, we can do this:

  "exports": {
    ".": {
      "default": "./index.js"
    },
    "./*": {
      "default": "./*.js"
    },

But subpash patterns are only supported since Node.js v12.20.0.

Entry point for package.json

If some tools are very strict with "exports" and if we don't have an entry for package.json, they complain.

Hence, we add such an entry:

  "exports": {
    "./package.json": "./package.json",

ESM for Node.js

"import" condition is for import statement and import() expression. This is a little bit tricky, but we ended up using .mjs extension for this entry. This indicates ESM to Node.js regardless of "type" field in package.json.

As a result, it looks like this:

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "import": "./esm/index.mjs",
      "default": "./index.js"
    },
    "./utils": {
      "import": "./esm/utils.mjs",
      "default": "./utils.js"
    },

We chose ./esm subfolder to place ESM files for some reasons. But it turns out that it is no longer important because currently our fallback is CJS.

"module" for non-Node.js bundlers

Some bundlers don't like the .mjs extension probably because it's not widely used yet.

As far as I know, webpack v5 and vite support unofficial "module" condition.

So, we can specify it with .js extension.

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "module": "./esm/index.js",
      "import": "./esm/index.mjs",
      "default": "./index.js"
    },
    "./utils": {
      "module": "./esm/utils.js",
      "import": "./esm/utils.mjs",
      "default": "./utils.js"
    },

Currently, ./esm/index.js and ./esm/index.mjs have same content. If for some reason they couldn't be the same, we would be able to change them.

How to deal with TypeScript

As far as I understand, tsc looks for the same file name with .d.ts extension. We place type definition files along with JS files.

./index.js
./index.d.ts
./utils.js
./index.d.ts
./esm/index.js
./esm/index.mjs
./esm/index.d.ts
./esm/utils.js
./esm/utils.mjs
./esm/utils.d.ts

TypeScript will support "types" condition in 4.7.

Having those would be nice:

  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./index.d.ts",
      "module": "./esm/index.js",
      "import": "./esm/index.mjs",
      "default": "./index.js"
    },
    "./utils": {
      "types": "./utils.d.ts",
      "module": "./esm/utils.js",
      "import": "./esm/utils.mjs",
      "default": "./utils.js"
    },

We have already added them before knowing TypeScript 4.7 would support it.

Technically, we will be able to delete ./esm/*.d.ts files with TypeScript 4.7. We will keep them for older TypeScript versions for the mean time.

Dual package hazard

Dual package hazard is a big problem when supporting both ESM and CJS. Jotai uses some module level variables, so it can suffer from this problem.

So far, we believe the probability of this case is fairly low, and it's easy to notice if it exists. We leave this problem unsolved and wait for more feedback.

Closing note

We described some parts of our "exports" entry points
in an unorganized way. I hoped to have more useful info about how we came there, but it turns out that it's not very straightforward. For example, some of old decisions were made with our misunderstanding, and they are no longer important. So, this article is just a note about how we think at this point. It's likely that it may not be valid or best in the near future.

Mixing CJS and ESM is really hard, and we hope ecosystem migrates soon and finds a good pattern meanwhile.

If you want to learn the concrete example, visit unpkg or something to see the package content: https://unpkg.com/browse/jotai@1.6.4/

Originally published at https://blog.axlight.com on April 17, 2022.

When I Use Valtio and When I Use Jotai

Daishi Kato — Wed, 02 Feb 2022 12:46:13 +0000

My two apps use them

Introduction

Recently, I often got asked about this question: Which is recommended, valtio or jotai?

For those who are not familiar with them, they are two out of many state management libraries that I developed.

https://github.com/pmndrs/valtio

https://github.com/pmndrs/jotai

Now, from the library perspective, their implementations are very different. However, from the usage perspective, I understand the confusion. Both serve similar functionalities and we don't usually use both in a single app.

It might be valuable if I could explain which to use if I were to develop some apps.

My answer is I would use valtio for data-centric apps and jotai for component-centric apps.

Let's dive in.

Data-centric and component-centric approaches

In the past, I had this tweet, mentioning "React Centric" and "Data Centric". React component centric approach is an internal store, where as data centric approach is an external store.

This is a diagram to show technical differences among @ReactJS libraries for global state which I maintain/develop. I feel like keeping posting this kind of tweets, but every time it's slightly changed.https://t.co/sJAmYrng5V pic.twitter.com/MgVmy9Go5W
— Daishi Kato (@dai_shi) April 11, 2021

In this article, our focus is the columns in the table. (The rows are from a different perspective.)

Here's another tweet with the same idea. It's "state resides at component level (inside react)" vs. "state resides at module level (outside react)".

Here's another more technical matrix of some @ReactJS global state libraries. It doesn't mean to be super accurate, but to grasp their major characteristics.@Excalidraw shareable link: https://t.co/9P4hsf0gtm pic.twitter.com/OHEXELze4k
— Daishi Kato (@dai_shi) December 25, 2020

Again, our focus is the columns in the table.

So, what are the two approaches?

The data-centric approach is you have data first regardless of React components. React components are used to represent those data. For example, in game development, it's likely that you may have game state in advance to design components. You don't want these data to be controlled by React lifecycle.

On the other hand, with the component-centric approach, you would design components first. Some states can be locally defined in components with useState. Other states will be shared across components. For example, in a GUI intensive app, you want to control UI parts in sync, but they are far away in the component tree.

Note that this is not a ground rule. We could store game state in the component-centric libraries, and UI state in the data-centric libraries. Each library has its own features, so that would be the point of choice.

I would choose valtio for data-centric apps and jotai for component-centric apps.

Let's see the actual examples.

My apps with valtio and jotai

There are two apps I developed each with valtio and jotai.

The first app is called Remote Faces and it uses valtio. It's an app to share your face image with your colleagues to show presense in a remote-work environment.

https://remote-faces.js.org

It has data to be shared with other users. The latest version uses valtio-yjs to sync data with others.

See the GitHub repo for more details:

https://github.com/dai-shi/remote-faces

The second app is called Katachidraw and it uses jotai. This is an SVG-based drawing app.

https://katachidraw.vercel.app

It's actually developed to demonstrate how jotai can extensively used.

The source code is available:

https://github.com/dai-shi/katachidraw

You can also learn the basics in this egghead course.

Summary

It's really hard to suggest which libraries to use in general. The real recommendation is to learn both and understand them.

If data-centric approach vs. component-centric approach discussion makes sense, it may help you to choose one. But still, other features in valtio and jotai are very different. So, you want to at least read their README files.

Another suggestion is, if you really like the syntax of valtio, pick valtio, otherwise pick jotai. If you are even unsure about it, just pick jotai which has less gotchas.

I didn't discuss other libraries in this article. It will be more complicated to compare three or more libraries. Maybe another pair of libraries would be possible to discuss.

Originally published at https://blog.axlight.com on January 30, 2022.