reatom-naming-plugin

A Babel & Vite plugin that automatically adds debug names to Reatom units, so you don't have to write them by hand.

const count = atom(0)               // →  atom(0, "count")
const doubled = computed(() => …)   // →  computed(…, "doubled")
const increment = action(() => …)   // →  action(…, "increment")

The name is taken from the variable or property the unit is assigned to. It works for atom, action, computed, reaction and every reatom* factory (reatomBoolean, reatomForm, …), but only for identifiers imported from a @reatom/* package.

Install

npm i -D reatom-naming-plugin

The plugin ships no runtime dependencies. @babel/core is an optional peer:

• The Babel entry needs nothing extra — your own Babel runs the plugin.
• The Vite entry needs @babel/core (loaded lazily). Most Vite + React setups already have it via @vitejs/plugin-react; otherwise add it: npm i -D @babel/core. It is build-time only and never enters your bundle.

Usage

Vite

// vite.config.ts
import { reatomNaming } from 'reatom-naming-plugin/vite'

export default {
  plugins: [reatomNaming()],
}

Babel

// babel.config.json
{ "plugins": ["reatom-naming-plugin/babel"] }

Options

All options are optional — the defaults work out of the box.

reatomNaming({
  naming: 'convention',
  factories: /^(reatom\w+|atom|action|reaction|computed)$/,
  importSources: [/^@reatom\//],
  domainVariable: 'name',
})

naming — how detailed the names are

Default: 'convention'.

• 'variable' — just the variable / property name.

  const count = atom(0)            // →  atom(0, "count")
  const form = { email: atom('') } // →  atom('', "email")

• 'convention' — adds context with dots, the same way @reatom/eslint-plugin does. A property gets its object's name as a prefix:

  const count = atom(0)            // →  atom(0, "count")
  const form = { email: atom('') } // →  atom('', "form.email")  ← note the prefix

factories — which functions get named

Default: /^(reatom\w+|atom|action|reaction|computed)$/ (covers atom, action, computed, reaction, and every reatom*).

Pass a RegExp or an explicit list to change it:

reatomNaming({ factories: ['atom', 'action'] }) // only these two

importSources — where those functions must come from

Default: [/^@reatom\//] — only names units imported from a @reatom/* package, so a same-named action() from another library is left alone.

reatomNaming({ importSources: ['my-state-lib'] }) // also treat this lib's exports
reatomNaming({ importSources: false })            // match by name only, ignore imports

domainVariable — the per-instance prefix in factories

Default: 'name'. Only relevant in 'convention' mode.

When you write your own reatom* factory that takes a name argument, the plugin builds a dynamic name from it, so every instance is distinguishable:

const reatomUser = (name) => {
  const age = atom(0)              // →  atom(0, `${name}.age`)
}
reatomUser('user1') // this instance's atom is "user1.age"
reatomUser('user2') // this one is "user2.age"

If your factories use a different parameter name (e.g. id), point the option at it:

reatomNaming({ domainVariable: 'id' }) // const reatomUser = (id) => atom(0, `${id}.age`)

Vite-only options

• apply — when the transform runs. 'all' (default), 'serve' (dev only, names stripped from the production build), or 'build' (prod only).
• include / exclude — which files to process. Defaults: /\.[cm]?[jt]sx?$/ and /node_modules/.

Notes

• Units that already pass a name are left untouched.
• The name is only appended as an argument — object initial state like atom({ name: 'John' }) is never modified.
• Naming follows the @reatom/eslint-plugin convention.

License

MIT