Skip to content

Latest commit

 

History

History
207 lines (142 loc) · 6.72 KB

README.md

File metadata and controls

207 lines (142 loc) · 6.72 KB

ModuleWebUI / 页面模块管理系统

项目将重构，此版本问题太多且基本不可用 A modern Android Root universal module management web UI built with Vite — a modular, plugin-friendly frontend for Android Root modules and tooling.

一个基于 Vite 构建的现代化安卓 Root 通用模块管理 Web 界面，提供模块化页面系统、插件开发能力与国际化支持。

Table of Contents / 目录

Quick Start / 快速开始

Clone the repository, install dependencies, and run the dev server.

克隆仓库、安装依赖并运行开发服务器。

# Clone
git clone https://github.com/MemDeco-WG/ModuleWebUI.git
cd ModuleWebUI

# Install
npm ci  # preferred in CI
# or
npm install

# Run the dev server
npm run dev
# Open http://localhost:5173 (default Vite port)

Prerequisites / 环境要求

  • Node.js (LTS recommended) — the project CI targets Node 16, 18, 20, and step used Node 22 for some checks. Use Node >= 16; Node 22 is recommended for local testing.
  • npm (>= 8)
  • Bash / POSIX shell for build.sh (on Windows use WSL / Git Bash)

Install & Run / 安装与运行

  • Use npm ci in CI environments for reproducible installs, or npm install locally.
  • Start dev server:
npm run dev
  • Preview production build locally:
npm run build:prod
npm run preview
  • Use ./build.sh to build a packaged module and replace ModuleWebUI with your module ID:
# Build for module id "com.example.MyModule"
./build.sh com.example.MyModule

Notes:

  • build.sh will call npm ci if node_modules does not exist.
  • build.sh replaces the string ModuleWebUI in src and index.html with the provided module id before running the production build.

Build & Packaging / 构建与打包

  • npm run build — creates a development build using Vite.
  • npm run build:prod — creates a production build (minified and optimized).
  • npm run analyze — helps analyze sizes during build.

The final build artifacts are output to dist/. build.sh helps prepare a module for packaging by replacing the default internal module ID.

Dependency Updates / 依赖更新说明

This repository maintains dependencies via package.json. Recent dependency updates include safe, non-breaking minor/patch bumps. Example of dependencies set in package.json:

  • vite: ^7.0.0 (dev dependency)
  • esbuild: ^0.25.12
  • fdir: ^6.5.0
  • glob: ^11.1.0
  • rollup: ^4.53.3
  • tinyglobby: ^0.2.15
  • Others (picocolors, picomatch, postcss, ...)

How to check for outdated dependencies:

npm outdated

How to safely update dependencies:

  1. Non-breaking updates (safe upgrades):

    npm update

    This upgrades to the latest matching semver versions according to package.json (no major versions).

  2. Major updates (requires manual testing):

    • Use npm install package@latest to install a major update.
    • Or use npx npm-check-updates -u to update package.json to newer major versions, then run npm install.
    • After major updates, carefully test builds and runtime behavior.

  3. Audit vulnerabilities:

    npm audit
npm audit fix  # may be used, but pay attention to major changes

Important: Always run builds & tests (or CI pipeline) after dependency upgrades, and verify changes do not introduce breaking behavior. Some modules have breaking changes across major versions — e.g., nanoid major upgrades changed ESM/CommonJS behavior. Be careful when updating major versions.

Development Tips / 开发建议

  • Pages & modules: This project organizes page modules independently. Each page module has lifecycle hooks and can be dynamically loaded. See src/pages.json and src/pages/ for examples.
  • Plugins: The plugin system allows adding header/footer buttons, UI changes, actions, and listening to events.
  • i18n: The project supports multiple locales. Language pack contributions are supported via src/i18n and settings.json.
  • Use the index.html as the entry point and the modules in src/modules/*.

Troubleshooting:

  • If sed fails on macOS with -i usage, adjust the build.sh or run the replacement manually with the macOS sed form: 
    # For macOS
find src -name "*.js" -exec sed -i '' "s/ModuleWebUI/${MODID}/g" {} \;
sed -i '' "s/ModuleWebUI/${MODID}/g" index.html
  • For Windows, use WSL, Git Bash, or modify build.sh to use cross-platform tools.

Docs / 文档

Further developer/user documentation is available in the docs/ folder:

  • docs/README.md (中文)
  • docs/README.en.md (English)
  • docs/user.md | docs/user-en.md — user documentation
  • docs/page-module-development.md | docs/page-module-development.en.md — Page module development guide
  • docs/plugin-development.md | docs/plugin-development.en.md — Plugin development guide

Use these to learn how to create new pages, custom plugins, and localization.

CI / 持续集成

This repository includes GitHub Actions CI:

  • .github/workflows/ci.yml runs build & quality checks.
  • CI uses npm ci to install dependencies and run build.sh.
  • The build matrix checks Node 16, 18, and 20; one step uses Node 22 to validate certain tooling (like Vite).

Note: Ensure packages remain compatible with Node versions you plan to support.

Contributing / 贡献

Contributions are welcome.

Suggested workflow:

  1. Fork the repository and create a feature branch.
  2. Make changes or fixes.
  3. Run npm install and npm run dev to verify local behavior.
  4. Build with ./build.sh <MODID> to confirm packaging.
  5. Open a PR with a clear description and link to documentation if adding features.

Please adhere to repository guidelines and ensure your changes are properly tested.

License / 许可证

ModuleWebUI is released under the MIT License. See the LICENSE file for full terms.

Acknowledgements / 鸣谢

  • Built with Vite, Rollup, and many open-source libraries (see package.json).
  • Thanks to contributors & community for bug fixes and improvements.

If you need further help or a more specific README section (examples, API docs, or CI customization), let me know which area to expand.