Architecture Upgrade of the Tongtian Tower Frontend Platform Using Git Submodule, Workspace, and NPM Packages

Background – Tongtian Tower is JD's visual page‑building platform. With the need to support multiple international and commercial sites (Indonesia, Thailand, BAIC, etc.), the front‑end team faced challenges in managing modules across many sites while keeping development cost low and maintaining agility.

Analysis and Solution – The team identified two core problems: reuse of functional modules across projects and site‑specific configuration. Three reuse strategies were considered (copy‑paste, npm package, Bit‑like tools). The chosen solution combines Git Submodule (as a Bit‑style manager), Yarn workspace , and traditional npm packages.

Step 1 – Git Submodule Refactor – After evaluating alternatives (single‑SPA, Lerna, Webpack 5 Module Federation), Git Submodule was selected for its low intrusion and stable API. The team extracted reusable code into a separate repository and added it as a submodule:

# 添加子模块到项目根目录下
$ git submodule add [remote-url] [local-path]

To initialize and update the submodule, the following commands are used:

# 当项目中有 .gitsubmodule 文件时，执行此命令会初始化子模块到远程的链接
$ git submodule init
# 将指定 commit id 的子模块的远程代码拉取到本地
$ git submodule update --remote

Removing a submodule requires de‑initialization, cache removal, and manual folder deletion:

# 在 Git 配置中卸载从库配置
$ git submodule deinit [submodule-name]
# 在 Git 缓存中删除从库 cache
$ git rm --cached [submodule-name]
# 手动移除文件夹
$ rm -rf [submodule-name]

Advantages of this approach include rapid code transplantation, high reuse across projects, and dependency‑driven builds.

Step 2 – Workspace Refactor – The UI library and common modules were moved into submodules and managed via Yarn workspaces. Adding workspaces is as simple as updating package.json :

{
"scripts": {...},
// 添加 workspaces 字段
"workspaces": ["submodule-a","submodule-b"],
"dependencies": {...}
}

After removing existing node_modules and reinstalling with yarn install , shared dependencies (e.g., @babel, react) are hoisted to the root, while version‑conflicting packages remain in their respective project folders.

Step 3 – NPM Package Integration – The UI library can still be imported as an npm package ( import UI from '@jmfe/babel-ui'; ) while being physically present as a workspace submodule, allowing dynamic updates without npm link.

Site‑Specific Configuration – Each site maintains its own config.js . Static imports are used for build‑time values, while dynamic imports (React class or hooks) enable runtime theming and UI adjustments. The team also implemented a theming solution using stylus-loader with global variables injected from variables.styl .

Conclusion – The new architecture reduced the effort to migrate a module from five days to one day, cutting overall development time by roughly 50% for the five existing sites. The approach also improves code maintainability, facilitates future site expansion, and provides a solid foundation for further optimizations such as visual submodule management.