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>
  )
}

Roadmap

• Support for custom component templates
• Plugin system for extending with custom behaviors
• Visual editor for configuration
• Integration with popular frameworks (Next.js, Gatsby, etc.)
• Additional container component types

License

MIT