Cerebral
A declarative state and side effects management solution for popular JavaScript frameworks
Project Status
Cerebral 5.3 is the latest release, bringing modern API patterns and significant improvements:
- Supports full type safety in your application
- Updated integrations for the latest view libraries (React, Vue, etc.)
- Compatibility with modern lint, build and publish tools
- Updated documentation
- Bug fixes and performance improvements
The project is currently in maintenance mode. We accept PRs and Issues for bug fixes. While we're not actively developing new features, if you have a reasonable feature request, please create an issue. If we agree that the request adds value and it receives community support (indicated by thumbs up), we may consider implementing it.
Framework Support
Cerebral works seamlessly with all major frontend frameworks:
- React: Compatible with React 16.3 through React 19
- Vue: Full support for Vue 3, with backward compatibility for Vue 2.6+
- Preact: Works with Preact X (v10+) and older v8
- Inferno: Supports v4 through v9
- Angular: Compatible with Angular 14 through 19
Getting Started
Installation
# Using npm
npm install cerebral
# Using yarn
yarn add cerebral
# Using pnpm
pnpm add cerebral
Basic Example (React)
import React from 'react'
import { createApp } from 'cerebral'
import { Container, connect } from '@cerebral/react'
import { state, sequences } from 'cerebral'
// Create an action
const increment = ({ store, get }) => {
// Use 'store' to update state
store.set(state`count`, get(state`count`) + 1)
}
// Create app with state and sequences
const app = createApp({
state: {
count: 0
},
sequences: {
increment: [increment]
}
})
// Connect component to Cerebral
const Counter = connect(
{
count: state`count`,
increment: sequences`increment`
},
function Counter({ count, increment }) {
return (
<div>
<h1>Count: {count}</h1>
<button onClick={() => increment()}>Increment</button>
</div>
)
}
)
// Provide the app to your component tree
const App = () => (
<Container app={app}>
<Counter />
</Container>
)
For more detailed examples, check the documentation. If you prefer the proxy syntax (state.count
instead of state`count`
), see our proxy documentation.
Documentation
You can find the Cerebral documentation at cerebraljs.com.
Contribute
Cerebral is organized as a monorepo to make contributions easier:
- Clone the repo:
git clone https://github.com/cerebral/cerebral.git
- Install dependencies:
npm install
(from the root folder)
You don't need to run npm install
in each package directory - the monorepo setup handles this for you.
Testing
Run all tests from the root directory:
npm test
Or run tests for a specific package:
# Navigate to the package
cd packages/cerebral
# Run tests for just this package
npm test
Making Changes
-
Create a branch for your changes
-
Make your code changes and add tests
-
Commit from the root using our guided format:
npm run commit
-
Push your branch and create a pull request on GitHub
Using the monorepo for development
If you want to use your local Cerebral code in your own project, you can create symlinks to the packages:
# From your project root
ln -s ../../cerebral/packages/node_modules/cerebral/ node_modules/
ln -s ../../cerebral/packages/node_modules/@cerebral/ node_modules/
Remember to remove these links before installing from npm:
unlink node_modules/cerebral
unlink node_modules/@cerebral
Release process
- Review and merge PRs into
next
branch. It is safe to use "Update branch", the commit created by Github will not be part ofnext
history - From command line:
git switch next
git pull
npm install # make sure any new dependencies are installed
npm run release -- --dry-run --print-release # and check release notes
git switch master
git pull
git merge --ff-only next
git push