React Style Bundler

Common errors

• ReferenceError: styled is not defined

  cause Attempting to use `styled` without correctly importing it, often by using CommonJS `require` syntax or incorrect named import.
  fix Ensure you are using `import { styled } from 'react-style-bundler';` at the top of your file.

• CSS bundle is empty or incomplete when calling getCSSBundle()

  cause The main React `App` component, or any component that defines `styled` components, was not imported or processed before `styled.getCSSBundle()` was invoked, meaning styles were never registered.
  fix Verify that your primary application component (e.g., `import { App } from './path/to/App';`) is imported and processed by your build system *before* `let bundle = styled.getCSSBundle();` is called.

• React hydration error: Text content did not match. Server: "..." Client: "..." (related to styling)

  cause A mismatch in the order or set of styles applied between the server and client builds, leading to different class names or rendered styles. This often happens due to inconsistent component import orders or conditional style loading between environments.
  fix Carefully review your build setup to ensure that the order in which styled components are imported and processed is identical on both the server and client. Ensure no styles are loaded conditionally or at different points in the import graph for either environment.

Warnings

• gotcha The library explicitly states it 'lacks functionality to bundle' for pure client-side usage and 'works best with Server Side Rendering'. Using it solely for client-side rendering might lead to unexpected behavior or require manual workarounds.
  Fix: Focus usage on Server-Side Rendering (SSR) environments where its strengths lie, or consider alternatives for purely client-side style bundling.
• breaking Styles added to the client-side bundle (e.g., via conditional imports or separate entry points) that are 'higher' in the import graph than the shared main App component will not be included in the server-generated CSS bundle. This results in missing styles during SSR and potential visual inconsistencies.
  Fix: Ensure all styles intended for SSR are imported via components that are part of the shared `App` component's import graph, so they are processed uniformly on both client and server.
• breaking Adding extra styles to the server-side rendering process 'higher' in the import graph than the shared App component can cause class name mismatching and React hydration errors, as the client and server generate different style outputs.
  Fix: Maintain a consistent import order and style registration path for all styled components across both your client and server bundles, ensuring the `App` component acts as a single, consistent entry point for style discovery.
• gotcha The README indicates that the library's CSS preprocessing capabilities might be basic, explicitly inviting contributions for improvements. This suggests that advanced CSS features might not be fully supported out-of-the-box compared to more mature CSS-in-JS solutions.
  Fix: Be aware of potential limitations with complex CSS preprocessing. Consider contributing or using a separate preprocessor if specific advanced features are critical.

Install

• npm install react-style-bundler npm
• yarn add react-style-bundler yarn
• pnpm add react-style-bundler pnpm

Imports

• styled
  wrong:

  const { styled } = require('react-style-bundler');

  correct:

  import { styled } from 'react-style-bundler';

  The 'styled' function is the primary API for creating styled components.
• getCSSBundle
  wrong:

  import { getCSSBundle } from 'react-style-bundler';

  correct:

  import { styled } from 'react-style-bundler';
  // ... after component imports ...
  let bundle = styled.getCSSBundle();

  The getCSSBundle method is accessed via the default 'styled' instance, not as a direct export.
• StyleSheetManager
  wrong:

  import StyleSheetManager from 'react-style-bundler';

  correct:

  import { StyleSheetManager } from 'react-style-bundler';

  Used for advanced scenarios like custom sheet injection, though not shown in basic examples.

Quickstart

This quickstart demonstrates how to define a styled component, integrate it into a React application, and then extract the final CSS bundle using `styled.getCSSBundle()` after the application's components have been processed.

// Import the bundler instance and styled function
import { styled } from "react-style-bundler";

// Define a simple React App component that uses styled components
function MyStyledComponent() {
  return styled.div`
    background-color: #f0f0f0;
    padding: 20px;
    border-radius: 8px;
    font-family: sans-serif;

    h1 {
      color: #333;
      margin-bottom: 10px;
    }

    button {
      background-color: #007bff;
      color: white;
      border: none;
      padding: 10px 15px;
      border-radius: 5px;
      cursor: pointer;

      &:hover {
        background-color: #0056b3;
      }
    }
  `;
}

// Assume this is your main application component,
// importing it triggers the style registration.
// In a real app, this would be your root component, e.g., <App />
const App = () => {
  const StyledDiv = MyStyledComponent(); // Create instance of styled component
  return (
    <StyledDiv>
      <h1>Hello from React Style Bundler!</h1>
      <button>Click Me</button>
    </StyledDiv>
  );
};

// Simulate rendering the app to ensure all styles are registered
// In a real SSR scenario, you'd render this to a string.
// For demonstration, just importing it is enough to register styles.
console.log("App component imported, styles are now registered.");
App(); // Calling it to ensure the styled components are processed

// After your application component has been processed,
// retrieve the bundled CSS as a string.
let cssBundle = styled.getCSSBundle();

// In a real build step, you would then save this string to a file,
// e.g., 'build/out.css'
console.log("\n--- Generated CSS Bundle ---");
console.log(cssBundle);
// Example of saving: await saveFile(cssBundle, "./build/out.css");