@hanamura/rcgen NPM

React Containers Static Generator

A tool for generating optimized React container components with static CSS from configuration files.

Overview

This tool generates responsive React container components based on a simple JSON configuration file. It produces code optimized for Server-Side Rendering with no layout flash issues.

Generated files include: 1. React component files (.tsx) 2. CSS Module files (.module.css) with media queries 3. TypeScript type definitions 4. Core utility files

Benefits

SSR Compatible: No more layout flash issues with server-side rendering
Performance: Static CSS is more performant than runtime matchMedia evaluations
CSS Variables Based: Uses CSS variables and media queries instead of JavaScript
Type Safety: Strong TypeScript typings for all components and options
Zero Runtime Overhead: All responsive behavior happens entirely in CSS
Framework Agnostic: Works with any React-based framework

Installation

# Install the generator (not yet published)
npm install @hanamura/rcgen

# Or clone this repository and build it locally
git clone https://github.com/hanamura/react-containers.git
cd react-containers/static-generator
npm install
npm run build

Usage

# Generate components based on your configuration
npx rcgen --config ./config.json --output ./src/generated

# Use the --force flag to overwrite existing files
npx rcgen --config ./config.json --output ./src/generated --force

# Use the --verbose flag for detailed output
npx rcgen --config ./config.json --verbose

Configuration Format

The configuration file uses a JSON format that defines your queries (breakpoints), spacing values, and container components to generate:

{
  "queries": [
    { "name": "vp_sm", "query": "(min-width: 0px)" },
    { "name": "vp_md", "query": "(min-width: 640px)" },
    { "name": "vp_lg", "query": "(min-width: 1024px)" }
  ],
  "spacing": [
    { "name": "sp_sm", "value": "var(--spacing-sm)" },
    { "name": "sp_md", "value": "var(--spacing-md)" },
    { "name": "sp_lg", "value": "var(--spacing-lg)" }
  ],
  "containers": ["Stack", "Tile", "Cluster", "Reel", "Switcher", "Panorama"],
  "variablePrefix": "rcg"
}

Configuration Properties

queries: Array of query objects with name and query (CSS media query) properties
spacing: Array of spacing objects with name and value (CSS value) properties
containers: Array of container component names to generate
variablePrefix (optional): Prefix for CSS variables to avoid naming collisions

Available Containers

The system includes these built-in container components:

Component	Description	CSS Implementation	Key Options
Stack	Vertical layout	Flexbox with column direction	gap, direction
Tile	Grid layout	CSS Grid with configurable columns	columns, gap
Cluster	Wrapped flex layout	Flexbox with wrap	gap, align, justify
Reel	Horizontal scroll	CSS scroll snap with overflow	gap, snap
Switcher	Content switching	CSS-based display switching	threshold, gap
Panorama	Full-width container	100vw width and negative margins	indent

Generated Output Structure

The generator creates the following directory structure:

output-dir/
├── core/
│   ├── index.ts   - Exports all utilities and types
│   ├── types.ts   - Type definitions
│   └── utils.ts   - Utility functions
└── components/
    ├── Stack.tsx
    ├── Stack.module.css
    ├── Tile.tsx
    ├── Tile.module.css
    └── ... other components

Using the Generated Components

import { Stack, Tile, spacing } from './generated';

function App() {
  return (
    <Stack 
      options={{ gap: spacing.sp_md }}
      adaptiveOptions={{
        vp_sm: { gap: spacing.sp_sm },
        vp_lg: { gap: spacing.sp_lg }
      }}
    >
      <Tile
        options={{ columns: 1 }}
        adaptiveOptions={{
          vp_md: { columns: 2 },
          vp_lg: { columns: 3 }
        }}
      >
        {/* Content */}
      </Tile>
    </Stack>
  )
}