React-JSS

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause `createUseStyles` is a React Hook and must be called within a functional component or another custom hook, not in a class component or outside React's render phase.
  fix Ensure `createUseStyles` is called directly inside a functional component's body or within a custom hook that respects React's Rules of Hooks.

• TypeError: Cannot read properties of undefined (reading 'theme')

  cause Attempting to access `theme` properties within a style definition or component without a `ThemeProvider` being present higher up in the component tree.
  fix Wrap your component tree (or the relevant section) with `<ThemeProvider theme={yourThemeObject}>` to provide the theme context.

• Module not found: Can't resolve 'react-jss'

  cause The `react-jss` package is not installed or the import path is incorrect.
  fix Run `npm install react-jss` or `yarn add react-jss` to install the package. Verify the import statement is `import { ... } from 'react-jss';`.

Warnings

• breaking The `react-jss` project is officially no longer maintained. No new features, bug fixes, or compatibility updates for future React versions are expected. Users should consider migrating to alternative styling solutions.
  Fix: Evaluate migration to actively maintained CSS-in-JS libraries such as Emotion, Styled Components, or native CSS Modules, depending on project requirements and preferred styling paradigm.
• gotcha There were several bug fixes and reverts related to React 18 compatibility, specifically concerning `useInsertionEffect`. While patched in v10.9.2, ensure thorough testing when using `react-jss` with React 18 or newer, as future React updates may reintroduce issues due to lack of maintenance.
  Fix: Ensure you are on `react-jss@10.9.2` or later for React 18 compatibility fixes related to `useInsertionEffect`. Be aware of the project's abandoned status for future React versions.
• gotcha Memory leaks were reported and addressed in specific JSS plugins (e.g., `jss-plugin-global`, `jss-plugin-nested`, `jss-plugin-rule-value-function`) with subsequent reverts in some cases. This indicates potential instability around memory management in complex styling scenarios.
  Fix: Upgrade to `react-jss@10.9.2` or later to include the most stable fixes for these memory leaks. For critical applications, monitor memory usage carefully, especially with highly dynamic or frequently updated styles.

Install

• npm install react-jss npm
• yarn add react-jss yarn
• pnpm add react-jss pnpm

Imports

• createUseStyles
  wrong:

  const useStyles = require('react-jss').createUseStyles;

  correct:

  import { createUseStyles } from 'react-jss';

  This hook is the primary way to define and use styles in functional React components. CommonJS `require` syntax is not idiomatic for modern React applications and can lead to issues with tree-shaking and module resolution.
• ThemeProvider
  wrong:

  import ThemeProvider from 'react-jss/lib/ThemeProvider';

  correct:

  import { ThemeProvider } from 'react-jss';

  Used to provide a theme object down the React tree via context. Direct deep imports from `lib/` are discouraged as they are internal and subject to change.
• JssProvider

  import { JssProvider } from 'react-jss';

  Provides a custom JSS instance, SheetsRegistry, or other JSS-specific configurations, particularly useful for Server-Side Rendering (SSR) or advanced setups.

Quickstart

This example demonstrates how to set up `react-jss` with a `ThemeProvider` to provide global theme values and use `createUseStyles` for component-scoped styling, including dynamic values based on the theme.

import React from 'react';
import { createUseStyles, ThemeProvider } from 'react-jss';

interface Theme {
  primary: string;
  secondary: string;
  fontSize: number;
}

const theme: Theme = {
  primary: '#007bff',
  secondary: '#6c757d',
  fontSize: 16,
};

const useStyles = createUseStyles<keyof Theme> ({
  button: {
    backgroundColor: ({ primary }) => primary,
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    fontSize: ({ fontSize }) => `${fontSize}px`,
    cursor: 'pointer',
    '&:hover': {
      opacity: 0.9,
    },
  },
  secondaryButton: {
    backgroundColor: ({ secondary }) => secondary,
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    fontSize: ({ fontSize }) => `${fontSize}px`,
    cursor: 'pointer',
    marginLeft: '10px',
    '&:hover': {
      opacity: 0.9,
    },
  },
});

function MyButton() {
  const classes = useStyles(theme); // styles can receive props or use the theme from context
  return (
    <div>
      <button className={classes.button}>Primary Button</button>
      <button className={classes.secondaryButton}>Secondary Button</button>
    </div>
  );
}

function App() {
  return (
    <ThemeProvider theme={theme}>
      <MyButton />
    </ThemeProvider>
  );
}

export default App;