bem-react

Dependency Injection in this library allows you to decouple React components into different versions (e.g., desktop vs mobile, or experimental vs common) and switch between them easily.

The Core Workflow:

1. Define a Registry ID: Use a unique identifier (often via @bem-react/classname) to represent a specific dependency context.
2. Create a Registry: Instantiate a Registry with that ID.
3. Register Components: Use .set() or .fill() to map descriptive keys to specific component implementations.
4. Inject the Registry: Wrap your common component with withRegistry(registry)(Component) to create a versioned instance.
5. Consume Dependencies: Inside your components, use useRegistry(id) or the RegistryConsumer component to access the registered dependencies instead of importing them directly.

// 1. Define ID
export const registryId = cn('App')

// 2. Create Registry & 3. Register
const registry = new Registry({ id: registryId })
registry.set('Header', HeaderDesktop)

// 4. Inject
export const AppDesktop = withRegistry(registry)(AppCommon)

// 5. Consume
const { Header } = useRegistry(registryId)

The @bem-react/core package allows you to organize components using BEM (Block Element Modifier) methodology. It works by defining a base component (the "Presenter") and then composing various modifier variants onto it using withBemMod and compose functions.

Core Workflow

1. Define Props: Extend IClassNameProps from @bem-react/core in your component's interface.
2. Create Base Component: Use cn from @bem-react/classname to create a class name generator for your block.
3. Define Modifiers: Use withBemMod to create variants that trigger based on specific prop values.
4. Compose: Use compose to merge the base component with all desired modifiers.

Composition Order

The order of components passed to compose is critical. The FIRST modifier inside the compose method will be the one rendered if multiple modifiers attempt to change the same underlying structure (e.g., changing a button tag to an a tag).

import { compose, withBemMod } from '@bem-react/core';

// The first modifier in the list takes precedence for structural changes
const Button = compose(
  withButtonThemeAction,
  withButtonTypeLink,
)(ButtonPresenter);

While React is the industry standard, bem-react-core addresses specific architectural limitations in common web development tasks. Standard React patterns often lead to suboptimal solutions in the following areas:

• Decomposition: React components often rely on imperative if or switch statements to handle variations, making them hard to grasp and modify. Most logic resides in the render() method, making it difficult to override functionality without rewriting the method.
• Code Reuse: React typically uses Higher-Order Components (HOCs) or inheritance for reuse. Inheritance struggles with combining orthogonal features without complex hierarchies, and HOCs can add complexity.
• Cross-platform Development: Teams often choose between building separate versions for each platform (high maintenance/sync cost) or a single responsive version (increased code complexity and potential performance degradation on mobile).
• Experiments (A/B Testing): Codebase branching is expensive to maintain and sync, while targeted conditionals within a single codebase increase complexity, hurt performance, and leave "dead code" after experiments end.
• Sharing Component Libraries: Modifying shared libraries via forking, inheritance, or runtime patching is often difficult or incomplete (e.g., an inherited component might not be used by other library components that compose it).

bem-react-core provides more efficient alternatives through redefinition levels and declarative block modification.

For better code splitting, you can use React.lazy inside a withBemMod wrapper to load heavy modifier-specific logic or styles only when the modifier is active.

Note: If using Server-Side Rendering (SSR), replace React.lazy with @loadable/components or react-loadable.

Implementation Pattern

1. Create an async component file with a default export.
2. In your modifier file, use withBemMod and wrap the component in Suspense with a lazy import.

// Inside your modifier file
export const withMod = withBemMod<BlockModProps>(cnBlock(), { mod: true }, (Block) => (props) => {
  const DynamicPart = lazy(() => import('./Block_mod.async.tsx'))

  return (
    <Suspense fallback={<div>Updating...</div>}>
      <Block {...props}>
        <DynamicPart />
      </Block>
    </Suspense>
  )
})

import React, { Suspense, lazy } from 'react'
import { cnBlock } from '../Block'

export interface BlockModProps {
  mod?: boolean
}

export const withMod = withBemMod<BlockModProps>(cnBlock(), { mod: true }, (Block) => (props) => {
  const DynamicPart = lazy(() => import('./Block_mod.async.tsx'))

  return (
    <Suspense fallback={<div>Updating...</div>}>
      <Block {...props}>
        <DynamicPart />
      </Block>
    </Suspense>
  )
})