Streamline Your Micro Frontends with Git Submodules for Scalable, Maintainable Codebases

In modern enterprise-scale frontend applications, micro frontends have become a popular architectural choice. Each micro frontend often exists as an independently deployable and maintainable module, and in many setups, teams choose to manage them using Git submodules.

In this article, I’ll walk you through the key concepts, common pitfalls, and best practices when using Git submodules—explained clearly and politely, with a special focus on working with 10 or more micro frontends.

---

🌱 What Are Git Submodules?

Git submodules allow you to include one Git repository inside another as a subdirectory. This is especially useful when:

• Your team shares a common library across multiple applications.
• You want to keep each micro frontend in a separate Git repo, but still orchestrate and manage them from a parent repo.

---

🔧 Cloning a Repo with Submodules

When cloning a parent repository that contains submodules, the submodules are not downloaded by default.

✅ Recommended way:

git clone --recursive <parent-repo-url>

⛔ If you cloned without -recursive, do:

git submodule update --init --recursive

This will initialize and fetch all submodules and their history.

---

📄 How Git Handles Submodule References

Each submodule is pinned to a specific commit. This information is not stored in the .gitmodules file, but rather inside the parent repo’s .git directory.

You can find what commit the submodule is pinned to using:

git submodule status

This ensures that the parent repo can keep track of exact versions of each micro frontend, leading to consistent builds and deployments.

---

🔁 Making Changes Inside a Submodule

Submodules are treated as completely separate repositories. So if you:

Navigate into a submodule:

cd microfrontend-one/

Make changes and commit them:

git switch main
git add .
git commit -m "Update UI component"

The parent repo still points to the old commit. To update the reference:

cd ../
git add microfrontend-one
git commit -m "Update microfrontend-one to latest commit"

This step is crucial to notify the parent repo that it should now track the new commit of the submodule.

---

🔄 Switching Branches in the Parent Repo

When switching branches in the parent repo, Git does not automatically update the submodules to match the new commit references.

To sync submodules after switching branches:

git submodule update --init --recursive

This ensures that each micro frontend is on the right commit for the selected parent repo branch.

---

⚙️ Automating Submodule Updates (Recommended for Teams)

To avoid having to manually run the above command all the time, update your Git config globally:

git config --global submodule.recurse true
git config --global fetch.recurseSubmodules true

This enables automatic updates during common Git operations like pull and checkout.

---

➕ Adding a New Micro Frontend as a Submodule

To include a new micro frontend repository:

git submodule add <repo-url> microfrontend-new/

This will:

• Clone the repo
• Create or update the .gitmodules file
• Pin the submodule to the latest commit on its default branch

You may then switch to a specific commit or branch in that submodule and commit the change in the parent repo.

---

❌ Removing a Submodule

To safely remove a submodule:

git rm --cached <path-to-submodule>
rm -rf <path-to-submodule>