React with Styles CSS Interface

Common errors

• ThemedStyleSheet.registerInterface is not a function

  cause `ThemedStyleSheet` was not imported correctly or `react-with-styles` is not installed/incorrectly configured.
  fix Ensure `import ThemedStyleSheet from 'react-with-styles/lib/ThemedStyleSheet';` is used and `react-with-styles` is installed (peer dependency). Check the `react-with-styles` documentation for proper setup.

• Styles are not applying or are being overridden unexpectedly.

  cause Class name collisions due to non-unique style names or improper handling of specificity.
  fix Review all style definitions for duplicate class names. Utilize `registerCSSInterfaceNamespace('YourAppName')` to prefix all generated class names. Avoid attempting to override the internal specificity selectors and stick to overriding via the original class names. Use browser developer tools to inspect the generated class names and their applied styles to identify conflicts.

• Module not found: Can't resolve 'react-with-styles-interface-css'

  cause The package is not installed or the import path is incorrect.
  fix Run `npm install react-with-styles-interface-css` or `yarn add react-with-styles-interface-css`. Verify the import statement `import CSSInterface from 'react-with-styles-interface-css';`.

Warnings

• gotcha Class name collisions can occur if styles across your project are not given unique names, leading to unintended style overrides. The generated static CSS relies on these names being distinct.
  Fix: Ensure all class names defined in your `react-with-styles` style objects are globally unique, or utilize the `registerCSSInterfaceNamespace` function to prefix them, minimizing collision risk.
• gotcha The CSS output by this interface uses specifiers with varying levels of specificity to maintain compatibility with `aphrodite`'s style resolution logic. Directly overriding these generated specifiers can lead to unpredictable behavior and should be avoided.
  Fix: Instead of targeting the internal, highly specific selectors, override styles using the original class names defined in your `react-with-styles` definitions, potentially combined with the registered namespace prefix.
• breaking The `react-with-styles` ecosystem, including this interface, is considered to be in maintenance by Airbnb, with its last major `react-with-styles` update in 2021. While stable, this implies less active development and potential for slower adoption of new React features or changes in the broader CSS-in-JS landscape.
  Fix: Be aware of the project's maintenance status. For new projects, evaluate more actively developed CSS-in-JS solutions or build-time styling libraries that are aligned with current React practices like React Server Components.
• gotcha Actual CSS file generation requires the separate `react-with-styles-interface-css-compiler` package. Forgetting to integrate this compiler into your build pipeline will result in no CSS output despite defining styles correctly in your components.
  Fix: Install `react-with-styles-interface-css-compiler` and configure your build process (e.g., via `npm scripts` or a custom build step) to run its CLI or programmatic API. Ensure the compiler points to your application's entry point.

Install

• npm install react-with-styles-interface-css npm
• yarn add react-with-styles-interface-css yarn
• pnpm add react-with-styles-interface-css pnpm

Imports

• CSSInterface
  wrong:

  import { CSSInterface } from 'react-with-styles-interface-css'; // Not a named export
  const CSSInterface = require('react-with-styles-interface-css'); // CommonJS is deprecated for modern React libs

  correct:

  import CSSInterface from 'react-with-styles-interface-css';

  `CSSInterface` is the default export of this package. Ensure `react-with-styles/lib/ThemedStyleSheet` is also imported and `registerInterface` is called.
• registerCSSInterfaceNamespace
  wrong:

  import registerCSSInterfaceNamespace from 'react-with-styles-interface-css'; // Not a default export

  correct:

  import { registerCSSInterfaceNamespace } from 'react-with-styles-interface-css';

  Used to prefix all generated class names for better organization and to prevent collisions in larger applications. This is a named export.
• ThemedStyleSheet
  wrong:

  import { ThemedStyleSheet } from 'react-with-styles'; // Incorrect path, ThemedStyleSheet is not a root export

  correct:

  import ThemedStyleSheet from 'react-with-styles/lib/ThemedStyleSheet';

  Required from the core `react-with-styles` library to register this CSS interface. This path `react-with-styles/lib/ThemedStyleSheet` is specific and crucial for correct setup.

Quickstart

This quickstart demonstrates how to register the `CSSInterface` with `react-with-styles`, optionally namespace class names, and then apply styles to a React component using `withStyles` and `css` functions.

import ThemedStyleSheet from 'react-with-styles/lib/ThemedStyleSheet';
import CSSInterface, { registerCSSInterfaceNamespace } from 'react-with-styles-interface-css';
import { withStyles, css } from 'react-with-styles';

// 1. Register the CSS interface with react-with-styles
ThemedStyleSheet.registerInterface(CSSInterface);

// 2. Optional: Register a namespace to prefix generated class names
const namespace = 'MyAwesomeApp';
registerCSSInterfaceNamespace(namespace);

// 3. Define your styles using the withStyles HOC
const MyStyledComponent = withStyles(({ color, unit }) => ({
  container: {
    backgroundColor: color.primary,
    padding: 2 * unit,
    borderRadius: unit,
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: {
    color: color.white,
    fontSize: 3 * unit,
    fontWeight: 'bold',
  },
}))(({ styles, css, message = "Hello, CSS Interface!" }) => (
  <div {...css(styles.container)}>
    <span {...css(styles.text)}>{message}</span>
  </div>
));

// Example usage (this part would typically be in your app's component tree)
// This example is for demonstration; a full app would also need a ThemeProvider
// (from react-with-styles) to provide `color` and `unit`.
// console.log(<MyStyledComponent />);