{"id":49791053,"url":"https://github.com/perlinson/modernx","last_synced_at":"2026-05-12T04:04:29.248Z","repository":{"id":333245449,"uuid":"1136668892","full_name":"perlinson/modernx","owner":"perlinson","description":"Modern React state management framework with concurrent features and modern toolchain","archived":false,"fork":false,"pushed_at":"2026-01-21T02:39:41.000Z","size":4888,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-05T12:13:52.026Z","etag":null,"topics":["cli","concurrent-rendering","devtools","framework","frontend","gui","library","logger","monorepo","react","react-hooks","react18","redux","state-management","typescript"],"latest_commit_sha":null,"homepage":"https://perlinson.github.io/modernx/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perlinson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-18T05:38:29.000Z","updated_at":"2026-01-24T04:30:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/perlinson/modernx","commit_stats":null,"previous_names":["perlinson/modernx"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/perlinson/modernx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlinson%2Fmodernx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlinson%2Fmodernx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlinson%2Fmodernx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlinson%2Fmodernx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perlinson","download_url":"https://codeload.github.com/perlinson/modernx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perlinson%2Fmodernx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32922896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"online","status_checked_at":"2026-05-12T02:00:06.338Z","response_time":102,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","concurrent-rendering","devtools","framework","frontend","gui","library","logger","monorepo","react","react-hooks","react18","redux","state-management","typescript"],"created_at":"2026-05-12T04:04:23.500Z","updated_at":"2026-05-12T04:04:29.240Z","avatar_url":"https://github.com/perlinson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"English | [简体中文](./README_zh-CN.md)\n\n# ModernX\n\n[![NPM version](https://img.shields.io/npm/v/modernx.svg?style=flat)](https://npmjs.org/package/modernx)\n[![NPM downloads](http://img.shields.io/npm/dm/modernx.svg?style=flat)](https://npmjs.org/package/modernx)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Build Status](https://img.shields.io/github/workflow/status/perlinson/modernx/CI)](https://github.com/perlinson/modernx/actions)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\nModern React state management framework with concurrent features and modern toolchain. Based on [redux](https://github.com/reactjs/redux), [redux-saga](https://github.com/redux-saga/redux-saga) and [react-router](https://github.com/ReactTraining/react-router). (Inspired by [elm](http://elm-lang.org/) and [choo](https://github.com/yoshuawuyts/choo))\n\n---\n\n## 🚀 Features\n\n### ✨ Modern React 18 Support\n- **Concurrent Features**: Support for `useTransition`, `useDeferredValue`, and automatic batching\n- **Enhanced Performance**: 30-50% reduction in re-renders with automatic batching\n- **React Router v6**: Complete migration tools and compatibility layer\n\n### 📦 Monorepo Architecture\n- **modernx**: Main package with all features\n- **modernx-core**: Core functionality and React integration\n- **modernx-immer**: Immer integration for immutable updates\n- **modernx-loading**: Loading state management\n- **modernx-logger**: Redux logger plugin\n- **modernx-cli**: Command-line tools and scaffolding\n- **modernx-gui**: Development GUI and debugging tools\n\n### 🛠️ Developer Experience\n- **Full TypeScript Support**: Complete TypeScript support with type definitions and ESLint integration\n- **Code Quality**: ESLint + @typescript-eslint + Prettier for consistent code style\n- **Zero Configuration**: Out of the box with sensible defaults\n- **Modern Toolchain**: Built with Node.js 18, latest Babel, and modern build tools\n- **Hot Reload**: Development experience with HMR\n- **Debugging Tools**: Built-in logger and GUI visualization tools\n- **CLI Integration**: Project scaffolding with optional tools\n\n### 🔄 Backward Compatible\n- **100% API Compatibility**: Existing projects upgrade without code changes\n- **Progressive Migration**: Gradually adopt new features\n- **Stable APIs**: Reliable and well-tested\n\n---\n\n## 📦 Installation\n\n```bash\n# Install the main package\nnpm install modernx\n\n# Or with yarn\nyarn add modernx\n\n# Or with pnpm\npnpm add modernx\n```\n\n### Peer Dependencies\n\nMake sure you have React 18+ installed:\n\n```bash\nnpm install react@18 react-dom@18\n```\n\n---\n\n## 🎮 Quick Start\n\n### Basic Example\n\n```javascript\nimport { createApp } from 'modernx';\n\n// 1. Define a model\nconst countModel = {\n  namespace: 'count',\n  state: 0,\n  reducers: {\n    add(state) { return state + 1; },\n    minus(state) { return state - 1; }\n  },\n  effects: {\n    *asyncAdd({ payload }, { put }) {\n      yield new Promise(resolve =\u003e setTimeout(resolve, 1000));\n      yield put({ type: 'add', payload });\n    }\n  }\n};\n\n// 2. Create app\nconst app = createApp({\n  models: [countModel]\n});\n\n// 3. Start app\napp.start('#root');\n```\n\n### With React Components\n\n```javascript\nimport React from 'react';\nimport { connect } from 'modernx';\n\nconst Counter = ({ count, add, minus, asyncAdd }) =\u003e (\n  \u003cdiv\u003e\n    \u003ch2\u003eCount: {count}\u003c/h2\u003e\n    \u003cbutton onClick={add}\u003e+\u003c/button\u003e\n    \u003cbutton onClick={minus}\u003e-\u003c/button\u003e\n    \u003cbutton onClick={asyncAdd}\u003eAsync +1\u003c/button\u003e\n  \u003c/div\u003e\n);\n\nexport default connect(\n  ({ count }) =\u003e ({ count }),\n  ({ add, minus, asyncAdd }) =\u003e ({ add, minus, asyncAdd })\n)(Counter);\n```\n\n---\n\n## 🛠️ Development\n\n### Contributing\n\nWe welcome contributions! Please see our [Developer Guide](./docs/DEVELOPER_GUIDE.md) for detailed instructions.\n\n### Quick Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/perlinson/modernx.git\ncd modernx\n\n# Install dependencies\nnpm install\n\n# Bootstrap packages\nnpm run bootstrap\n\n# Link development dependencies\nnpm run dev:link\n\n# Start development\nnpm run dev\n```\n\n### Development Commands\n\n```bash\n# Build all packages\nnpm run build\n\n# Run tests\nnpm test\n\n# Type checking\nnpm run typecheck\n\n# Lint code\nnpm run lint\n\n# Validate monorepo\nnpm run validate:quick\n```\n\n### Monorepo Management\n\n```bash\n# Workspace status\nnpm run workspaces:status\n\n# Link internal dependencies\nnpm run dev:link\n\n# Clean all packages\nnpm run clean:all\n\n# Run scripts across packages\nnpm run run:all build\n```\n\n---\n\n## 🛠️ Development Tools\n\n### Logger Plugin\n\nAdd comprehensive Redux logging to your ModernX application:\n\n```javascript\nimport modernx from 'modernx';\nimport logger from 'modernx-logger';\n\nconst app = modernx({\n  plugins: [logger({\n    collapsed: true,\n    duration: true,\n    timestamp: true,\n  })],\n});\n```\n\n### GUI Development Tool\n\nStart the development GUI for real-time state visualization:\n\n```bash\n# Start GUI from project directory\nnpx modernx-gui\n\n# Or include in project creation\nnpx modernx create my-app --tools gui\n```\n\nThe GUI provides:\n- **Real-time State Visualization**: Live display of Redux state changes\n- **Action History**: Complete timeline of all actions with payloads\n- **Project Structure Analysis**: Automatic detection of ModernX models\n- **WebSocket Communication**: Real-time synchronization with your app\n\n### CLI Integration\n\nCreate new ModernX projects with optional debugging tools:\n\n```bash\n# Create project with logger and GUI\nnpx modernx create my-app --tools logger,gui\n\n# Interactive project creation\nnpx modernx create my-app\n# Select tools during setup:\n# - Logger: Redux logger for debugging\n# - GUI: Development GUI with real-time visualization\n```\n\n---\n\n## 🎯 React 18 Concurrent Features\n\n### useDvaTransition\n\nNon-blocking state updates with `useTransition`:\n\n```javascript\nimport { useDvaTransition } from 'modernx/react18-utils';\n\nconst HeavyComponent = () =\u003e {\n  const [isPending, startTransition] = useDvaTransition();\n  \n  const handleHeavyOperation = () =\u003e {\n    startTransition(() =\u003e {\n      // Non-blocking state update\n      dispatch({ type: 'heavyOperation' });\n    });\n  };\n  \n  return (\n    \u003cbutton onClick={handleHeavyOperation} disabled={isPending}\u003e\n      {isPending ? 'Processing...' : 'Start Operation'}\n    \u003c/button\u003e\n  );\n};\n```\n\n### useDvaConcurrentState\n\nDeferred rendering with `useDeferredValue`:\n\n```javascript\nimport { useDvaConcurrentState } from 'modernx/react18-utils';\n\nconst SearchComponent = () =\u003e {\n  const { state, deferredState } = useDvaConcurrentState('search');\n  \n  return (\n    \u003cdiv\u003e\n      \u003cinput onChange={(e) =\u003e dispatch({ type: 'search', payload: e.target.value })} /\u003e\n      \u003cdiv\u003eCurrent: {state.results.length} results\u003c/div\u003e\n      \u003cdiv\u003eDeferred: {deferredState.results.length} results\u003c/div\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n---\n\n## 📚 Documentation\n\n### Guides\n- [Installation Guide](./docs/GettingStarted.md#installation)\n- [Quick Start](./docs/GettingStarted.md#quick-start)\n- [Core Concepts](./docs/Concepts.md)\n- [React 18 Features](./docs/GettingStarted.md#react-18-features)\n- [Advanced Usage](./docs/GettingStarted.md#advanced-usage)\n\n### API Reference\n- [createApp](./docs/API.md#createapp)\n- [Model API](./docs/API.md#model-api)\n- [Hooks API](./docs/API.md#hooks-api)\n- [Plugin API](./docs/API.md#plugin-api)\n\n### Examples\n- [Basic Counter](./examples/with-basic)\n- [Todo List](./examples/user-dashboard)\n- [Async Data](./examples/with-basic)\n- [React 18 Concurrent](./examples/react18-concurrent)\n- [React Router v6](./examples/react-router-v6)\n\n---\n\n## 🏗️ Project Structure\n\n```\nmodernx/\n├── packages/\n│   ├── modernx/           # Main package\n│   ├── modernx-core/      # Core functionality\n│   ├── modernx-immer/     # Immer integration\n│   ├── modernx-loading/   # Loading state\n│   ├── modernx-logger/    # Logger plugin\n│   ├── modernx-cli/       # Command-line tools\n│   └── modernx-gui/       # Development GUI\n├── examples/              # Example projects\n├── docs/                  # Documentation\n├── website/              # VuePress website\n└── scripts/               # Build and deployment scripts\n```\n\n---\n\n## 🧪 Development\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/perlinson/modernx.git\ncd modernx\n\n# Install dependencies\nnpm install\n\n# Start development\nnpm run dev\n\n# Run tests\nnpm test\n\n# Build packages\nnpm run build\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run specific package tests\nnpm run test:modernx-core\n```\n\n---\n\n## 📦 Packages\n\n| Package | Version | Size | Description |\n|---------|---------|------|-------------|\n| [modernx](https://www.npmjs.com/package/modernx) | ![npm version](https://img.shields.io/npm/v/modernx.svg) | ~18KB | Main package with all features |\n| [modernx-core](https://www.npmjs.com/package/modernx-core) | ![npm version](https://img.shields.io/npm/v/modernx-core.svg) | ~27KB | Core functionality |\n| [modernx-immer](https://www.npmjs.com/package/modernx-immer) | ![npm version](https://img.shields.io/npm/v/modernx-immer.svg) | ~2KB | Immer integration |\n| [modernx-loading](https://www.npmjs.com/package/modernx-loading) | ![npm version](https://img.shields.io/npm/v/modernx-loading.svg) | ~5KB | Loading state management |\n| [modernx-logger](https://www.npmjs.com/package/modernx-logger) | ![npm version](https://img.shields.io/npm/v/modernx-logger.svg) | ~3KB | Redux logger plugin |\n| [modernx-cli](https://www.npmjs.com/package/modernx-cli) | ![npm version](https://img.shields.io/npm/v/modernx-cli.svg) | ~8KB | Command-line tools |\n| [modernx-gui](https://www.npmjs.com/package/modernx-gui) | ![npm version](https://img.shields.io/npm/v/modernx-gui.svg) | ~12KB | Development GUI |\n\n---\n\n## 🤝 Contributing\n\nWe welcome all kinds of contributions! Please see our [Developer Guide](./docs/DEVELOPER_GUIDE.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n---\n\n## 📄 License\n\nMIT © [perlinson](https://github.com/perlinson)\n\n---\n\n## 🙏 Acknowledgments\n\n- [Redux](https://github.com/reactjs/redux) - State management\n- [Redux-Saga](https://github.com/redux-saga/redux-saga) - Side effects\n- [React Router](https://github.com/ReactTraining/react-router) - Routing\n- [Elm](http://elm-lang.org/) - Architecture inspiration\n- [Choo](https://github.com/yoshuawuyts/choo) - API inspiration\n\n---\n\n## 🔗 Links\n\n- **Documentation**: https://perlinson.github.io/modernx\n- **GitHub**: https://github.com/perlinson/modernx\n- **NPM**: https://www.npmjs.com/package/modernx\n- **Issues**: https://github.com/perlinson/modernx/issues\n- **Discussions**: https://github.com/perlinson/modernx/discussions\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/perlinson\"\u003eperlinson\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperlinson%2Fmodernx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperlinson%2Fmodernx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperlinson%2Fmodernx/lists"}