CCState Babel Plugin

5.2.3 verified Sat Apr 25 auth: no javascript

A Babel preset for CCState v5.2.3 that provides Hot Module Reload support and automatic debug label injection for atoms. It adds a global cacheMap to make each atom a singleton under HMR, and automatically generates debug information for easier troubleshooting. The preset is configurable via options like projectRoot and customAtomNames (default: ['state', 'computed', 'command']). Designed as a build-time tool, it integrates seamlessly with Vite and other Babel-based setups. Differentiators include first-class HMR support and auto-labeling, inspired by Jotai's devtools.

Common errors

error Error: Cannot find module 'ccstate-babel/preset' ↓

cause Missing or incorrectly placed package installation, or wrong babel config path.

fix

Ensure ccstate-babel is installed as a dev dependency and use the correct preset path: 'ccstate-babel/preset'.

error TypeError: ccstate_babel.preset is not a function ↓

cause Using default import instead of named import in JavaScript babel config.

fix

Use require('ccstate-babel').preset or import { preset } from 'ccstate-babel'.

error Error: Options must be an object or undefined ↓

cause Passing options incorrectly in babel config (e.g., string instead of object).

fix

Ensure second argument is an object: ['ccstate-babel/preset', { projectRoot: __dirname }]

Warnings

breaking Version 5.x requires CCState 5.x; incompatible with older atom signatures. ↓

fix Upgrade CCState to 5.x and ensure atom definitions use the new API (e.g., state() instead of atom()).

deprecated Support for Node <12 has been dropped since v4.0.0. ↓

fix Use Node 12+.

gotcha The preset alters atom behavior for HMR; if HMR is not used, still adds overhead due to global cacheMap. ↓

fix Disable preset in production build or configure to skip HMR logic (not directly supported; consider forking).

Install

npm install ccstate-babel

yarn add ccstate-babel

pnpm add ccstate-babel

Imports

default (preset)
wrong
```
import ccstateBabel from 'ccstate-babel'
```
correct
```
import { preset } from 'ccstate-babel'
```
The preset is exported as a named export 'preset' from the main entry. Default export is not available.
preset (via paths)
wrong
```
"presets": ["ccstate-babel"]
```
correct
```
// babel.config.json
"presets": ["ccstate-babel/preset"]
```
Use the full path 'ccstate-babel/preset' in babel config, not just the package name.

usePreset in Vite

wrong

plugins: [react({ babel: { presets: ['ccstate-babel'] } })]

correct

const react = require('@vitejs/plugin-react');
...
plugins: [react({ babel: { presets: ['ccstate-babel/preset'] } })]

Ensure the preset path is 'ccstate-babel/preset' within the babel object, not the outer level.

Quickstart

Shows how to configure the Babel preset in both babel.config.json and Vite setup, including custom atom names.

// Install
// npm install --save-dev ccstate-babel @babel/core

// babel.config.json
{
  "presets": [
    ["ccstate-babel/preset", {
      "projectRoot": __dirname,
      "customAtomNames": ["state", "computed", "command", "$action"]
    }]
  ]
}

// Then use in a Vite project (vite.config.ts)
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react({
      babel: {
        presets: [
          ['ccstate-babel/preset', { projectRoot: __dirname }]
        ]
      }
    })
  ]
});

// After configuration, atom calls like state(0) will be transformed for HMR and debug labels.