DEV Community: Álvaro N.

Stop Using Context for State: Use an Event-Driven Pattern

Álvaro N. — Tue, 10 Mar 2026 14:26:24 +0000

The Architectural Pitfall Behind React

React assumes that components act as pure functions (returning the same JSX for the same inputs). React components are functions that return React elements (JSX). These elements describe the UI tree. Components may contain state, hooks, and local logic, but their primary role is to describe UI based on inputs.

Each of these nodes can have its own state and uses it to build the user interface.

The Achilles Heel of React

If the state of the Form component is modified, this needs to somehow be reflected in the DOM. How does React handle state change in this component? And its children Input 1 and Input 2? Would they be affected by this state change?

For React to know what changed from one point to another, it calls the function that declares each of these components recursively (the parent, the parent's children, the parent's children's children...) to the end of the branch. After calling all the functions, React compares the new element tree with the previous one and generates a minimal set of DOM mutations if any change is detected.

This behavior, despite being direct, simple, and having guaranteed React the Top spot in the hall of web technologies, brought a disadvantage inherent to the model itself: state changes cause component functions to re-execute down the tree, even when most of the subtree does not depend on that state.

Frameworks such as Solid and modern Angular adopt fine-grained reactivity through signals, where updates propagate only to computations that depend on the changed value.

In the beginning, when React was built, web applications and websites used to be simpler and less ambitious. As the web evolved and grew, more complex needs arose, and with them, heavier components, which increased the cost of re-renders on the web. This is not a design flaw in React. It’s a deliberate architectural trade-off that favors predictability and simplicity over fine-grained reactivity.

Caution...

Because of this, a lot of effort is spent on strategies like react-compiler (a compiler that adds automatic memoization), useMemo, useCallback, and memo (these functions ensure the component/state is kept and reused through a cache, except when a variable in the dependency array changes). However, putting memo everywhere, besides making your code MUCH more verbose...

Having a cache has a trade-off – while it saves memory required for computation and time from having to calculate things, it requires memory for storing old values. - Wing

What If Components Didn’t Re-Render?

Before moving on to the actual implementation, I will show two examples: the first uses an Event-Driven approach to communicate changes to components, and the second uses the traditional approach with useContext. In both examples, I placed a console.log at the root of each component to allow us to observe the reconstruction of the component tree when a state is updated.

Event-Driven Example

The library making the components flash is React Scan. It visually informs you when a component has re-rendered.

Initial render:

app rerendered
form rerendered
input name rerendered
input work rerendered
name rerendered
work rerendered

After typing in the name input:

name rerendered

After typing in the work input:

work rerendered

Not even the input component itself re-rendered, only the Name and Work components re-rendered when typing in the inputs.

Context/Provider Example

Initial render:

app rerendered
form rerendered
input name rerendered
input work rerendered
name rerendered
work rerendered

After typing in the name input:

input name rerendered
input work rerendered
name rerendered
work rerendered

After typing in the work input:

input name rerendered
input work rerendered
name rerendered
work rerendered

The difference is staggering.

Why does this happen?

Although a useContext approach allows moving data just as fluidly through the component tree (and more directly), it carries an inevitable trade-off due to how React handles state updates: when a state changes, the component and its children are rebuilt. Since the context is used in Name and Work components, them and all of its children are rebuilt when a state is modified.

Event-Driven State: The Alternative

Event-driven architecture is made up of event producers (publishers) and event consumers (subscribers)[...]. After an event has been detected, it is transmitted from the event producer to the event consumers through event channels, where an event processing platform processes the event..." - What is event-driven architecture?

(Analogy) Producers grow tomatoes and potatoes, and cooks (consumers) use the tomatoes and potatoes to create recipes (pizzas, pastas, mashed potatoes). The producers send their products to the cooks as soon as they are ready. Therefore, there is no need for the cook to know how, where, or why the tomatoes and potatoes were grown; they simply receive the potatoes and use them to create their recipes.

This approach allows us to move state out of React and control how data flows through the application, so we can handpick which components listen to which changes. The tomato cooks (and only them) will re-render only when the tomato producers send them tomatoes (and the same goes for the potato ones), regardless of where the producers or consumers are in the component tree.

Building an Event-Driven Store From Scratch

This pattern is essentially the same external store model used internally by libraries like Zustand and Redux. So this article can also help you better visualize the data flow using these libraries.

`PubSub` Implementation:

export type EventMapBase = Record<string, unknown>;  

type Listener = () => void;  

export class PubSub<Events extends EventMapBase> {  
  private listeners = new Map<keyof Events, Set<Listener>>();  
  private snapshots = new Map<keyof Events, Events[keyof Events]>();  

  // The subscribe method is responsible for listening to emitted events.
  subscribe<K extends keyof Events>(  
    eventName: K,  
    listener: Listener,  
  ): () => void {  
    const currentListeners =  
      this.listeners.get(eventName) ?? new Set<Listener>();  

    currentListeners.add(listener);  
    this.listeners.set(eventName, currentListeners);  

    return () => {  
      currentListeners.delete(listener);  

      if (currentListeners.size === 0) {  
        this.listeners.delete(eventName);  
      }  
    };  
  }  

  // The publish method is responsible for executing the functions that
  // are listening to a specific event.
  publish<K extends keyof Events>(eventName: K, payload: Events[K]): void {  
    this.snapshots.set(eventName, payload);  

    const currentListeners = this.listeners.get(eventName);  

    if (!currentListeners) {  
      return;  
    }  

    currentListeners.forEach((listener) => {  
      listener();  
    });  
  }  

  getSnapshot<K extends keyof Events>(eventName: K): Events[K] | undefined {  
    return this.snapshots.get(eventName) as Events[K] | undefined;  
  }  
}

This is a basic implementation of PubSub, which will be our centerpiece for creating an event-driven architecture, allowing the data flow outside of React.

EventEmitter and Observables are also types of PubSub (or vice versa). It's also common for methods to be called on, listen, emit, notify, etc.

While in the example the PubSub has very apparent limitations, such as being only synchronous, not being fault-tolerant, and executing listeners one after the other. In production, your PubSub must be much more robust and fault-tolerant than the current example to ensure an efficient solution.

`useSubscribe` Implementation:

useSubscribe is one of the two bridges between PubSub and React. The hook receives a PubSub instance and the identifier of the event to be consumed, integrating it with React using the useSyncExternalStore hook:

import { useMemo, useSyncExternalStore } from "react";  
import { type EventMapBase, PubSub } from "./pub-sub";  

export function useSubscribe<  
  Events extends EventMapBase,  
  K extends keyof Events,  
>(pubSub: PubSub<Events>, eventName: K) { 

  // The `subscribe` function is responsible for notifying `useSyncExternalStore` that a new value is available: 
  const subscribe = useMemo(() => {  
    return (onStoreChange: () => void) =>  
      pubSub.subscribe(eventName, onStoreChange);  
  }, [pubSub, eventName]);

  // The `getSnapshot` function returns the latest value emitted by the PubSub:
  const getSnapshot = useMemo(() => {  
    return () => pubSub.getSnapshot(eventName);  
  }, [pubSub, eventName]);  

  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);  
}

This ensures that components created after events are emitted still receive the most up-to-date data. (The PubSub is capable of informing what the last emitted value was for an event x).

`usePublish` Implementation:

usePublish is the second bridge between PubSub and React. The hook is simple: it receives a PubSub instance and the event identifier to be produced and returns a factory function for those events.

import { PubSub, type EventMapBase } from "./pub-sub";  
import { useCallback } from "react";  

export function usePublish<Events extends EventMapBase, K extends keyof Events>(  
  pubSub: PubSub<Events>,  
  eventName: K,  
) {  
  return useCallback(  
    (payload: Events[K]) => pubSub.publish(eventName, payload),  
    [eventName, pubSub],  
  );  
}

Components used in the PubSub example

function Form() {  
  console.log("form rerendered");  

  return (  
    <form>  
      <Input label="Name" name="name" /> <Input label="Work" name="work" />  
    </form>  
  );  
}  

type InputProps = {  
  label: string;  
  name: keyof AppEvents;  
};  

function Input({ label, name }: InputProps) {  
  console.log("input rerendered");  

  const pubSub = useGetPubSub();  
  const publish = usePublish(pubSub, name as keyof AppEvents);  
  return (  
    <label>  
      {label}: <input onChange={({ target: { value } }) => publish(value)} />  
    </label>  
  );  
}  

function Name() {  
  console.log("name rerendered");  

  const pubSub = useGetPubSub<AppEvents>();  
  const name = useSubscribe(pubSub, "name");  

  return (  
    <p>  
      <b>Name: </b> {name}  
    </p>  
  );  
}  

function Work() {  
  console.log("work rerendered");  

  const pubSub = useGetPubSub<AppEvents>();  
  const work = useSubscribe(pubSub, "work");  

  return (  
    <p>  
      <b>Work: </b> {work}  
    </p>  
  );  
}

In the Input on line 49, the input is uncontrolled; however, there would be no problem implementing it in a controlled way (listening and emitting in the component itself).

Provider with a PubSub instance:

A PubSubProvider is a nice to have that will allow us to inject the PubSub instance into any component below it in the tree. It will only be rendered once during creation, ensuring the singleton aspect to our PubSub.

const PubSubContext = createContext(new PubSub<any>());  

function PubSubProvider(props: PropsWithChildren<{ pubSub: PubSub<any> }>) {  
  return (  
    <PubSubContext.Provider value={props.pubSub}>  
      {props.children}  
    </PubSubContext.Provider>  
  );  
}  

function useGetPubSub<Events extends EventMapBase>() {  
  return useContext(PubSubContext) as PubSub<Events>;  
}

If you are working with CSR (Client-Side Rendering), the PubSub can be a constant exported from another file. In an SSR or SSG context, it's better that it is instantiated within the component to avoid issues with sharing the PubSub instance between different requests.

Putting all the pieces together:

export default function PubSubBased() {  
  console.log("app rerendered");  

  // This way, we will create a singleton that will be used by all components.
  // Using a Context is safer in environments that run on the server.
  const [store] = useState(() => new PubSub());  

  return (  
    <PubSubProvider pubSub={store}>  
      <Form />  
      <Name />  
      <Work />  
    </PubSubProvider>  
  );  
}

Context Based tree used in example

const StoreContext = createContext({  
  name: "",  
  work: "",  
  setForm: (_key: string, _value: string) => {},  
});  

// Ideally, decoupling the data and memoizing it would decrease
// the amount of re-renders, although this solution
// increases the complexity of the example (and wouldn't reach the
// efficiency of the other method, test it yourself).
function StoreProvider(props: PropsWithChildren) { 
  const [form, setForm] = useState({  
    name: "",  
    work: "",  
  });  

  const value = useMemo(  
    () => ({  
      name: form.name,  
      work: form.work,  
      setForm: (key: string, value: string) => {  
        setForm((currentValues) => ({  
          ...currentValues,  
          [key]: value,  
        }));  
      },  
    }),  
    [form],  
  );  

  return (  
    <StoreContext.Provider value={value}>  
      {props.children}  
    </StoreContext.Provider>  
  );  
} 

function useStore() {  
  return useContext(StoreContext);  
}  

function Form() {  
  console.log(`form rerendered`);  

  return (  
    <form>  
      <Input label="Name" name="name" /> <Input label="Work" name="work" />  
    </form>  
  );  
}  

type InputProps = {  
  label: string;  
  name: string;  
};  

function Input({ label, name }: InputProps) {  
  console.log(`input ${name} rerendered`);  

  const { setForm } = useStore();  
  return (  
    <label>  
      {label}:{" "}  
      <input onChange={({ target: { value } }) => setForm(name, value)} />  
    </label>  
  );  
}  

function Name() {  
  console.log("name rerendered");  

  const { name } = useStore();  

  return (  
    <p>  
      <b>Name: </b> {name}  
    </p>  
  );  
}  

function Work() {  
  console.log("work rerendered");  

  const { work } = useStore();  

  return (  
    <p>  
      <b>Work: </b> {work}  
    </p>  
  );  
}  

export default function PropBased() {  
  return (  
    <StoreProvider>  
      <Form />  
      <Name />  
      <Work />  
    </StoreProvider>  
  );  
}

Final recap, trade-offs, and tips.

Advantages

No unnecessary re-renders: The fact of moving data from very distant components or moving a large flow of data doesn't cause cascading re-renders to all components.
Simple and library-free: For simple or localized solutions, just this approach is enough to solve useContext problems while maintaining functionality.
Decoupling: Component hierarchy is irrelevant to the data flow. All that matters for PubSub is that some components are producers and others are consumers.
Framework Independence: The PubSub logic can be reused in other libraries (Vue, Angular) or Vanilla code.
Prop Drilling Prevention: Removes the need to pass callbacks or states multiple levels down the component tree.

Disadvantages

Reinventing the wheel: State management libraries like Zustand (mainly) and Redux use this approach in their internal infrastructure and are much more powerful than doing everything by hand.
Complexity in testing/debugging: By moving the data flow outside of React, you lose the ability to use its own tools to analyze bugs and test. It's up to you to implement these structures according to your project.

Tips

Not every component needs to be controlled (listen and emit data). If you have a button, input, modal, form, or whatever, that performs a task but is not modified by it, it's possibly an uncontrolled component that emits events without re-rendering itself. In these cases, avoid using useSubscribe or setState in these components and you will have a considerable performance gain.
It's not necessary to pass the states captured by useSubscribe via prop to children in most cases: if the component is a child, it will already be re-rendered. You can just call const value = useSubscribe(pubSub, "value") in the child component and React will take care of the rest.
Use useSubscribe directly in the component where the data will be used and only with the data that will be used. Storing many different pieces of data in the event can, and will, undo the advantage of accurately re-rendering only a few components. Granularity prevents components from re-rendering unnecessarily.
The current PubSub and useSubscribe implementation uses strict equality (Object.is) to avoid re-renders when the state doesn't change, and doesn't implement functions capable of selecting data from complex objects (like selecting the second property from a {first: {second: 'data'} } payload), while only accepting constant objects (readonly). A more robust solution would be to implement shallow compare and strict selectors, whose addition in this code would fall outside the scope of this article.

Thanks for reading!!!

I hope this architecture helps you write web apps/applications with React in a more performant and consistent way.

If you have any questions or information to add, I am open to comments!

How to Train a Model in TensorFlow.js on Massive Datasets (Out-of-Core Learning).

Álvaro N. — Sun, 01 Mar 2026 05:08:11 +0000

You wake up one day and decide: "I'm going to create a machine learning model".

On the first day, you have a JSON file with 100 entries and 100 WebP images to train a Convolutional Neural Network (CNN) for detection. You read the JSON, load the 100 images, put everything in memory (which should consume about 100 MB), and everything works perfectly.

After a week, you've taken a lot of photos, and your data has increased 10 times. Now, with 1000 entries, your model performs much better. But then, you look at your task manager and your Node.js training process is already consuming 1 GB. Again, you think: "not a problem, my computer has 16 GB of RAM", and you carry on happily with your model.

However... how much can the memory handle?

After a month collecting images and filling out your JSON, you come across a 10 GB .zip file of photos and thousands of entries. The modus operandi is the same: you extract the files to the usual folder and run the training script.

Kaboom!!!

Your computer freezes, the fan screams, and the process quickly exhausts the RAM. The result? The dreaded OOM (Out of Memory) that crashes your script.

You then think of two alternatives: spend a fortune to upgrade your setup to 64 GB of RAM and move on with life, or... ask yourself: "is there a way to read a file, train the model on it, remove this file from memory, and pull the next one, in a continuous cycle?".

This way, you could feed the model with a dataset that wouldn't fit entirely in memory through a continuous flow (data stream), without ever blowing up your machine's RAM.

The answer to your problem lies in the Generators and their ability to create a data streaming.

Generators, Iterators and Lazy Evaluation

In short, generators (function*) are basically functions that manufacture "iterators" in JavaScript. Analogously, the functioning of an iterator is conceptually similar to a paginated list. You want to read the next item? Click next, the item will be fetched and processed. Want the next one? Click again. When you reach the last item and click next, the list will inform you that it's over.

In technical terms, this is called lazy evaluation. Data isn't allocated in memory until you explicitly ask for it. The code only runs on demand.

Let's take an example:

export function* someGenerator() {
  console.log("Inside: First log");
  yield 1;

  console.log("Inside: Second log");
  yield 2;

  console.log("Inside: Third log");
  yield 3;

  console.log("Inside: Fourth log");
}

const iterator = someGenerator();

console.log("Outside:", iterator.next().value);
console.log("Outside:", iterator.next().value);
console.log("Outside:", iterator.next().value);
console.log("Outside:", iterator.next().value);

With the mindset of a normal function, you would think: "The code will run to the end, store all these yield instructions in an array and return everything to me". But the output proves otherwise:

Inside: First log
Outside: 1
Inside: Second log
Outside: 2
Inside: Third log
Outside: 3
Inside: Fourth log
Outside: undefined

On the first next() call, the execution goes to the first yield and pauses. The function's state is frozen. When we call next() again, it resumes exactly from where it left off. At the last log, there are no more yields. The function reaches the end and the iterator returns { value: undefined, done: true }.

Whoa, powerful. But how do we use it in practice?

Generators are our golden goose for creating infinite processing pipelines without clogging the memory. See an example applying this concept to reading image files:

export async function* datasetGenerator(dataPath) {
  const dir = await fs.opendir(dataPath);

  for await (const dirent of dir) {
    if (!dirent.isFile() || (!dirent.name.endsWith(".webp") && !dirent.name.endsWith(".jpg"))) {
      continue;
    }

    const buffer = await fs.readFile(path.join(dataPath, dirent.name));
    yield { 
      buffer, 
      labelValue: getLabelFromName(dirent.name) 
    };
  }
}

The fact that it's an asynchronous function doesn't change the essence of the generator; the difference is that internally we iterate with promises. The magic here is that there is only one image loaded in the buffer and in memory at a time.

How to use Generators in TensorFlow.js

The TensorFlow library has a native and direct method to convert our custom generator into an object of the tf.data.Dataset class. This object is the heart of the data pipeline in TF.js.

// TF.js requires the function reference, not the instantiated iterator
const dataset = tf.data.generator(() => datasetGenerator('./my-dataset'));

"But I need to process the data first!"

It's not necessary to pollute the generator function with heavy preprocessing logic. The Dataset class contains powerful utility methods for us to process (or map) the data as it flows through the pipeline:

const preparedDataset = dataset.map(({ buffer, labelValue }) => {
    return tf.tidy(() => {
      const imageTensor = tf.node.decodeImage(buffer, 3);
      const xs = imageTensor.div(255);
      const ys = tf.tensor1d([labelValue]);
      return { xs, ys };
    });
});

The Mandatory `{xs, ys}` Format

TensorFlow.js needs to know who is who in your data.

xs (features): What we are going to use to predict.
ys (labels): What we want to predict.

The model.fitDataset(dataset) method requires that each return from your pipeline has the exact format of an object containing xs (input tensors) and ys (output tensors).

const trainableDataset = preparedDataset.map(({ normalizedImage, label }) => ({
  xs: normalizedImage,
  ys: label
}));

The Dataset Class Arsenal

Building the pipeline is like a conveyor belt in a factory: you order the workers (functions) and each one does a thing at their stage and passes it forward.

With this, it's possible to apply various processings to your dataset before feeding them to the model, such as:

.shuffle(1000): Creates a fixed-size buffer in memory (e.g., 1000 items). As your generator processes items, they fill this buffer. When the model needs an item, it randomly picks an item from this buffer, and the generator immediately replaces it with the next fetched item.

A VERY important note about the shuffle method: if your dataset is ordered, for example: 1000 photos of cats and then 1000 photos of dogs, the buffer will only randomize among the 1000 photos of cats, which can cause catastrophic forgetting. To avoid this, you must randomize your data or the way you read it.

.batch(32): Groups a number of samples into a single batch. Your {xs: Tensor, ys: Tensor} object containing 1 image becomes a group containing 32 images in the first dimension. (Essential for taking advantage of TensorFlow's matrix calculations).
.prefetch(2): Makes the generator read 2 batches of files in parallel with the model training and leaves them ready in the queue for when the training finishes. (Basically, training while processing).
.take(10) / .skip(10): Selects only 10 items or ignores the first 10 items.
.filter(fn): Works like the native array filter, removing unwanted items from the stream before they reach the model.

Putting it all together (pipeline example):

import fs from 'fs/promises';
import path from 'path';
import * as tf from '@tensorflow/tfjs-node';

export async function* datasetGenerator(dataPath) {
  const dir = await fs.opendir(dataPath);

  for await (const dirent of dir) {
    if (!dirent.isFile() || (!dirent.name.endsWith(".webp") && !dirent.name.endsWith(".jpg"))) {
      continue;
    }

    const buffer = await fs.readFile(path.join(dataPath, dirent.name));
    yield { 
      buffer, 
      labelValue: getLabelFromName(dirent.name) 
    };
  }
}

const finalDataset = tf.data
  .generator(() => datasetGenerator("./train_data"))
  .shuffle(1000) 
  .map(({ buffer, labelValue }) => {
    return tf.tidy(() => {
      const xs = tf.node.decodeImage(buffer, 3);
      const ys = tf.tensor1d([labelValue]);
      return { xs, ys };
    });
  })
  .batch(32) 
  .map(({ xs, ys }) => {
    return tf.tidy(() => {
      const normalizedXs = xs.div(255);
      return { xs: normalizedXs, ys };
    });
  })   
  .prefetch(2);

await model.fitDataset(finalDataset, { 
  epochs: 32,
});

But is that it, only advantages? (Some trade-offs of the approach)

Although this approach reads only the files necessary to compose a given training batch, it will probably increase your model's training time. If you previously had your dataset entirely in memory, the model could immediately request your data and iterate over it to train.

Now, the approach is to read, prepare, train, and discard, keeping in memory only the data that is being used. Reading this data should take some time, and the same file might be read several times if the model is configured to iterate over the data more than once.

Despite allowing greater scalability in the amount of data, this approach takes a toll on time and I/O and CPU work.

By swapping in-memory loading for lazy-evaluated generators, we successfully trade I/O speed for infinite memory scalability. This ensures our models can learn from massive datasets without melting our machines.

Thanks for reading!!!

[Boost]

Álvaro N. — Sun, 02 Mar 2025 22:12:37 +0000

Creating a reusable Design System between React and React Native with Tamagui

Álvaro N. ・ Mar 27 '24

#react #reactnative #javascript #designsystem

Creating a reusable Design System between React and React Native with Tamagui

Álvaro N. — Wed, 27 Mar 2024 01:35:42 +0000

TLDR;

You can check the repository generated by this article here.

🚀 Introduction

Many times, while developing mobile applications with React Native, I have thought about the possibility of reusing components in both web and mobile contexts. Recently, I came across a library called Tamagui that allows components to be shared in both React Web and React Native.

So I had the challenge of creating a separate component library that could be used in both React Web and React Native.

📦 Starting the project with Vite

Let's start by creating a template with vite. According to the Vite documentation, it is a build tool that aims to provide a faster and leaner development experience for modern web projects.

pnpm create vite@latest

╰─○ pnpm create vite@latest
✔ Project name: library
✔ Select a framework: › React
✔ Select a variant: › TypeScript + SWC

This setup will give us an initial configuration with React and TypeScript geared towards web application development. However, what we really need is a configuration that allows us to develop components to be distributed and used by other applications.

To achieve this, let's adjust our vite.config.ts to configure the development mode for a library.

// /vite.config.ts
import { defineConfig } from "vite";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    lib: { 
      // defining the entry point of our component library.
      entry: "src/index.ts", 
        // defining the distribution formats of our library (CommonJS and ESM).
        formats: ["cjs", "es"]  
      },
      rollupOptions: {
        // defining the external dependencies of our library.
        // These dependencies will not be included in the final bundle.
      external: ["react", "react/jsx-runtime", "react-dom"], 
    },
  },
});

In the file specified in entry, let's create the entry point of our library.

// /src/index.ts
export * from "./components";

let's create an example component.

// /src/components/Text/Text.tsx

export const Text = () => {
  return <p>Text</p>;
};

our file structure will look like this:

  /src
    /components
      /text
        text.tsx
        index.ts
      index.ts
    index.ts
  vite.config.ts

When the pnpm vite build command is executed, some files will be generated inside the dist folder with the name of your library.

// /dist/library.js

import { jsx as t } from "react/jsx-runtime";
const i = () => /* @__PURE__ */ t("text", { children: "Text!" });
export {
  i as Text
};

Note that there are no external dependencies included in the final bundle because we defined them as external in vite.config.ts. For this reason, we need to specify in the package.json that these dependencies should come from outside (those installing the library should have them as dependencies). To do this, let's move React and ReactDOM to the devDependencies field since we only need these dependencies during development, and add them to the peerDependencies section of our package.json.

  "peerDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  },
  "devDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
    // other dependencies
  }

This article by Naveera explains the difference between each type of dependency.

Let's also update the scripts section of the package.json to include the vite build command:

// /package.json
  "scripts": {
    "build": "vite build"
  },
  "devDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "typescript": "5.4.3",
    "vite": "5.2.3",
    "vite-plugin-dts": "3.7.3"
  },
  "peerDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }

⛓️ Integrating with Typescript

When observing the distribution folder (dist) generated by Vite when running the build command, you may notice that our TypeScript types are not present. This happens because Vite transforms TypeScript into JavaScript to run in the context of browsers, where types are not necessary. However, in our case, as we are building the project to share with other developers, types are essential for bug prevention and improved development experience.

Let's address this issue by installing some new plugins for Vite:

  pnpm add -D vite-plugin-dts

// /vite.config.ts
import { defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import tsconfigPaths from "vite-tsconfig-paths";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    // The dtsPlugin will generate type declaration files for each file inside the src folder.
    dtsPlugin(),
  ],
  build: {
    lib: { 
      entry: "src/index.ts", 
      // Setting the distribution formats for our library (CommonJS and ESM).
      formats: ["cjs", "es"] 
    },
    rollupOptions: {
      // Setting the external dependencies for our library. 
      // These dependencies will not be included in the final bundle.
      external: ["react", "react/jsx-runtime", "react-dom"],
    },
  },
});

We will also make an adjustment in the tsconfig.json and package.json to configure the generation of sourcemaps from the generated types. This will allow the editor to provide the original source code instead of the compiled code when we search for references to imported libraries.

// /tsconfig.json
    // ...
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    // ...

// /package.json
  // ...
  "source": "./src/index.ts",
  "files": [
    "dist",
    "src"
  ],
  // ...

♟ Tree Shaking

By default, Vite merges all source files into a single .js file to be served to the browser. You can observe this behavior by looking at the generated files in the distribution folder:

dist/
  components/
    Text/
      text.d.ts
      text.d.ts.map
      index.d.ts
      index.d.ts.map
    index.d.ts
    index.d.ts.map
  index.d.ts
  index.d.ts.map
  library.js
  library.cjs

All JavaScript content has been merged into a single file, while the types remain isolated from each other. However, this behavior may not be ideal in the context of library development. With all source code in a single file, when someone uses a component or function generated by your library, all JavaScript content will be included in the final bundle, even if they are only using a few components. This increases the final size of the application and consequently the weight of your application/website. In this section, we will configure Vite to consider each file in the project as a separate module that imports other modules. This will allow bundlers like Vite and webpack to remove unused components in the final build.

To configure each file as an entry point, we will use the glob library, which allows us to find each file within the src folder using a minimatch expression.

pnpm add -D glob @types/node

The @types/node library will allow us to use internal node libraries with TypeScript, such as node:url and node:path.

Let's update the rollup configuration in vite.config.ts so that it maps all files within the src folder and adds them as entry points in the rollup configuration.

// /vite.config.ts

import { defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import { dirname, extname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { glob } from "glob";

// Absolute path of the current directory from the root of the file system.
const __dirname = dirname(fileURLToPath(import.meta.url)); // /home/user/folder/library or C:\Users\user\folder\library

const computeAllSrcFiles = (): Record<string, string> => {
  // Find all .ts and .tsx files within the src folder.
  const files = glob.sync(["src/**/*.{ts,tsx}"]);

  const paths = files.map((file) => [
    // Remove the file extension and calculate the relative path from the src folder.
    /* key: */ relative(
      "src",
      file.slice(0, file.length - extname(file).length)
    ),

    // Convert the file path to an absolute path.
    /* value: */ fileURLToPath(new URL(file, import.meta.url)),
  ]);

  return Object.fromEntries(paths);
  // Convert the array of paths into an object.
};

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [dtsPlugin()],
  build: {
    lib: {
      // Set the entry point of our component library for Vite.
      entry: resolve(__dirname, "src/main.ts"),
      // Set the distribution formats for our library (CommonJS and ESM).
      formats: ["cjs", "es"],
      // Set the output file name.
      // `entryName` is the file name without the extension,
      // and `format` is the distribution format.
      fileName(format, entryName) {
        if (format === "es") return `${entryName}.js`;
        return `${entryName}.${format}`;
      },
    },
    rollupOptions: {
      // Set the external dependencies for our library.
      external: ["react", "react/jsx-runtime", "react-dom"],
      // The `input` configuration in rollupOptions allows you to provide an object
      // specifying output files pointing to source code files.
      input: computeAllSrcFiles(),
    },
  },
});

Now, our distribution folder will contain the following generated files:

/dist
  /components
    Button.cjs
    Button.d.ts
    Button.d.ts.map
    Button.js
    Button.cjs
    index.d.ts
    index.d.ts.map
    index.js
  index.cjs
  index.d.ts
  index.d.ts.map
  index.js

💅 Setting up Storybook

Storybook is a tool for building components and pages in isolation, which is very useful for testing and documenting interfaces and components. When developing a component library, it is common to want to have a catalog of our components and documentation of their properties and behaviors, streamlining the development and usage process of the components.

We can set up our initial Storybook file with the following command:

# At the time of writing this article, the version of Storybook is 8.0.4
npx storybook@latest init

This will generate a folder called .storybook with files named main.ts and preview.ts, along with a folder of examples called stories.

  .storybook/
    main.ts
    preview.ts
  src/ 
    stories/

The stories folder contains components and examples of how you can use Storybook, so it can be safely removed. Let's delete the stories folder and improve our Text component by including a text.stories.tsx file and a typings file text.types.ts.

// /src/components/text/text.types.ts

import { ComponentPropsWithoutRef, ReactNode } from "react";

export type TextProps = ComponentPropsWithoutRef<"p"> & {
  // The ComponentPropsWithoutRef interface provides the base typing
  // for the <p> element without adding a ref.
  children?: ReactNode;
};

// /src/components/text/text.stories.tsx

import type { Meta, StoryObj } from "@storybook/react";
import { Text } from "./text";

export default {
  component: Text,
  title: "Components/Text",
} satisfies Meta<typeof Text>;

type Story = StoryObj<typeof Text>;

export const StoryDefault: Story = {
  // Here, we are configuring Storybook to render the text component and name it as Default.
  name: "Default",
  render: (props) => <Text {...props} />,
};

If you are unsure about the content within the stories file, the official documentation of Storybook is a good starting point.

// /src/components/text/text.tsx

import { TextProps } from "./text.types";

export const Text = ({ children, ...props }: TextProps) => (
  <p {...props}>{children}</p>
);

All this structuring is optional, and you can organize the files and styles however you like.

If you start Storybook with the command pnpm storybook, you will notice that our text component has already been rendered on the screen.

🧪 Adding Vitest with React Testing Library

vitest is a testing framework similar to jest that integrates well with projects using Vite. It allows us to reuse plugins and configurations already set up in the vite.config.ts, making the test setup process easier.

Since we are testing the front-end, we will also rely on the React Testing Library, which provides support for rendering components and custom queries in the DOM.

Let's start by installing the necessary dependencies and creating a vitest.config.ts file in the project root:

pnpm add -D vitest @testing-library/jest-dom @testing-library/react jsdom

// /vitest.config.ts

import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react-swc";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
    // In this file, we will configure the integration of vitest
    // with the React Testing Library
    setupFiles: ["./src/setup-tests.ts"],
  },
});

// /src/setup-tests.ts
import "@testing-library/jest-dom/vitest";

Some adjustments will also need to be made in the tsconfig.json so that TypeScript recognizes the global variables provided by vitest:

// /tsconfig.json
  "compilerOptions": {
    // add reference to vitest/globals in the types property.
    "types": ["vitest/globals"], 
    // ...

Finally, let's add a command in the scripts section of the package.json to run the tests more easily:

// /package.json
  "scripts": {
    "test": "vitest"
  },

Finally, it's time to create a test for our text component and see the result in the terminal:

// /src/components/text/text.test.tsx

import { render, screen } from "@testing-library/react";

import { Text } from "./text";

describe("[Components]: Text", () => {
  it("renders without crash", () => {
    render(<Text>Hello World</Text>)
    const component = screen.getByText("Hello World");
    expect(component).toBeDefined();
  });
});

 ✓ src/components/text/text.test.tsx (1)
   ✓ [Components]: Text (1)
     ✓ renders without crash

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  15:29:37
   Duration  383ms

👾 Adding Tamagui

Tamagui is a tool that enables code sharing between different platforms that support React (web, android, ios), making styling in the React environment more pleasant and faster.

⚠️ Before we continue: Limitations regarding PNPM

There are some limitations when using pnpm to configure environments involving React Native, and even Storybook, due to the way the package manager resolves its dependencies. Unfortunately, React Native doesn't work well with the structure created to resolve dependencies using symbolic links. For this reason, we will use a flag in the .npmrc file that tells pnpm to create a file structure similar to npm and yarn in the node_modules folder:

// /.npmrc
# https://pnpm.io/npmrc#node-linker
node-linker=hoisted

It will also be necessary to remove the type: "module" declaration inside the package.json file so that @tamagui can function correctly.

After this configuration, it is necessary to use pnpm install so that it recreates the node_modules with the new structure.

Continuing...

Let's start by installing the necessary dependencies to configure the tamagui environment in our library.

pnpm add expo expo-linear-gradient -D react-native @tamagui/core @tamagui/vite-plugin

For some reason, tamagui has a dependency on expo-linear-gradient internally, so it is necessary to install both expo and expo-linear-gradient libraries.

Some adjustments also need to be made to the structure of our peerDependencies to include @tamagui and react-native as external dependencies. Since our library works in different contexts, some dependencies are not necessarily required:

// /package.json

 "peerDependencies": {
    "@tamagui/core": "1.91.4",
    "@tamagui/vite-plugin": "1.91.4",
    // The metro-plugin is responsible for making tamagui work in the react-native context.
    "@tamagui/metro-plugin": "1.91.4",
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "react-native": "0.73.5"
  },
  // We will use this field to define peer dependencies that are not required.
  "peerDependenciesMeta": {
    // We will not use react-dom in the react-native context.
    "react-dom": {
      "optional": true
    },
    // We will not use react-native in the web context.
    "react-native": {
      "optional": true
    },
    // Using vite as a bundler is not mandatory.
    "@tamagui/vite-plugin": {
      "optional": true
    },
    // Using metro as a bundler is not mandatory.
    "@tamagui/metro-plugin": {
      "optional": true
    }
  },

Let's also configure the vite.config.ts to include @tamagui/core and react-native as external dependencies:

// /vite.config.ts

    rollupOptions: {
      // Setting up the external dependencies of our library.
      external: [
        "react",
        "react/jsx-runtime",
        "react-dom",
        "react-native",
        "@tamagui/core",
      ],

It will also be necessary to create an initial configuration file for tamagui called tamagui.config.ts. I will create this file in the src/themes folder.

// /src/themes/tamagui.config.ts
import { createTamagui } from "@tamagui/core";

// You are free to define tamagui's tokens and themes as you wish.
// In our case, we will define only two colors and two themes.
const config = createTamagui({
  fonts: {},
  shorthands: {},
  themes: {
    // It is necessary to configure at least one theme in the application.
    night: { color: "#005" },
    sun: { color: "#FA0" },
  },
  tokens: {
    color: {
      primary: "#000",
      secondary: "#FFF",
    },
    radius: {},
    size: {},
    space: {},
    zIndex: {},
  },
});

export default config;

After defining the tokens, let's configure TypeScript to recognize the custom types defined in tamagui.config.ts by creating a file src/types.d.ts and adding the following configuration:

// src/types.d.ts

import config from "./themes/tamagui.config";

export type AppConfig = typeof config;

declare module "@tamagui/core" {
  interface TamaguiCustomConfig extends AppConfig {}
}

We extract the config type and assign it to the TamaguiCustomConfig type. This will allow TypeScript to recognize the constant types defined in src/themes/tamagui.config.ts.

To make the tamagui token and theme system work, it is necessary to create a provider that injects the tamagui context into the application. Let's create a file called theme-provider.tsx in the src/themes folder.

// /src/themes/theme-provider.tsx
import { TamaguiProvider, TamaguiProviderProps } from "@tamagui/core";
import { PropsWithChildren } from "react";
import appConfig from "./tamagui.config";

type ThemeProviderProps = PropsWithChildren<TamaguiProviderProps>;

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return (
    <TamaguiProvider config={appConfig} {...props}>
      {children}
    </TamaguiProvider>
  );
}

This provider should be used by Storybook, tests, and the library consumer in order for the tokens defined in tamagui.config.ts to work.

👾🧪 Tamagui with Vitest

To make Tamagui work in the context of tests with Vitest, it is necessary to add the plugin responsible for processing Tamagui components and add the ThemeProvider in each render() call.

Let's install the Vite plugin and add it to vitest.config.ts:

pnpm add -D @tamagui/vite-plugin

// /vitest.config.ts

import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react-swc";
import { createRequire } from "module";

const require = createRequire(import.meta.url);
const { tamaguiPlugin } = require("@tamagui/vite-plugin");

export default defineConfig({
  plugins: [
    react(),
    tamaguiPlugin({
      components: ["@tamagui/core"],
      // The tamagui plugin is added to the plugins section of vitest, pointing to our custom token configuration.
      config: "src/themes/tamagui.config.ts",
    }),
  ],
  test: {
    environment: "jsdom",
    globals: true,
    server: {
      // Since the tests run in the node context, this configuration is necessary to remove ESM imports and exports.
      deps: {
        inline: ["@tamagui"],
      },
    },
    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
    setupFiles: ["./src/setup-tests.ts"],
  },
});

To add the provider to all tests in a practical way, we can create a custom render that will be used by all tests instead of the traditional render exported by the @testing-library/react library. Let's create a file in the src/__tests__/setup.tsx directory that will contain our custom render. This render should be imported instead of the render from @testing-library/react to ensure that our tests work.

// /src/__tests__/setup.tsx

import {
  queries,
  Queries,
  render as nativeRender,
  RenderOptions,
  RenderResult,
} from "@testing-library/react";
import "@testing-library/jest-dom";
import { TamaguiProvider } from "@tamagui/core";
import { ReactElement } from "react";
import config from "../themes/tamagui.config";

const render = <
  Q extends Queries = typeof queries,
  Container extends DocumentFragment | Element = HTMLElement,
  BaseElement extends DocumentFragment | Element = Container,
>(
  ui: ReactElement,
  renderOptions?: RenderOptions<Q, Container, BaseElement>
): RenderResult<Q, Container, BaseElement> =>
  nativeRender(<TamaguiProvider config={config}>{ui}</TamaguiProvider>, {
    ...renderOptions,
  });

export * from "@testing-library/react";
export { render };

After these adjustments, our project is now configured to run tests even with Tamagui components. Finally, let's integrate our text component with Tamagui:

// /src/components/text/text.styles.ts

import { Text, styled } from "@tamagui/core";

export const StyledText = styled(Text, {
  color: "$black",
});

// /src/components/text/text.types.tsx
import { GetProps } from "@tamagui/core";
import type { StyledText } from "./text.styles";

export type TextProps = GetProps<typeof StyledText>;

// /src/components/text/text.tsx

import { forwardRef } from 'react';
import { TamaguiElement } from '@tamagui/core';
import type { TextProps } from './text.types';
import { StyledText } from '.';

export const Text = (props: TextProps) => (
   <StyledText {...props}>
     {children}
   </StyledText>
)

// /src/components/text/text.test.tsx

import { Text } from "./text";

import { render, screen } from "../../__tests__/setup";

describe("[Components]: Text", () => {
  it("renders without crash", () => {
    render(<Text>Hello World</Text>);
    const component = screen.getByText("Hello World");
    expect(component).toBeDefined();
  });
});

When running the test, you will see that the integration is already working:

✓ src/components/text/text.test.tsx (1)
   ✓ [Components]: Text (1)
     ✓ renders without crash

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  21:36:14
   Duration  460ms

👾💅 Configuring with Storybook

To make Tamagui work within the context of Storybook, the steps are similar to those for tests. You need to inject the Tamagui plugin into Storybook and add the provider to each story.

We can add the plugin to Storybook as follows:

// /.storybook/main.ts

import { tamaguiPlugin } from "@tamagui/vite-plugin";
import type { StorybookConfig } from "@storybook/react-vite";
import tsconfigPaths from "vite-tsconfig-paths";

const config: StorybookConfig = {
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
  ],
  docs: {
    autodocs: true,
  },
  env: (config) => ({
    ...config,
    // Setting the tamagui target to render for web
    TAMAGUI_TARGET: "web",
  }),
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
  stories: [
    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)",
    "../src/**/*.mdx",
    "../docs/**/*.mdx",
  ],
  viteFinal: (config, { configType }) => {
    config.define = {
      // Environment variables required for @Tamagui to work correctly
      ...config.define,
      "process.env.NODE_ENV":
        configType === "PRODUCTION" ? "production" : "development",
      "process.env.STORYBOOK": true,
    };

    config.plugins!.push(
      tamaguiPlugin({
        // Reference from the absolute path to the tamagui.config.ts
        config: "/src/themes/tamagui.config.ts",
      }),
    );

    return config;
  },
};
export default config;

// /.storybook/preview.tsx

import type { Preview } from "@storybook/react";

import { ThemeProvider } from "../src/themes/theme-provider";

const preview: Preview = {
  decorators: [
    (Story) => (
      // We add the provider to render in all stories:
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
  ],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /date$/i,
      },
    },
  },
};

export default preview;

After these configurations, we can run pnpm storybook and see the component working in the Storybook itself.

🦋 Publishing with changesets

The changesets library is designed to automate the generation of changelogs, publishing, and version updating of the library. This ensures that users who download your design system will be able to handle version management based on semantic versions.

🧹 Cleaning up before publishing

If you tried running the library build command before reaching this step, you may have noticed that there are some files in our distribution folder related to unit tests and the Storybook itself. The build command may not have even worked on its own.

This happens because we defined all files in the /src folder as an entry point for a module in our vite.config.ts, which is causing it to also consider test and documentation files when generating the files.

We can adjust this within the computeAllSrcFiles function in vite.config.ts, configuring it to ignore all files that are not source code:

// /vite.config.ts

const computeAllSrcFiles = (): Record<string, string> => {
  // Find all .ts and .tsx files within the src folder.
  const files = glob.sync(["src/**/*.{ts,tsx}"], {
    ignore: [
    "src/**/*.stories.tsx",
  "src/**/__tests/**",
  "src/**/*.test.{ts,tsx}",
  "src/setup-tests.ts",
  "types.d.ts",
  ], // minimatch patterns we want the glob to ignore.
  });

It is also necessary to configure the dts plugin to ignore these files in the generation of d.ts and d.ts.map files:

// vite.config.ts

// ...

export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",     
        "src/**/*.stories.tsx",
      "src/**/__tests/**",
      "src/**/*.test.{ts,tsx}",
      "src/setup-tests.ts",
      "types.d.ts"
      ],
      include: ["src"],
    }),
  ],
  // ...

You may also notice that some files like button.types.js were generated without any JavaScript content. This is because these files only contain type declarations in their source code, which cannot be transpiled to JavaScript.

We can remove these empty generated files by creating a custom plugin for Vite:

// vite.config.ts
const removeEmptyFiles = (): PluginOption => ({
  generateBundle(_, bundle) {
    for (const name in bundle) {
      const file = bundle[name];
      if (file.type !== "chunk") return;

      if (file.code.trim() === "") delete bundle[name];
      if (file.code.trim() === '"use strict";') delete bundle[name];
    }
  },
  name: "remove-empty-files",
});

export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",     
        "src/**/*.stories.tsx",
        "src/**/__tests/**",
        "src/**/*.test.{ts,tsx}",
        "src/setup-tests.ts",
        "types.d.ts"
      ],
      include: ["src"],
    }),
    removeEmptyFiles(),
  ],
  // ...

This function will check if any data chunk is empty or only contains the "use strict;" declaration. If true, this content will be removed from the final bundle.

At the end of this step, our vite.config.ts will look like this:

// /vite.config.ts

import { PluginOption, defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import tsconfigPaths from "vite-tsconfig-paths";
import { dirname, extname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { glob } from "glob";

// Absolute path of the current directory from the root of the file system.
const __dirname = dirname(fileURLToPath(import.meta.url)); // /home/user/folder/library or C:\Users\user\folder\library

const computeAllSrcFiles = (): Record<string, string> => {
  // Find all .ts and .tsx files within the src folder.
  const files = glob.sync(["src/**/*.{ts,tsx}"], {
    ignore: ["src/**/*.stories.tsx", "src/**/*.test.tsx", "src/setup-tests.ts"],
  });

  const paths = files.map((file) => [
    // Remove the file extension and calculate the relative path from the src folder.
    /* key: */ relative(
      "src",
      file.slice(0, file.length - extname(file).length)
    ),

    // Convert the file path to an absolute path.
    /* value: */ fileURLToPath(new URL(file, import.meta.url)),
  ]);

  return Object.fromEntries(paths);
  // Convert the array of paths into an object.
};

const removeEmptyFiles = (): PluginOption => ({
  generateBundle(_, bundle) {
    for (const name in bundle) {
      const file = bundle[name];
      if (file.type !== "chunk") return;

      if (file.code.trim() === "") delete bundle[name];
      if (file.code.trim() === '"use strict";') delete bundle[name];
    }
  },
  name: "remove-empty-files",
});

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",
        "src/**/*.stories.tsx",
        "src/**/*.test.tsx",
        "src/setup-tests.ts",
      ],
      include: ["src"],
    }),
    removeEmptyFiles(),
  ],
  build: {
    lib: {
      // Setting the entry point of our component library.
      entry: resolve(__dirname, "src/main.ts"),
      // Setting the distribution formats of our library (CommonJS and ESM).
      formats: ["cjs", "es"],
      // Setting the output file name.
      // EntryName is the file name without the extension,
      // and format is the distribution format.
      fileName(format, entryName) {
        if (format === "es") return `${entryName}.js`;
        return `${entryName}.${format}`;
      },
    },
    rollupOptions: {
      // Setting the external dependencies of our library. (They won't be included in the bundle)
      external: [
        "react",
        "react/jsx-runtime",
        "react-dom",
        "@tamagui/core",
        "@tamagui/vite-plugin",
      ],
      input: computeAllSrcFiles(),
    },
  },
});

Continuing...

To install the changesets library, run this command in the terminal:

pnpm install -D @changesets/cli && npx changeset init

After installing the library, some files were generated in the .changeset folder, and some commands need to be added to our application's package.json:

// package.json
  // ...
   scripts: {
  // ...
  // The changeset library's add command creates a new version entry
  // in the .changeset folder with the major, minor, or patch scopes
  // representing semantic versioning.
  "changeset": "changeset add", 
  // The publish command is responsible for publishing the library
  // to artifacts such as npm, Azure, AWS, etc.
  "publish":  "changeset publish",
  // The version command is used to consume all the entries created
  // by the changeset command and calculate the resulting version.
  // This command also generates a CHANGELOG file containing each
  // version already published by the library.
  "version":  "changeset version"
  // ...

We will also need to adjust our package.json to point to the correct files in our distribution folder:

// /package.json
{
  // The name to be published for your library,
  // if it's in a public registry, the name must be unique.
  "name": "library",
  // Indicates whether the library can be published to public registries:
  "private": false,
  // The changeset library will automatically increment the version
  // whenever the changeset version command is used:
  "version": "0.0.0",
  // We point to the original source code:
  "source": "./src/index.ts",
  // We point to the transpiled code in CommonJS format:
  "main": "dist/index.cjs",
  // We point to the transpiled code in ESM format:
  "module": "dist/index.js",
  // We include all the folders that should be added when publishing
  // the library:
  "files": [
    "dist",
    "src",
    "package.json",
    "CHANGELOG",
    "README.md"
  ],
  // ...
},

// .changeset/config
{
  "$schema":  "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog":  "@changesets/cli/changelog",
  "commit":  false,
  "fixed":  [],
  "linked":  [],
  "access":  "public", // To publish publicly, set it to `public`
  "baseBranch":  "main", // Set it to the name of your main branch
  "updateInternalDependencies":  "patch",
  "ignore":  []
}

After these adjustments, you can generate a changeset using the following commands in the terminal:

╰─± pnpm changeset    
🦋  What kind of change is this for library? (current version is 0.0.0) · minor
🦋  Please enter a summary for this change (this will be in the changelogs).
🦋    (submit empty line to open external editor)
🦋  Summary · First version of my library
🦋  
🦋  === Summary of changesets ===
🦋  minor:  library
🦋  
🦋  Is this your desired changeset? (Y/n) · true
🦋  Changeset added! - you can now commit it
🦋  
🦋  If you want to modify or expand on the changeset summary, you can find it here
🦋  info /home/user/documents/library/.changeset/pink-spoons-laugh.md

This command will generate a randomly named markdown file inside the .changeset folder called changeset. You can modify it as you prefer before actually generating a new version, and you can also accumulate as many changesets as needed before releasing new versions.

To generate a new version of the library, you should run the version command. This command will calculate how many changesets exist inside the .changeset folder and update the version key inside the package.json file, as well as document each of these files inside the CHANGELOG.md file.

pnpm run version
🦋  All files have been updated. Review them and commit at your leisure

// / CHANGELOG.md

# library

## 0.1.0

### Minor Changes

- First version of my library

This changelog file contains the textual content of all the changesets generated within the .changeset folder.

// /package.json
"name":  "library",
"private":  false,
"version":  "0.1.0",

The version of our library has also been updated in the package.json, according to the semantic scope defined in each changeset (major, minor, or patch).

Finally, to publish the library, you should run the command pnpm run publish.

pnpm run publish
> changeset publish

🦋  info npm info library
🦋  warn Received 404 for npm info "library"
🦋  info library is being published because our local version (0.1.0) has not been published on npm
🦋  info Publishing "library" at "0.1.0"

This will cause the contents specified within the files field in our package.json to be published to the npm registry. You should authenticate with npm and follow the steps provided in the terminal to publish your library. :D

Thank you for reading !!!!

You can see all the code generated during the development of this library in my Github repository:

https://github.com/alvarogfn/tamagui-design-system-vite-example

I hope this article has been helpful to you in some way, and I appreciate any suggestions for improvement!

Criando um Design System reutilizável entre React e React Native com Tamagui

Álvaro N. — Wed, 27 Mar 2024 00:14:50 +0000

TLDR;

Você pode conferir o repositório gerado por esse artigo clicando aqui.

🚀 Introdução

Muitas vezes, no desenvolvimento de aplicações mobile com React Native me veio a cabeça a possibilidade de reutilização de componentes no contexto web/mobile. Recentemente, conheci uma biblioteca chamada Tamagui que permite que os componentes sejam compartilhados tanto no React Web quando no React Native.

Então tive o desafio de criar uma biblioteca de componentes separada que pudesse ser utilizada tanto no React Web quanto no React Native.

📦 Iniciando o projeto com vite

Vamos começar criando um template com vite. De acordo com a documentação do Vite, ele é uma ferramenta de construção que tem como objetivo fornecer uma experiência de desenvolvimento mais rápida e leve para projetos web modernos.

pnpm create vite@latest

╰─○ pnpm create vite@latest
✔ Project name: library
✔ Select a framework: › React
✔ Select a variant: › TypeScript + SWC

Esse setup vai nos dar uma configuração inicial com React e TypeScript orientado para o desenvolvimento de aplicações web, porém, o que precisamos mesmo é de uma configuração que permita o desenvolvimento de componentes para serem distribuídos para serem utilizados por outras aplicações.

Para isso, vamos ajustar o nosso vite.config.ts para configurar o modo de desenvolvimento de uma biblioteca.

// /vite.config.ts
import { defineConfig } from "vite";

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    lib: { 
      // definindo o ponto inicial da nossa biblioteca de componentes.
      entry: "src/index.ts", 
      // definindo os formatos de distribuição da nossa biblioteca (CommonJS e ESM).
      formats: ["cjs", "es"]  
    },
    rollupOptions: {
      // definindo as dependências externas da nossa biblioteca.
      // Essas dependências não serão incluídas no bundle final.
      external: ["react", "react/jsx-runtime", "react-dom"], 
    },
  },
});

No arquivo especificado em entry, vamos criar o ponto de entrada da nossa biblioteca.

// /src/index.ts
export * from "./components";

e vamos criar um componente de exemplo.

// /src/components/Text/Text.tsx

export const Text = () => {
  return <p>Text</p>;
};

No final, nossa estrutura de arquivos se parecerá com isso:

  /src
    /components
      /text
        text.tsx
        index.ts
      index.ts
    index.ts
  vite.config.ts

Quando o comando pnpm vite build for executado, alguns arquivos serão gerados dentro da pasta dist com o nome da sua biblioteca.

// /dist/library.js

import { jsx as t } from "react/jsx-runtime";
const i = () => /* @__PURE__ */ t("text", { children: "Text!" });
export {
  i as Text
};

Note que não há nenhuma dependência externa incluída no bundle final, pois definimos as dependências como externas no vite.config.ts. Por esse motivo, precisamos informar no package.json que essas dependências devem vir de fora (quem está instalando a biblioteca deve ter elas como dependência). Para isso, vamos mover o React e o ReactDOM para o campo de devDependencies, pois precisamos dessas dependências apenas enquanto desenvolvemos, e adicionar elas na seção de peerDependencies do nosso package.json.

  "peerDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  },
  "devDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
    // outras dependências
  }

Esse artigo da Naveera explica bem a diferença entre cada tipo de dependência.

Vamos também atualizar a seção de scripts do package.json para incluir o comando de build do vite:

// /package.json
  "scripts": {
    "build": "vite build"
  },
  "devDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "typescript": "5.4.3",
    "vite": "5.2.3",
    "vite-plugin-dts": "3.7.3"
  },
  "peerDependencies": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }

⛓️ Integrando com o Typescript

Ao observar a pasta de distribuição (dist) gerada pelo vite ao rodar o comando de build, você pode notar que os nossos tipos do typescript não estão presentes, isso acontece pois o vite transforma o Typescript em Javascript para rodar no contexto dos navegadores, onde os tipos não são necessários. No nosso caso que estamos buildando o projeto para compartilhar com outros desenvolvedores, os tipos acabam sendo essenciais para a prevenção de bugs e melhora na experiência de desenvolvimento.

Vamos ajustar esse detalhe instalando alguns plugins novos para o vite:

  pnpm add -D vite-plugin-dts

// /vite.config.ts
import { defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import tsconfigPaths from "vite-tsconfig-paths";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    // O plugin dtsPlugin vai gerar arquivos de 
    // tipagem para cada arquivo dentro da pasta src.
    dtsPlugin(),
  ],
  build: {
    lib: { 
      entry: "src/index.ts", 
      // Definindo os formatos de distribuição da nossa biblioteca (CommonJS e ESM).
      formats: ["cjs", "es"] 
    },
    rollupOptions: {
      // Definindo as dependências externas da nossa biblioteca. 
      // Essas dependências não serão incluídas no bundle final.
      external: ["react", "react/jsx-runtime", "react-dom"],
    },
  },
});

Também vamos fazer um ajuste no tsconfig.json e no package.json para configurar a geração de sourcemaps a apartir dos tipos gerados. Isso vai permitir que o editor forneça o código fonte original ao invés do código compilado quando buscarmos as referências das bibliotecas importadas.

// /tsconfig.json
    // ...
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    // ...

// /package.json
  // ...
  "source": "./src/index.ts",
  "files": [
    "dist",
    "src"
  ],
  // ...

♟ Tree Shaking

Por padrão, o vite tem o comportamento de mesclar todos os arquivos fonte do seu código em um único arquivo .js para ser servido para o navegador. Vocês podem notar isso ao observar os arquivos gerados na pasta de distribuição:

dist/
  components/
    Text/
      text.d.ts
      text.d.ts.map
      index.d.ts
      index.d.ts.map
    index.d.ts
    index.d.ts.map
  index.d.ts
  index.d.ts.map
  library.js
  library.cjs

Todo conteúdo javascript foi mesclado dentro de um único arquivo, enquanto os tipos permaneceram isolados entre sí, porém esse comportamento pode não ser o ideal no contexto do desenvolvimento de bibliotecas. Com todo código fonte dentro de um único arquivo, quando alguém utilizar algum componente ou função gerado pela sua biblioteca, todo o conteúdo javascript será incluído no bundle final, mesmo que você esteja utilizando apenas alguns componentes. Isso aumenta o tamanho final da aplicação e consequentemente o peso do seu aplicativo/site. Nessa seção, vamos configurar o vite para que ele considere cada arquivo do projeto como se fosse um módulo separado, que importa outros módulos, isso vai permitir que bundlers como vite e webpack removam os componentes que não estão sendo utilizados no build final.

Para configurar cada arquivo como um entry point, vamos utilizar a biblioteca glob, que vai nos permitir encontrar cada arquivo dentro da pasta src a partir de uma expressão minimatch.

pnpm add -D glob @types/node

A biblioteca @types/node vai permitir que usemos bibliotecas internas do node com typescript, como node:url e node:path.

Vamos atualizar as configurações do rollup no vite.config.ts para que ele mapeie todos os arquivos dentro da pasta src e os adicione como entry point nas configurações do rollup.

// /vite.config.ts

import { defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import { dirname, extname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { glob } from "glob";

// Caminho absoluto do diretório atual a partir da raiz do sistema de arquivos.
const __dirname = dirname(fileURLToPath(import.meta.url)); // /home/user/pasta/library ou C:\Users\user\pasta\library

const computeAllSrcFiles = (): Record<string, string> => {
  // Encontra todos os arquivos .ts e .tsx dentro da pasta src.
  const files = glob.sync(["src/**/*.{ts,tsx}"]);

  const paths = files.map((file) => [
    // Remove a extensão do arquivo e calcula o caminho relativo a partir da pasta src.
    /* key: */ relative(
      "src",
      file.slice(0, file.length - extname(file).length)
    ),

    // Converte o caminho do arquivo para um caminho absoluto.
    /* value: */ fileURLToPath(new URL(file, import.meta.url)),
  ]);

  return Object.fromEntries(paths);
  // Converte o array de caminhos em um objeto.
};

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [dtsPlugin()],
  build: {
    lib: {
      // Definindo o ponto inicial da nossa biblioteca de componentes para o vite.
      entry: resolve(__dirname, "src/main.ts"),
      // Definindo os formatos de distribuição da nossa biblioteca (CommonJS e ESM).
      formats: ["cjs", "es"],
      // Definindo o nome do arquivo de saída. 
      // `entryName` é o nome do arquivo sem a extensão, 
      // e `format` é o formato de distribuição.
      fileName(format, entryName) {
        if (format === "es") return `${entryName}.js`;
        return `${entryName}.${format}`;
      },
    },
    rollupOptions: {
      // Definindo as dependências externas da nossa biblioteca. 
      external: ["react", "react/jsx-runtime", "react-dom"],
      // A configuração `input` do rollupOptions permite que você forneça um objeto
      // específicando arquivos de saída apontando para arquivos do código fonte.
      input: computeAllSrcFiles(),
    },
  },
});

Agora, a nossa pasta de distribuição vai conter os seguintes arquivos gerados:

  /dist
    /components
      Button.cjs
      Button.d.ts
      Button.d.ts.map
      Button.js
      Button.cjs
      index.d.ts
      index.d.ts.map
      index.js
    index.cjs
    index.d.ts
    index.d.ts.map
    index.js

💅 Configurando o Storybook

O Storybook é uma ferramenta de construção de componentes e páginas de forma isolada, muito útil para construção de testes e documentação de interfaces e componentes. Ao desenvolver uma biblioteca de componentes, é comum querermos ter a disposição um catalogo dos nossos componentes e a documentação das suas propriedades e comportamentos, agilizando o processo de desenvolvimento e utilização dos componentes.

Podemos configurar o nosso arquivo inicial do Storybook com o comando:

# No momento de escrita desse artigo, a versão do storybook é a 8.0.4
npx storybook@latest init

Isso vai gerar uma pasta chamada .storybook com arquivos chamados main.ts e preview.ts, além de uma pasta de exemplos chamada stories.

  .storybook/
    main.ts
    preview.ts
  src/ 
    stories/

A pasta de stories contém componentes e exemplos de como você pode utilizar o storyboook, então ela pode ser removida sem medo. Vamos excluir a pasta stories, e melhorar o nosso componente de Text para incluir
um arquivo de text.stories.tsx, e um arquivo de tipagens text.types.ts.

// /src/components/text/text.types.ts

import { ComponentPropsWithoutRef, ReactNode } from "react";

export type TextProps = ComponentPropsWithoutRef<"p"> & {
  // A interface ComponentPropsWithoutRef fornece a tipagem base 
  // do elemento <p> sem adicionar um ref.
  children?: ReactNode;
};

// /src/components/text/text.stories.tsx

import type { Meta, StoryObj } from "@storybook/react";
import { Text } from "./text";

export default {
  component: Text,
  title: "Components/Text",
} satisfies Meta<typeof Text>;

type Story = StoryObj<typeof Text>;

export const StoryDefault: Story = {
  // Aqui, estamos configurando o storybook para 
  // renderizar o componente de texto e nomeá-lo como Default.
  name: "Default",
  render: (props) => <Text {...props} />,
};

Se você está em dúvida sobre conteúdo dentro do arquivo de stories, a própria documentação do storybook é um bom começo.

// /src/components/text/text.tsx

import { TextProps } from "./text.types";

export const Text = ({ children, ...props }: TextProps) => (
  <p {...props}>{children}</p>
);

Toda essa estruturação é opcional, e você pode organizar os arquivos e estilos do jeito que bem entender.

Se você iniciar o Storybook com o comando pnpm storybook, vai notar que o nosso componente de texto já foi renderizado na tela.

🧪 Adicionando Vitest com React Testing Library

O vitest é um framework de testes semelhante ao jest, que integra muito bem a ambientes com o vite configurado. Podemos reutilizar os plugins e configurações já inseridas dentro do vite.config.ts, facilitando o processo de configuração dos testes.

Como estamos em um contexto de testes para o front-end, vamos contar também com o apoio da biblioteca React Testing Library que fornece suporte para a renderização de componentes e queries customizadas na DOM.

Vamos começar instalando as dependências necessárias e criando um vitest.config.ts na raiz do projeto:

pnpm add -D vitest @testing-library/jest-dom @testing-library/react jsdom

// /vitest.config.ts

import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react-swc";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    globals: true,
    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
    // Nesse arquivo, vamos configurar a integração do vitest
    // com a biblioteca React Testing Library
    setupFiles: ["./src/setup-tests.ts"],
  },
});

// /src/setup-tests.ts
import "@testing-library/jest-dom/vitest";

Também será necessário fazer alguns ajustes no tsconfig.json para que o Typescript reconheça as variáveis globais fornecidas pelo vitest:

// /tsconfig.json
  "compilerOptions": {
    // adicione referencia ao vitest/globals na propriedade types.
    "types": ["vitest/globals"], 
    // ...

Por fim, vamos adicionar um comando na seção de scripts do package.json para rodar os testes com maior facilidade:

// /package.json
  "scripts": {
    "test": "vitest"
  },

Finalmente, é hora de criar um teste para o nosso componente de texto e ver o resultado no terminal:

// /src/components/text/text.test.tsx

import { render, screen } from "@testing-library/react";

import { Text } from "./text";

describe("[Components]: Text", () => {
  it("renders without crash", () => {
    render(<Text>Hello World</Text>)
    const component = screen.getByText("Hello World");
    expect(component).toBeDefined();
  });
});

 ✓ src/components/text/text.test.tsx (1)
   ✓ [Components]: Text (1)
     ✓ renders without crash

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  15:29:37
   Duration  383ms

👾 Adicionando Tamagui

O Tamagui é uma ferramenta que possibilita o compartilhamento de código entre diferentes plataformas que suportam o React (web, android, ios), tornando a estilização no ambiente React mais agradável e rápido.

⚠️ Antes de continuarmos: Limitações em relação ao PNPM

Existem algumas limitações em relação ao uso de pnpm ao configurar ambientes que envolvem o react native, e até mesmo o storybook devido a forma com que o gerenciador de pacotes resolve suas dependências. Infelizmente, o React Native não funciona muito bem com a estrutura criada para resolver as dependências a partir de links simbólicos. Por esse motivo, vamos utilizar de uma flag no .npmrc diz ao pnpm que queremos uma estrutura de arquivos semelhante ao npm e yarn na node_modules:

// /.npmrc
# https://pnpm.io/npmrc#node-linker
node-linker=hoisted

Também será necessário remover a declaração de type: "module" dentro do arquivo package.json para que o @tamagui possa funcionar corretamente.

Após essa configuração, é necessário utilizar pnpm install para que ele re-crie a node_modules com a nova estrutura.

Continuando...

Vamos começar instalando as dependências necessárias para configurar o ambiente do tamagui na nossa biblioteca.

pnpm add expo expo-linear-gradient -D react-native @tamagui/core @tamagui/vite-plugin

Por algum motivo, o tamagui tem dependência do expo-linear-gradient internamente, então é necessário instalar ambas as bibliotecas expo e expo-linear-grandient.

Também será necessário fazer alguns ajustes na estrutura das nossas peerDependencies para incluir o @tamagui e o react-native como dependências externas. Como nossa biblioteca funciona em contextos diferentes, algumas dependências não são necessariamente obrigatórias:

// /package.json

 "peerDependencies": {
    "@tamagui/core": "1.91.4",
    "@tamagui/vite-plugin": "1.91.4",
    // O metro-plugin é responsável por fazer o tamagui funcionar no contexto do react-native.
    "@tamagui/metro-plugin": "1.91.4",
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "react-native": "0.73.5"
  },
  // Vamos usar esse campo para definir as peer dependências que não são obrigatórias.
  "peerDependenciesMeta": {
    // Não usaremos react-dom no contexto do react-native.
    "react-dom": {
      "optional": true
    },
    // não usaremos o react-native no contexto do web.
    "react-native": {
      "optional": true
    },
    // Não é obrigatório utilizar o vite como bundler;
    "@tamagui/vite-plugin": {
      "optional": true
    },
    // Não é obrigatório utilizar o metro como bundler;
    "@tamagui/metro-plugin": {
      "optional": true
    }
  },

Vamos configurar também o vite.config.ts para incluir o @tamagui/core e o react-native como uma dependência externa:

// /vite.config.ts

    rollupOptions: {
      // Definindo as dependências externas da nossa biblioteca.
      external: [
        "react",
        "react/jsx-runtime",
        "react-dom",
        "react-native",
        "@tamagui/core",
      ],

Também será necessário criar um arquivo de configuração inicial para o tamagui chamado tamagui.config.ts, irei criar esse arquivo na pasta src/themes.

// /src/themes/tamagui.config.ts
import { createTamagui } from "@tamagui/core";

// Você é livre para definir os tokens e temas do tamagui como quiser.
// no nosso caso, vamos definir apenas duas cores e dois temas.
const config = createTamagui({
  fonts: {},
  shorthands: {},
  themes: {
    // É necessário configurar ao menos um tema na aplicação.
    night: { color: "#005" },
    sun: { color: "#FA0" },
  },
  tokens: {
    color: {
      primary: "#000",
      secondary: "#FFF",
    },
    radius: {},
    size: {},
    space: {},
    zIndex: {},
  },
});

export default config;

Após a definição dos tokens, vamos configurar o Typescript para reconhecer os tipos customizados definidos no tamagui.config.ts criando um arquivo src/types.d.ts e adicionando a seguinte configuração:

// src/types.d.ts

import config from "./themes/tamagui.config";

export type AppConfig = typeof config;

declare module "@tamagui/core" {
  interface TamaguiCustomConfig extends AppConfig {}
}

Nós extraímos o tipo de config e atribuímos ao tipo de TamaguiCustomConfig. Isso vai permitir que o typescript reconheça os tipos constantes definidos no src/themes/tamagui.config.ts.

Para que o sistema de tokens e temas do tamagui funcione, é necessário criar um provider que injete o contexto do tamagui na aplicação. Vamos criar um arquivo chamado theme-provider.tsx na pasta src/themes.

// /src/themes/theme-provider.tsx
import { TamaguiProvider, TamaguiProviderProps } from "@tamagui/core";
import { PropsWithChildren } from "react";
import appConfig from "./tamagui.config";

type ThemeProviderProps = PropsWithChildren<TamaguiProviderProps>;

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return (
    <TamaguiProvider config={appConfig} {...props}>
      {children}
    </TamaguiProvider>
  );
}

Esse provider deverá ser utilizado pelo storybook, testes e pelo consumidor da biblioteca para que os tokens definidos pelo tamagui.config.ts funcionem.

👾🧪 Tamagui com Vitest

Para que o Tamagui funcione no contexto dos testes com o vitest, é necessário adicionar o plugin responsável pelo processamento dos componentes do tamagui e adicionar o ThemeProvider em cada chamada render().

Vamos instalar o plugin do vite e adicioná-lo no vitest.config.ts:

pnpm add -D @tamagui/vite-plugin

// /vitest.config.ts

import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react-swc";
import { createRequire } from "module";

const require = createRequire(import.meta.url);
const { tamaguiPlugin } = require("@tamagui/vite-plugin");

export default defineConfig({
  plugins: [
    react(),
    tamaguiPlugin({
      components: ["@tamagui/core"],
      // O plugin do tamagui foi colocado na seção de plugins do vitest, apontando para nossa configuração personalizada de tokens.
      config: "src/themes/tamagui.config.ts",
    }),
  ],
  test: {
    environment: "jsdom",
    globals: true,
    server: {
      // Como os testes rodam no contexto do node, essa configuração é necessária para remover os imports e exports do ESM.
      deps: {
        inline: ["@tamagui"],
      },
    },
    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
    setupFiles: ["./src/setup-tests.ts"],
  },
});

Para adicionar o provider em todos os testes de forma prática, podemos criar um render customizado que será utilizado por todos os testes ao invés do render tradicional exportado pela biblioteca @testing-library/react. vamos criar um arquivo no diretório src/__tests__/setup.tsx que conterá o nosso render customizado. Esse render deve ser importado no lugar do render do @testing-library/react para garantir que nossos testes funcionem.

// /src/__tests__/setup.tsx

import {
  queries,
  Queries,
  render as nativeRender,
  RenderOptions,
  RenderResult,
} from "@testing-library/react";
import "@testing-library/jest-dom";
import { TamaguiProvider } from "@tamagui/core";
import { ReactElement } from "react";
import config from "../themes/tamagui.config";

const render = <
  Q extends Queries = typeof queries,
  Container extends DocumentFragment | Element = HTMLElement,
  BaseElement extends DocumentFragment | Element = Container,
>(
  ui: ReactElement,
  renderOptions?: RenderOptions<Q, Container, BaseElement>
): RenderResult<Q, Container, BaseElement> =>
  nativeRender(<TamaguiProvider config={config}>{ui}</TamaguiProvider>, {
    ...renderOptions,
  });

export * from "@testing-library/react";
export { render };

Após esses ajustes, o nosso projeto já está configurado para rodar os testes mesmo com os componentes do Tamagui. finalmente, vamos integrar o nosso componente de texto com o Tamagui:

// /src/components/text/text.styles.ts

import { Text, styled } from "@tamagui/core";

export const StyledText = styled(Text, {
  color: "$black",
});

// /src/components/text/text.types.tsx
import { GetProps } from "@tamagui/core";
import type { StyledText } from "./text.styles";

export type TextProps = GetProps<typeof StyledText>;

// /src/components/text/text.tsx

import { forwardRef } from 'react';
import { TamaguiElement } from '@tamagui/core';
import type { TextProps } from './text.types';
import { StyledText } from '.';

export const Text = (props: TextProps) => (
   <StyledText {...props}>
     {children}
   </StyledText>
)

// /src/components/text/text.test.tsx

import { Text } from "./text";

import { render, screen } from "../../__tests__/setup";

describe("[Components]: Text", () => {
  it("renders without crash", () => {
    render(<Text>Hello World</Text>);
    const component = screen.getByText("Hello World");
    expect(component).toBeDefined();
  });
});

Ao rodar o teste, você verá que a integração já está funcionando:

✓ src/components/text/text.test.tsx (1)
   ✓ [Components]: Text (1)
     ✓ renders without crash

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  21:36:14
   Duration  460ms

👾💅 Configurando com Storybook

Para fazer o Tamagui funcionar no contexto do storybook, os passos são semelhantes aos dos testes, você precisa injetar o plugin do tamagui no storybook e adicionar o provider em cada story.

Podemos adicionar o plugin ao storybook da seguinte forma:

// /.storybook/main.ts

import { tamaguiPlugin } from "@tamagui/vite-plugin";
import type { StorybookConfig } from "@storybook/react-vite";
import tsconfigPaths from "vite-tsconfig-paths";

const config: StorybookConfig = {
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-interactions",
  ],
  docs: {
    autodocs: true,
  },
  env: (config) => ({
    ...config,
    // Definindo o target do tamagui para renderizar para web
    TAMAGUI_TARGET: "web",
  }),
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
  stories: [
    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)",
    "../src/**/*.mdx",
    "../docs/**/*.mdx",
  ],
  viteFinal: (config, { configType }) => {
    config.define = {
      // variáveis de ambiente necessárias para que o @Tamagui entenda
      ...config.define,
      "process.env.NODE_ENV":
        configType === "PRODUCTION" ? "production" : "development",
      "process.env.STORYBOOK": true,
    };

    config.plugins!.push(
      tamaguiPlugin({
        // Referencia a partir do caminho absoluto para o tamagui.config.ts
        config: "/src/themes/tamagui.config.ts",
      }),
    );

    return config;
  },
};
export default config;

// /.storybook/preview.tsx

import type { Preview } from "@storybook/react";

import { ThemeProvider } from "../src/themes/theme-provider";

const preview: Preview = {
  decorators: [
    (Story) => (
      // Colocamos o provider para renderizar em todos os stories:
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
  ],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /date$/i,
      },
    },
  },
};

export default preview;

Após essas configurações, já podemos rodar pnpm storybook e ver o componente funcionando no próprio storybook.

🦋 Publicando com changesets

A biblioteca changesets é desenhada para automatizar a geração de changelogs, publicação e atualização da versão da biblioteca. Isso garante que os usuários que baixarem o seu design system serão capazes de lidar com o gerenciamento de versão a partir de versões semânticas.

🧹 Fazendo uma limpeza antes da publicação

Se você tentou rodar o comando de build da biblioteca antes de chegar nessa etapa, você pode ter notado que existem alguns arquivos na nossa pasta de distribuição relacionados aos testes de unidade e ao próprio storybook. Talvez o comando de build nem tenha funcionado por sí só.

Isso acontece pois definimos que todos os arquivos da pasta /src como um entry-point para um módulo no nosso vite.config.ts, o que está fazendo com que ele também considere os arquivos de teste e documentação ao gerar os arquivos.

Podemos ajustar isso dentro da função computeAllSrcFiles no vite.config.ts, configurando-o para ignorar todos os arquivos que não são código fonte:

// /vite.config.ts

const computeAllSrcFiles = (): Record<string, string> => {
  // Encontra todos os arquivos .ts e .tsx dentro da pasta src.
  const files = glob.sync(["src/**/*.{ts,tsx}"], {
    ignore: [
    "src/**/*.stories.tsx",
    "src/**/__tests/**",
    "src/**/*.test.{ts,tsx}",
    "src/setup-tests.ts",
    "types.d.ts",
    ], // minimatch que queremos que o glob ignore.
  });

Também é necessário configurar o plugin dts para ignorar esses arquivos na geração de arquivos d.ts e d.ts.map:

// vite.config.ts

// ...

export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",     
        "src/**/*.stories.tsx",
        "src/**/__tests/**",
        "src/**/*.test.{ts,tsx}",
        "src/setup-tests.ts",
        "types.d.ts"
      ],
      include: ["src"],
    }),
  ],
  // ...

Você também pode notar que alguns arquivos como o button.types.js foram gerados sem conteúdo javascript nenhum. Isso é porque esses arquivos só contém incluem declarações de tipo no seu código fonte, o que não é possível transpilar para javascript.

Podemos remover esses arquivos vazios gerados criando um plugin customizado para o vite:

// vite.config.ts
const removeEmptyFiles = (): PluginOption => ({
  generateBundle(_, bundle) {
    for (const name in bundle) {
      const file = bundle[name];
      if (file.type !== "chunk") return;

      if (file.code.trim() === "") delete bundle[name];
      if (file.code.trim() === '"use strict";') delete bundle[name];
    }
  },
  name: "remove-empty-files",
});

export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",     
        "src/**/*.stories.tsx",
        "src/**/__tests/**",
        "src/**/*.test.{ts,tsx}",
        "src/setup-tests.ts",
        "types.d.ts"
      ],
      include: ["src"],
    }),
    removeEmptyFiles(),
  ],
  // ...

Essa função vai verificar se algum chunk de dado está vazio ou se apenas contém a declaração de "use strict;", se verdadeiro, esse conteúdo será removido do bundle final.

Ao final dessa etapa, o nosso vite.config.ts estará assim:

// /vite.config.ts

import { PluginOption, defineConfig } from "vite";
import dtsPlugin from "vite-plugin-dts";
import tsconfigPaths from "vite-tsconfig-paths";
import { dirname, extname, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { glob } from "glob";

// Caminho absoluto do diretório atual a partir da raiz do sistema de arquivos.
const __dirname = dirname(fileURLToPath(import.meta.url)); // /home/user/pasta/library ou C:\Users\user\pasta\library

const computeAllSrcFiles = (): Record<string, string> => {
  // Encontra todos os arquivos .ts e .tsx dentro da pasta src.
  const files = glob.sync(["src/**/*.{ts,tsx}"], {
    ignore: ["src/**/*.stories.tsx", "src/**/*.test.tsx", "src/setup-tests.ts"],
  });

  const paths = files.map((file) => [
    // Remove a extensão do arquivo e calcula o caminho relativo a partir da pasta src.
    /* key: */ relative(
      "src",
      file.slice(0, file.length - extname(file).length)
    ),

    // Converte o caminho do arquivo para um caminho absoluto.
    /* value: */ fileURLToPath(new URL(file, import.meta.url)),
  ]);

  return Object.fromEntries(paths);
  // Converte o array de caminhos em um objeto.
};

const removeEmptyFiles = (): PluginOption => ({
  generateBundle(_, bundle) {
    for (const name in bundle) {
      const file = bundle[name];
      if (file.type !== "chunk") return;

      if (file.code.trim() === "") delete bundle[name];
      if (file.code.trim() === '"use strict";') delete bundle[name];
    }
  },
  name: "remove-empty-files",
});

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    dtsPlugin({
      exclude: [
        "node_modules",
        "src/**/*.stories.tsx",
        "src/**/*.test.tsx",
        "src/setup-tests.ts",
      ],
      include: ["src"],
    }),
    removeEmptyFiles(),
  ],
  build: {
    lib: {
      // Definindo o ponto inicial da nossa biblioteca de componentes.
      entry: resolve(__dirname, "src/main.ts"),
      // Definindo os formatos de distribuição da nossa biblioteca (CommonJS e ESM).
      formats: ["cjs", "es"],
      // Definindo o nome do arquivo de saída.
      // EntryName é o nome do arquivo sem a extensão,
      // e format é o formato de distribuição.
      fileName(format, entryName) {
        if (format === "es") return `${entryName}.js`;
        return `${entryName}.${format}`;
      },
    },
    rollupOptions: {
      // Definindo as dependências externas da nossa biblioteca. (Que não serão incluídas no bundle)
      external: [
        "react",
        "react/jsx-runtime",
        "react-dom",
        "@tamagui/core",
        "@tamagui/vite-plugin",
      ],
      input: computeAllSrcFiles(),
    },
  },
});

Continuando...

Para instalar a biblioteca changesets, rode esse comando no terminal:

pnpm install -D @changesets/cli && npx changeset init

Após a instalação da biblioteca, alguns arquivos foram gerados na pasta .changeset, e alguns comandos devem ser adicionados no package.json da nossa aplicação:

// package.json
   scripts: {
    // ...
    // O comando add da biblioteca changeset
    // cria uma nova entrada de versão na pasta 
    // .changeset com os escopos major, minor ou patch
    // representando o versionamento semântico
    "changeset": "changeset add", 
    // O comando de publish é responsável por publicar
    // a biblioteca em artefatos como o `npm`, `azure`, 'aws`...
    "publish":  "changeset publish",
    // O comando version é usado para consumir
    // todas as entradas criadas pelo comando de changeset
    // e calcular a versão resultante. Esse comando também
    // gera um arquivo de CHANGELOG contendo cada versão
    // já publicada pela biblioteca. 
    "version":  "changeset version"
    // ...

Também será necessário ajustar o nosso package.json para apontar para os arquivos corretos na nossa pasta de distribuição:

// /package.json
{
    // O nome a ser publicado da sua biblioteca,
    // caso seja em um registro público, o nome deve ser único.
    "name":  "library",
    // Indica que a biblioteca pode ser publicada em registros públicos:
    "private":  false, 
    // A biblioteca changeset aumentará a versão automaticamente sempre
    // que o comando changeset version for usado:
    "version":  "0.0.0",
    // Apontamos para o código fonte original:
    "source":  "./src/index.ts",
    // Apontamos para o código transpilado no formado Common Javascript:
    "main":  "dist/index.cjs",
    // Apontamos para o código transpilado no formado ESM:
    "module":  "dist/index.js",
    // Incluímos todas as pastas que devem ser adicionadas ao publicar 
    // a biblioteca:
    "files":  [
        "dist",
        "src",
        "package.json",
        "CHANGELOG",
        "README.md"
    ],
    // ...
},

// .changeset/config
{
    "$schema":  "https://unpkg.com/@changesets/config@3.0.0/schema.json",
    "changelog":  "@changesets/cli/changelog",
    "commit":  false,
    "fixed":  [],
    "linked":  [],
    "access":  "public", // Para publicar publicamente, defina como `public`
    "baseBranch":  "main", // Defina com o nome da sua branch principal
    "updateInternalDependencies":  "patch",
    "ignore":  []
}

Após esses ajustes, você pode gerar um changeset através dos comando no terminal:

╰─± pnpm changeset    
🦋  What kind of change is this for library? (current version is 0.0.0) · minor
🦋  Please enter a summary for this change (this will be in the changelogs).
🦋    (submit empty line to open external editor)
🦋  Summary · Primeira versão da minha biblioteca
🦋  
🦋  === Summary of changesets ===
🦋  minor:  library
🦋  
🦋  Is this your desired changeset? (Y/n) · true
🦋  Changeset added! - you can now commit it
🦋  
🦋  If you want to modify or expand on the changeset summary, you can find it here
🦋  info /home/user/documents/library/.changeset/pink-spoons-laugh.md

Esse comando vai gerar um arquivo markdown de nome aleatório dentro da pasta .changeset chamado de changeset, você pode modifica-lo do jeito que preferir antes de gerar de fato uma nova versão, e você também pode acumular quantos changesets precisar antes de lançar novas versões.

Para gerar uma nova versão da biblioteca, você deve executar o comando version, esse comando vai calcular quantos changesets existem dentro da pasta .changeset e fazer a atualização da chave de version dentro do package.json, além de documentar cada um desses arquivos dentro do arquivo CHANGELOG.md

pnpm run version
🦋  All files have been updated. Review them and commit at your leisure

// / CHANGELOG.md

# library

## 0.1.0

### Minor Changes

- Primeira versão da minha biblioteca

Esse arquivo de changelog contém o conteúdo textual de todos os changesets gerados dentro da pasta .changeset.

// /package.json
"name":  "library",
"private":  false,
"version":  "0.1.0",

A versão da nossa biblioteca também foi alterada no package.json, de acordo com o escopo semântico definido em cada changeset (major, minor ou patch).

Finalmente, para publicar a biblioteca, você deve rodar o comando pnpm run publish

pnpm run publish
> changeset publish

🦋  info npm info library
🦋  warn Received 404 for npm info "library"
🦋  info library is being published because our local version (0.1.0) has not been published on npm
🦋  info Publishing "library" at "0.1.0"

Isso vai fazer com que os conteúdos especificados dentro do campo files no nosso package.json sejam publicados no registro do npm. Você deve autenticar com o npm e seguir os passos definidos no terminal para que sua biblioteca seja publicada. :D

Obrigado por ler !!!!

Você pode ver todo o código gerado durante a codificação dessa biblioteca no meu repositório do Github:

https://github.com/alvarogfn/tamagui-design-system-vite-example

Espero que esse artigo tenha sido útil para você em algum nível, e agradeço a todas as sugestões de melhoria!

DEV Community: Álvaro N.

Stop Using Context for State: Use an Event-Driven Pattern

The Architectural Pitfall Behind React

The Achilles Heel of React

Caution...

What If Components Didn’t Re-Render?

Event-Driven Example

Context/Provider Example

Why does this happen?

Event-Driven State: The Alternative

Building an Event-Driven Store From Scratch

PubSub Implementation:

useSubscribe Implementation:

usePublish Implementation:

Components used in the PubSub example

Provider with a PubSub instance:

Putting all the pieces together:

Context Based tree used in example

Final recap, trade-offs, and tips.

Advantages

Disadvantages

Tips

Thanks for reading!!!

How to Train a Model in TensorFlow.js on Massive Datasets (Out-of-Core Learning).

However... how much can the memory handle?

Kaboom!!!

Generators, Iterators and Lazy Evaluation

Whoa, powerful. But how do we use it in practice?

How to use Generators in TensorFlow.js

"But I need to process the data first!"

The Mandatory {xs, ys} Format

The Dataset Class Arsenal

Putting it all together (pipeline example):

But is that it, only advantages? (Some trade-offs of the approach)

Thanks for reading!!!

[Boost]

Creating a reusable Design System between React and React Native with Tamagui

Álvaro N. ・ Mar 27 '24

Creating a reusable Design System between React and React Native with Tamagui

TLDR;

🚀 Introduction

📦 Starting the project with Vite

⛓️ Integrating with Typescript

♟ Tree Shaking

💅 Setting up Storybook

🧪 Adding Vitest with React Testing Library

👾 Adding Tamagui

⚠️ Before we continue: Limitations regarding PNPM

Continuing...

👾🧪 Tamagui with Vitest

👾💅 Configuring with Storybook

🦋 Publishing with changesets

🧹 Cleaning up before publishing

Continuing...

Thank you for reading !!!!

Criando um Design System reutilizável entre React e React Native com Tamagui

TLDR;

🚀 Introdução

📦 Iniciando o projeto com vite

⛓️ Integrando com o Typescript

♟ Tree Shaking

💅 Configurando o Storybook

🧪 Adicionando Vitest com React Testing Library

👾 Adicionando Tamagui

⚠️ Antes de continuarmos: Limitações em relação ao PNPM

Continuando...

👾🧪 Tamagui com Vitest

👾💅 Configurando com Storybook

🦋 Publicando com changesets

🧹 Fazendo uma limpeza antes da publicação

Continuando...

Obrigado por ler !!!!

`PubSub` Implementation:

`useSubscribe` Implementation:

`usePublish` Implementation:

The Mandatory `{xs, ys}` Format