README.en-US.md

React SkyrocAdmin

English | 中文

---

Note

If you find React SkyrocAdmin helpful or like our project, please give us a ⭐️ on GitHub. Your support motivates us to keep improving and adding new features! Thank you for your support!

Special Thanks

This project is based on the outstanding open-source project Soybean Admin, developed by Soybean. It is a React implementation of the original project. Special thanks to Soybean for their contributions to open source and for providing an excellent solution for admin panel development. If you like this project, please also give a ⭐️ to the original Soybean Admin.

Introduction

React SkyrocAdmin is a cutting-edge, powerful, and elegantly architected enterprise-grade admin template.

Why Choose React SkyrocAdmin?

• 🎯 Cutting-Edge: Built with 2025's latest frontend stack (React 19, Vite 6, TypeScript 5.7), staying ahead of the curve
• 💪 Powerful: Integrates industry best practices like TanStack Query and Redux Toolkit, providing complete enterprise solutions
• ✨ Elegant Architecture: Clear layered architecture, modular design, comprehensive type system - exemplary code quality
• 📐 Highly Standardized: Strict code conventions, unified project structure, standardized development workflow, perfect for team collaboration

Built with the latest frontend technologies:

Core Tech Stack

• 🚀 React 19 - Latest React version with cutting-edge features
• 🛤️ React Router V7 - Powerful routing management system
• 📦 Redux Toolkit - Modern state management solution
• 🔄 TanStack Query (React Query) 5 - Powerful server state management solution
• 🎨 Ant Design 5.24 - Enterprise-level UI component library
• ⚡️ Vite 6 - Lightning-fast development build tool
• 🎯 TypeScript 5.7 - Complete type system
• 🌈 UnoCSS - High-performance atomic CSS engine
• 📦 pnpm monorepo - Efficient package management

Key Features

• 💡 Code Quality - Strict code standards, elegant architecture, complete TypeScript support
• ⚡️ Ready to Use - No complex configuration, start developing quickly
• 🛠️ Rich Components - Built-in business components and theme configuration options
• 📋 Convention-based Routing - Automated file routing system, Next.js-like development experience
• 🔄 Data Management - Integrated TanStack Query for elegant server state management with auto-caching and revalidation
• 🏗️ Architecture Design - Clear layered service architecture with separated URLs, Keys, and Hooks for high modularity
• 🎨 Theme System - Dark mode, multiple theme colors, layout configurations
• 🌍 Internationalization - Complete i18n solution with multi-language support
• 🔐 Permission Management - Role-based access control system (RBAC)
• 📱 Responsive Design - Perfect adaptation for mobile and desktop
• 🎯 Optimistic UI - Automatic error capture with friendly error interfaces, component-level monitoring
• 🔧 CLI Tools - Built-in command-line tools (Git commit standards, code cleanup, version release, etc.)
• ⚙️ Keep-Alive - Page caching functionality for better UX
• 🎭 Animation System - Smooth animations based on Motion

Monorepo Architecture

The project uses pnpm workspace management with the following packages:

• 📡 @sa/axios - HTTP request library with interceptors and error handling
• 🎨 @sa/color - Theme color processing utilities
• 🪝 @sa/hooks - Common React Hooks collection (useRequest, useBoolean, useArray, etc.)
• 🧩 @sa/materials - Common component library (AdminLayout, PageTab, SimpleScrollbar, etc.)
• 🛠️ @sa/scripts - Command-line toolkit (code generation, Git tools, release tools, etc.)
• 🔧 @sa/utils - Common utility functions
• 🎯 @sa/uno-preset - UnoCSS custom preset configuration

Whether you're learning the latest frontend technologies or developing enterprise-grade admin panels, React SkyrocAdmin is your ideal choice.

Branches

• master branch: Latest stable version, based on React19 + ReactRouter V7.
• v1 branch: Legacy version, based on React18 + ReactRouter V6.

Both branches will continue to receive bug fixes. If you need the older version, switch to the appropriate branch. The v1 branch will remain advanced and feature-rich for 3-5 years.

Version Information

Current Version: v2.5.0

Tech Stack Versions

Technology	Version	Description
React	19.0.0	Core framework
React Router	7.2.0	Routing management
Redux Toolkit	2.5.1	State management
TanStack Query	5.90.8	Data fetching and caching
Ant Design	5.24.1	UI component library
Vite	6.1.1	Build tool
TypeScript	5.7.3	Type system
UnoCSS	66.0.0	Atomic CSS
Motion	12.4.7	Animation library
pnpm	10.4.1	Package manager

Live Preview

• React19 (v2) Version:

  • Preview
  • GitHub Repository
  • Gitee Repository

• React18 (v1) Version:

  • Preview

Documentation

• React19 (v2) Version:
  • Online Docs - Comprehensive Ant Design-themed documentation
• React18 (v1) Version:
  • Online Docs - v1 version documentation

Vue Versions

• NaiveUI Version:

  • Preview - A fresh and elegant admin panel built with Vue3 + NaiveUI.
  • GitHub Repository - Get the latest source code and contribute.
  • Gitee Repository - Faster access for China users.
  • Features:
    • Complete TypeScript support
    • Rich theme customization
    • Elegant coding style
    • Detailed documentation

• AntDesignVue Version:

  • Preview
  • GitHub Repository
  • Gitee Repository

• Legacy Version:

  • Preview
  • GitHub Repository

Ant Design-Themed Comprehensive Documentation

• Docs

Demo Screenshots

Project Structure

soybean-admin-react/
├── build/                    # Build configuration
│   ├── config/              # Vite config (proxy, time, etc.)
│   ├── optimize/            # Build optimization config
│   └── plugins/             # Vite plugin configuration
├── packages/                # Monorepo packages
│   ├── axios/              # HTTP request wrapper
│   ├── color/              # Color utilities
│   ├── hooks/              # React Hooks collection
│   ├── materials/          # Common components library
│   ├── scripts/            # CLI tools
│   ├── uno-preset/         # UnoCSS preset
│   └── utils/              # Utility functions
├── src/
│   ├── assets/             # Static resources
│   ├── components/         # Global components
│   ├── constants/          # Constant definitions
│   ├── features/           # Feature modules
│   │   ├── auth/          # Authentication module
│   │   ├── theme/         # Theme module
│   │   ├── router/        # Router module
│   │   ├── menu/          # Menu module
│   │   ├── tab/           # Tab module
│   │   ├── lang/          # i18n module
│   │   └── ...
│   ├── hooks/              # Business Hooks
│   ├── layouts/            # Layout components
│   ├── locales/            # i18n configuration
│   ├── pages/              # Page components (convention-based routing)
│   │   ├── (base)/        # Base layout pages
│   │   ├── (blank)/       # Blank layout pages
│   │   └── _builtin/      # Built-in pages
│   ├── router/             # Router configuration
│   ├── service/            # API service layer (elegant layered architecture) ✨
│   │   ├── api/           # API request functions
│   │   ├── enums/         # Business enums
│   │   ├── hooks/         # React Query Hooks wrapper
│   │   ├── keys/          # React Query Keys global management
│   │   ├── types/         # TypeScript type definitions
│   │   ├── urls/          # API URL constants
│   │   └── request/       # Request config and interceptors
│   ├── store/              # Redux state management
│   ├── styles/             # Global styles
│   ├── theme/              # Theme configuration
│   ├── types/              # TypeScript type definitions
│   └── utils/              # Utility functions
└── ...config files

Getting Started

Prerequisites

Ensure your environment meets the following requirements:

• git: For cloning and managing the project
• Node.js: >=18.12.0, recommended 18.19.0 or higher
• pnpm: >= 8.7.0, recommended 10.4.1 or higher

Installation Steps

1. Clone the repository

git clone https://github.com/Ohh-889/skyroc-admin.git
cd skyroc-admin

2. Install dependencies

pnpm i

⚠️ Since the project uses pnpm monorepo management, please do not use npm or yarn to install dependencies.

3. Start development server

pnpm dev

The development server will start at http://localhost:9527

4. Build for production

# Production build
pnpm build

# Test environment build
pnpm build:test

Available Commands

# Type checking
pnpm typecheck

# Code formatting and fixing
pnpm lint

# Git commit (with standards)
pnpm commit

# Generate routes
pnpm gen-route

# Clean cache and dependencies
pnpm cleanup

# Release version
pnpm release

# Preview build
pnpm preview

Core Features

🎨 Theme System

• Multiple Theme Colors: Built-in theme colors with custom color support
• Dark Mode: Complete dark mode support with system theme adaptation
• Layout Modes: Vertical, horizontal, mixed, and more layout modes
• Theme Configuration: Visual theme configuration panel with live preview
• Config Export: Support for theme configuration export and import

🔐 Permission Management

• Role-based Permissions: RBAC-based role permission control
• Menu Permissions: Dynamic menu generation based on user roles
• Button Permissions: Fine-grained button-level permission control
• Route Guards: Comprehensive route guards and permission validation
• Dynamic Routes: Support for dynamic route addition based on permissions

🛤️ Routing System

• Convention-based Routing: Automatic route generation based on file system
• Dynamic Routes: Support for dynamic parameter routes like [id], [...slug]
• Route Caching: Keep-Alive page caching functionality
• Route Animations: Page transition animation effects
• Breadcrumbs: Automatic breadcrumb navigation generation
• Route Meta: Rich route metadata configuration

📱 Tab System

• Multi-tabs: Chrome-style multi-tab management
• Context Menu: Close, refresh, pin, and other operations
• Tab Drag: Support for tab drag and drop sorting
• Tab Caching: Tab state persistence
• Quick Actions: Close others, close left, close right, etc.

🌍 Internationalization

• Multi-language: Support for Chinese, English, and more
• Dynamic Switching: Real-time language switching without refresh
• Antd Integration: Complete Antd component internationalization
• Dayjs Integration: Date and time internationalization support

🔄 Data Management

TanStack Query Integration

The project deeply integrates TanStack Query (React Query), providing an elegant and powerful server state management solution:

Architecture Design

Adopts a layered design with clear and elegant code organization:

• urls/: Centralized URL constant management, avoiding hard-coding

  // src/service/urls/auth.ts
  export const AUTH_URLS = {
    LOGIN: '/auth/login',
    GET_USER_INFO: '/auth/getUserInfo',
    REFRESH_TOKEN: '/auth/refreshToken'
  } as const;

• keys/: Global unique React Query Keys management

  // src/service/keys/index.ts
  export const QUERY_KEYS = {
    AUTH: {
      USER_INFO: ['auth', 'userInfo'] as const
    }
  } as const;

• api/: Pure API request functions

  // src/service/api/auth.ts
  export function fetchLogin(userName: string, password: string) {
    return request<Api.Auth.LoginToken>({
      url: AUTH_URLS.LOGIN,
      method: 'post',
      data: { userName, password }
    });
  }

• hooks/: React Query Hooks wrapper

  // src/service/hooks/useAuth.ts
  export function useLogin() {
    return useMutation({
      mutationKey: MUTATION_KEYS.AUTH.LOGIN,
      mutationFn: ({ userName, password }) => fetchLogin(userName, password)
    });
  }

Core Features

• ✨ Auto Caching: Smart cache management, reducing unnecessary network requests
• 🔄 Auto Revalidation: Automatically refetch stale data to keep it fresh
• ⚡️ Concurrent Requests: Automatic deduplication and batching of concurrent requests
• 🎯 Optimistic Updates: Support for optimistic UI updates, improving user experience
• 🔌 Offline Support: Data caching and synchronization in offline mode
• 📊 DevTools: Powerful developer tools for real-time request status monitoring

Usage Example

// Use in components
import { useLogin, useUserInfo } from '@/service/hooks';

function LoginPage() {
  const { mutate: login, isPending } = useLogin();
  const { data: userInfo, isLoading } = useUserInfo();

  const handleLogin = () => {
    login({ userName: 'admin', password: '123456' }, {
      onSuccess: (data) => {
        // Handle successful login
      }
    });
  };

  return <button onClick={handleLogin} disabled={isPending}>Login</button>;
}

Layered Architecture Benefits

This layered architecture design brings numerous advantages:

1. Clear Responsibilities: Each layer has a clear responsibility, easy to understand and maintain
2. Type Safety: Complete TypeScript type support, full-chain type safety from API to UI
3. Easy Testing: Independent layers facilitate unit testing and integration testing
4. Highly Reusable: Hooks can be reused across multiple components after encapsulation
5. Unified Management: Centralized Keys management prevents cache key conflicts
6. Code Standards: Enforces standardized code organization for efficient team collaboration

📡 HTTP Requests

• Axios Wrapper: Complete request interception and response handling
• Error Handling: Unified error handling mechanism
• Token Refresh: Automatic token refresh mechanism
• Request Cancellation: Support for request cancellation and duplicate request filtering
• useRequest: Powerful request Hook with caching, polling, debounce, throttle, and more

🎭 Component Library

Built-in rich business components:

• SystemLogo: System logo component
• ButtonIcon: Icon button component
• SvgIcon: SVG icon component
• DarkModeContainer: Dark mode container
• FullScreen: Full-screen toggle component
• BetterScroll: Enhanced scroll component
• ErrorBoundary: Error boundary component
• NumberTicker: Number scrolling animation
• TypingAnimation: Typewriter animation
• WaveBg: Wave background animation
• And more...

🛠️ Development Tools

• ESLint: Code quality checking
• TypeScript: Complete type checking
• Git Hooks: Pre-commit automatic checks
• Conventional Commits: Standardized commit messages
• CLI Tools: Built-in command-line toolkit
• Vite Inspector: Development debugging tool

Contribution

We warmly welcome and appreciate all forms of contributions. If you have any ideas or suggestions, please share them via pull requests or GitHub issues.

Git Commit Guidelines

This project includes a commit command to generate commit messages following the Conventional Commits standard. When submitting PRs, please use the pnpm commit command to create standardized commit messages.

Browser Support

For the best experience, use the latest version of Chrome.

not support	last 2 versions	last 2 versions	last 2 versions	last 2 versions

Open Source Authors

Ohh-889

Soybean

Contributors

Thanks to the following contributors. If you want to contribute, please refer to Contribution.

Community

React SkyrocAdmin is a completely free and open-source project, aiming to make developing medium-to-large admin systems easier. We also provide QQ and WeChat groups for user discussions. Feel free to ask questions in the group.

QQ Group

Add the WeChat below to contact the author and get invited to the WeChat group

WeChat Group

License

This project is licensed under MIT © 2021 Skyroc. It is intended for learning and reference only. For commercial use, please retain the original author's copyright information. The author does not guarantee or take responsibility for any risks associated with using the software.