Cerebellum

Cerebrum's React Component Library

For information about how to use Cerebellum in your application, please see the Storybook documentation.

Mantine Integration

Cerebellum exports Mantine-based helpers (showToast, showBar, showDialog, openConfirmModal, MantineModal, createCustomMantineTheme) as optional utilities. To use them, Mantine must be installed as a peer dependency in the consuming app.

1. Install Mantine

npm install @mantine/core @mantine/notifications @mantine/modals

2. Import CSS

Mantine uses CSS variables and CSS Modules. Add the following imports before any other styles in your app entry point (e.g. _app.tsx or layout.tsx):

// Mantine base styles (required)
import "@mantine/core/styles.css";
import "@mantine/notifications/styles.css";
import "@mantine/modals/styles.css";

// Cerebellum's Mantine CSS module styles (required for correct styling)
import "@cerebruminc/cerebellum/lib/esm/mantine.css";

3. Wrap your app with MantineProvider

import { MantineProvider } from "@mantine/core";
import { Notifications } from "@mantine/notifications";
import { ModalsProvider } from "@mantine/modals";
import { createCustomMantineTheme } from "@cerebruminc/cerebellum";

const theme = createCustomMantineTheme();

export default function App({ children }) {
  return (
    <MantineProvider theme={theme}>
      <ModalsProvider>
        <Notifications />
        {children}
      </ModalsProvider>
    </MantineProvider>
  );
}

Local Development

You can run Storybook locally with

npm start

Testing changes locally via yalc (the simplest)

Testing local builds with yalc

Once the component is working well in Storybook, you'll want to make sure it works as expected in your project. You can do this with yalc publish:

first make sure you have yalc installed in your machine

npm install -g yalc

Follow the next steps:

1. Create a build of your changes:

npm run build

2. publish the changes to your local repository that yalc creates, it grabs only files that should be published to NPM and puts them in a special global store.

yalc publish

3. In your project repository run:

yalc add @cerebruminc/cerebellum
npm install

You'll need to do this whenever you want to connect to your local Cerebellum build. Make sure to restart your local server.

When you're done, you can revert your changes inside your package.json file and wait until the new version is available in the npm repository:

NOTE: There is a huge gotcha here. revert the changes inside package.json will require you to run again npm ci or npm i to reinstall the original package

Working with npm link (another way to work locally with cerebellum)

If you want to work with npm link, In the Cerebellum directory, run:

npm link

In the consuming app, run:

npm link @cerebruminc/cerebellum

You'll need to do this whenever you want to connect to your local Cerebellum build. Make sure to restart your local server.

Make sure to build Cerebellum to access your changes. You'll need to do this anytime you make changes.

npm run build

When you're done, unlink the local Cerebellum version:

npm unlink @cerebruminc/cerebellum

NOTE: If you prefer to work with npm link, sometimes you will need to deal with nasty constraints and problems with dependency resolution, symlink interoperability between file systems, etc. We recommend work with yacl

NOTE: There is a huge gotcha here. Running npm unlink @cerebruminc/cerebellum will uninstall Cerebellum, so you will need to re-install it before running your app again.

Linking with Next.js

To work with Next.js, you will need to alias react, react-dom, and styled-components to prevent conflicting versions:

// next.config.js
const nextConfig = {
  webpack: (config, options) => {
    config.resolve.alias = {
      ...(config.resolve.alias || {}),
      react: path.resolve(__dirname, "node_modules/react"),
      "react-dom": path.resolve(__dirname, "node_modules/react-dom"),
      "styled-components": path.resolve(__dirname, "node_modules/styled-components"),
    };
    return config;
  },
  // Remaining config
}

Troubleshooting npm link

• Make sure the link is working. You can check it like this:

# run
ls -l node_modules/@cerebruminc 

# Linked to local build
total 0
lrwxr-xr-x@ 1 davebascom  staff  19 May 13 12:11 cerebellum -> ../../../cerebellum

# Using node_modules (not linked)
total 0
drwxr-xr-x  7 davebascom  staff  224 May 13 12:06 cerebellum

• Make sure you are not re-installing node_modules when you restart your server. This unlinks any symlinks.

# Do not run this - it will re-install node_modules and unlink Cerebellum
npm run go

# Start the server directly
npm run dev:https

• You may need to clear out node_modules in both Cerebellum and the consuming app.

• If you get a compile error after unlinking, make sure Cerebellum is installed. When you run npm unlink @cerebruminc/cerebellum, it will uninstall the package.

Testing the production build

Whenever you open a pull request, a production build is created and uploaded to the @cerebruminc/cerebellum npm package. The name of this beta package is added as a comment to he pull request, allowing you to test it in your own project:

Install this version in your package.json. Just make sure to omit the caret: | Stable | Experimental | | --- | --- | | "@cerebruminc/cerebellum": "v15.14.0", | "@cerebruminc/cerebellum": "15.14.0-beta.dangerous.c472cfa", |

Codemods

There are some codemods written in jscodeshift that you can run to update your existing Cerebellum integration. More information can be found in the codemods readme.