babel-plugin-mobx-observer-on-every-react-component

What does this Babel plugin do?

This plugin will wrap literally every React component in a MobX observer higher order component.

Why would you want to do this?

When using MobX, MobX-State-Tree, or any other library in the MobX ecosystem, you may find yourself in one of two scenarios:

1. You sometimes waste a lot of time debugging why a component isn't updating even though you think it should, only to realize that you forgot to wrap a component in an observer.
2. You just really dislike the way it looks to import observer from mobx-react or @observer from mobx-react-lite in every single file and wrap your components. This is something that seems to come up again and again.

The typical recommendation from MobX is to just use the @observer decorator or the observer HOC and accept that you'll have to import it and use it in every file. This plugin doesn't actually change that requirement, it just makes it so that you don't have to manually do that. You may find value in this plugin if you either hate having to remember that, or if you just don't like the way it looks.

What are the downsides of using this plugin?

1. This plugin is currently in early development, so there will probably be bugs. As more people try and adopt it, we will clean up whatever doesn't work. If we get enough adoption and stability, we will mark this library as v1 and remove this bullet point. But for now, use at your own risk!
2. If you're not already using Babel, you'll have to add it to your tool chain.
3. It will make your Babel build take a little longer, although we can improve that over time with performance enhancements.
4. You may pick up some convenience, but it also adds a little magic to your project. You or your coworkers may sort of "forget" about the observer HOC and not realize that it's not actually being applied. That could lead to hard-to-debug issues in your own codebase, or just a general degradation of your own mental model of how your code works.

Are there any runtime performance concerns?

Not that we have evidence for. The MobX docs specifically recommend wrapping every component in an observer, saying:

observer only enhances the component you are decorating, not the components called by it. So usually all your components should be wrapped by observer. Don't worry, this is not inefficient. On the contrary, more observer components make rendering more efficient as updates become more fine-grained.

We don't actually have benchmarks to share, so it's always possible there's some small cost, but it's likely to be negligible. If you disagree, send us some benchmarks and we'll update this section!

Install

# npm
npm install --save-dev babel-plugin-mobx-observer-on-every-react-component
# yarn
yarn add --dev babel-plugin-mobx-observer-on-every-react-component
# pnpm
pnpm add --dev babel-plugin-mobx-observer-on-every-react-component
# bun
bun add --dev babel-plugin-mobx-observer-on-every-react-component

Usage

Add the plugin to your .babelrc file:

{
  "plugins": [
    ["babel-plugin-mobx-observer-on-every-react-component"]
  ]
}

If you prefer using a JavaScript configuration file, you can add the plugin to your babel.config.js:

module.exports = function(api) {
  api.cache(true);

  return {
    plugins: [
      'babel-plugin-mobx-observer-on-every-react-component'
    ]
  };
};

Options

You can pass an optional object to the plugin to configure the behavior of the plugin. Options look like this:

/**
 * Options for the plugin
 */
interface PluginOptions {
  // Default false, controls if we log debug statements during plugin execution. Mostly intended for plugin developers.
  debugEnabled?: boolean; 
}

More options on the way

Here are some options we'll eventually add:

1. Array of files to ignore
2. Some kind of pattern matching to ignore certain files
3. Allow transformation of node_modules (right now we have it hardcoded to skip node_modules)
4. We are open to suggestions! Please open an issue or discussion if you have ideas.

Ignore files/lines

If you want to ignore an entire file, add a comment to the top of the file:

// @auto-observer-ignore-file

If you want to ignore a specific block, add a comment to the start of the block:

// @auto-observer-ignore-block

Examples

Local Example with Vite

cd example
bun install
bun dev

Then check out the Vite app that starts. It'll look something like this:

https://github.com/user-attachments/assets/1e1dc69e-defe-4387-82c9-c91ab0a5c887

Babel REPL

You can see the plugin in action with different starting points using the Babel REPL. This is also a great way to provide us with reproducible examples for bug reports.

Contributing

We'd love to have any help. Please open an issue or discussion if you want to get started.

Resources for Babel Plugin development

Here are some resources we've used to learn how to develop Babel plugins:

1. Babel Plugin Handbook
2. Build your own Babel plugin

Development environment

We use Bun for package management, running tests, and building the project (sort of - we are actually using tsc under the hood with Bun as a task runner for this).

1. Clone the repo
2. Make sure you have the most recent version of Bun installed (check their website for instructions)
3. Install dependencies with bun install
4. Make sure tests are passing with bun test
5. Hop into the example folder and also install dependencies with cd example && bun install
6. Once in the example folder, you can run bun dev to start the dev server and see a Vite app that points to a local build of this package.
7. To update the build of this package that the example is pointing to, run bun run build in the root of the project and restart the dev server in the example folder.
8. To build your changes, run bun run build in the root of the project.