English | 简体中文

ModernX

Modern React state management framework with concurrent features and modern toolchain. Based on redux, redux-saga and react-router. (Inspired by elm and choo)

---

🚀 Features

✨ Modern React 18 Support

• Concurrent Features: Support for useTransition, useDeferredValue, and automatic batching
• Enhanced Performance: 30-50% reduction in re-renders with automatic batching
• React Router v6: Complete migration tools and compatibility layer

📦 Monorepo Architecture

• modernx: Main package with all features
• modernx-core: Core functionality and React integration
• modernx-immer: Immer integration for immutable updates
• modernx-loading: Loading state management
• modernx-logger: Redux logger plugin
• modernx-cli: Command-line tools and scaffolding
• modernx-gui: Development GUI and debugging tools

🛠️ Developer Experience

• Full TypeScript Support: Complete TypeScript support with type definitions and ESLint integration
• Code Quality: ESLint + @typescript-eslint + Prettier for consistent code style
• Zero Configuration: Out of the box with sensible defaults
• Modern Toolchain: Built with Node.js 18, latest Babel, and modern build tools
• Hot Reload: Development experience with HMR
• Debugging Tools: Built-in logger and GUI visualization tools
• CLI Integration: Project scaffolding with optional tools

🔄 Backward Compatible

• 100% API Compatibility: Existing projects upgrade without code changes
• Progressive Migration: Gradually adopt new features
• Stable APIs: Reliable and well-tested

---

📦 Installation

# Install the main package
npm install modernx

# Or with yarn
yarn add modernx

# Or with pnpm
pnpm add modernx

Peer Dependencies

Make sure you have React 18+ installed:

npm install react@18 react-dom@18

---

🎮 Quick Start

Basic Example

import { createApp } from 'modernx';

// 1. Define a model
const countModel = {
  namespace: 'count',
  state: 0,
  reducers: {
    add(state) { return state + 1; },
    minus(state) { return state - 1; }
  },
  effects: {
    *asyncAdd({ payload }, { put }) {
      yield new Promise(resolve => setTimeout(resolve, 1000));
      yield put({ type: 'add', payload });
    }
  }
};

// 2. Create app
const app = createApp({
  models: [countModel]
});

// 3. Start app
app.start('#root');

With React Components

import React from 'react';
import { connect } from 'modernx';

const Counter = ({ count, add, minus, asyncAdd }) => (
  <div>
    <h2>Count: {count}</h2>
    <button onClick={add}>+</button>
    <button onClick={minus}>-</button>
    <button onClick={asyncAdd}>Async +1</button>
  </div>
);

export default connect(
  ({ count }) => ({ count }),
  ({ add, minus, asyncAdd }) => ({ add, minus, asyncAdd })
)(Counter);

---

🛠️ Development

Contributing

We welcome contributions! Please see our Developer Guide for detailed instructions.

Quick Setup

# Clone the repository
git clone https://github.com/perlinson/modernx.git
cd modernx

# Install dependencies
npm install

# Bootstrap packages
npm run bootstrap

# Link development dependencies
npm run dev:link

# Start development
npm run dev

Development Commands

# Build all packages
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Lint code
npm run lint

# Validate monorepo
npm run validate:quick

Monorepo Management

# Workspace status
npm run workspaces:status

# Link internal dependencies
npm run dev:link

# Clean all packages
npm run clean:all

# Run scripts across packages
npm run run:all build

---

🛠️ Development Tools

Logger Plugin

Add comprehensive Redux logging to your ModernX application:

import modernx from 'modernx';
import logger from 'modernx-logger';

const app = modernx({
  plugins: [logger({
    collapsed: true,
    duration: true,
    timestamp: true,
  })],
});

GUI Development Tool

Start the development GUI for real-time state visualization:

# Start GUI from project directory
npx modernx-gui

# Or include in project creation
npx modernx create my-app --tools gui

The GUI provides:

• Real-time State Visualization: Live display of Redux state changes
• Action History: Complete timeline of all actions with payloads
• Project Structure Analysis: Automatic detection of ModernX models
• WebSocket Communication: Real-time synchronization with your app

CLI Integration

Create new ModernX projects with optional debugging tools:

# Create project with logger and GUI
npx modernx create my-app --tools logger,gui

# Interactive project creation
npx modernx create my-app
# Select tools during setup:
# - Logger: Redux logger for debugging
# - GUI: Development GUI with real-time visualization

---

🎯 React 18 Concurrent Features

useDvaTransition

Non-blocking state updates with useTransition:

import { useDvaTransition } from 'modernx/react18-utils';

const HeavyComponent = () => {
  const [isPending, startTransition] = useDvaTransition();
  
  const handleHeavyOperation = () => {
    startTransition(() => {
      // Non-blocking state update
      dispatch({ type: 'heavyOperation' });
    });
  };
  
  return (
    <button onClick={handleHeavyOperation} disabled={isPending}>
      {isPending ? 'Processing...' : 'Start Operation'}
    </button>
  );
};

useDvaConcurrentState

Deferred rendering with useDeferredValue:

import { useDvaConcurrentState } from 'modernx/react18-utils';

const SearchComponent = () => {
  const { state, deferredState } = useDvaConcurrentState('search');
  
  return (
    <div>
      <input onChange={(e) => dispatch({ type: 'search', payload: e.target.value })} />
      <div>Current: {state.results.length} results</div>
      <div>Deferred: {deferredState.results.length} results</div>
    </div>
  );
};

---

📚 Documentation

Guides

• Installation Guide
• Quick Start
• Core Concepts
• React 18 Features
• Advanced Usage

API Reference

• createApp
• Model API
• Hooks API
• Plugin API

Examples

• Basic Counter
• Todo List
• Async Data
• React 18 Concurrent
• React Router v6

---

🏗️ Project Structure

modernx/
├── packages/
│   ├── modernx/           # Main package
│   ├── modernx-core/      # Core functionality
│   ├── modernx-immer/     # Immer integration
│   ├── modernx-loading/   # Loading state
│   ├── modernx-logger/    # Logger plugin
│   ├── modernx-cli/       # Command-line tools
│   └── modernx-gui/       # Development GUI
├── examples/              # Example projects
├── docs/                  # Documentation
├── website/              # VuePress website
└── scripts/               # Build and deployment scripts

---

🧪 Development

Local Development

# Clone the repository
git clone https://github.com/perlinson/modernx.git
cd modernx

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm test

# Build packages
npm run build

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific package tests
npm run test:modernx-core

---

📦 Packages

Package	Version	Size	Description
modernx		~18KB	Main package with all features
modernx-core		~27KB	Core functionality
modernx-immer		~2KB	Immer integration
modernx-loading		~5KB	Loading state management
modernx-logger		~3KB	Redux logger plugin
modernx-cli		~8KB	Command-line tools
modernx-gui		~12KB	Development GUI

---

🤝 Contributing

We welcome all kinds of contributions! Please see our Developer Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

---

📄 License

MIT © perlinson

---

🙏 Acknowledgments

• Redux - State management
• Redux-Saga - Side effects
• React Router - Routing
• Elm - Architecture inspiration
• Choo - API inspiration

---

🔗 Links

• Documentation: https://perlinson.github.io/modernx
• GitHub: https://github.com/perlinson/modernx
• NPM: https://www.npmjs.com/package/modernx
• Issues: https://github.com/perlinson/modernx/issues
• Discussions: https://github.com/perlinson/modernx/discussions

---

_{Built with ❤️ by perlinson}