This content originally appeared on DEV Community and was authored by Rajat
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
.gitmodulesfile - 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>
Then commit the changes in the parent repo. Modern Git versions handle submodule removal more gracefully than older ones.
🧠 Best Practices for Using Submodules in Micro Frontend Setups
- Use the latest Git version – submodule UX is significantly improved.
- Pin to specific commits for deterministic builds.
- Keep submodules clean—avoid mixing parent and submodule changes in one commit.
- Add aliases for common submodule commands to streamline workflows.
- Ensure all team members are trained in submodule workflows to avoid accidental breakage.
💡 Alternatives to Git Submodules
Before committing to submodules, consider these alternatives:
1. Package Manager Approach
Publish each micro frontend as a package via npm (public or private). Then reference them via package.json.
✅ Easier for CI/CD and version management
⛔ Requires package management setup and publishing
2. Monorepo Approach
Manage all micro frontends inside one repo using tools like Nx, Turborepo, or Lerna.
✅ Centralized development and tooling
⛔ Heavier for large codebases if not structured well
📢 Final Thoughts
While Git submodules offer a clean and elegant mechanism to manage independent micro frontend repositories, they can introduce complexity. If your team is already using them, the tips above should help you manage them more effectively. Otherwise, evaluate whether alternatives like npm packages or a monorepo better suit your workflow.
If you're working with a large team and find Git submodules confusing, it might be time to:
- Set up clear documentation
- Provide Git training or workshops
- Automate repetitive tasks with aliases or scripts
🎯 Your Turn, Devs!
👀 Did this article spark new ideas or help solve a real problem?
💬 I'd love to hear about it!
✅ Are you already using this technique in your Angular or frontend project?
🧠 Got questions, doubts, or your own twist on the approach?
Drop them in the comments below — let’s learn together!
🙌 Let’s Grow Together!
If this article added value to your dev journey:
🔁 Share it with your team, tech friends, or community — you never know who might need it right now.
📌 Save it for later and revisit as a quick reference.
🚀 Follow Me for More Angular & Frontend Goodness:
I regularly share hands-on tutorials, clean code tips, scalable frontend architecture, and real-world problem-solving guides.
- 💼 LinkedIn — Let’s connect professionally
- 🎥 Threads — Short-form frontend insights
- 🐦 X (Twitter) — Developer banter + code snippets
- 👥 BlueSky — Stay up to date on frontend trends
- 🌟 GitHub Projects — Explore code in action
- 🌐 Website — Everything in one place
- 📚 Medium Blog — Long-form content and deep-dives
- 💬 Dev Blog — Free Long-form content and deep-dives
- ✉️ Substack — Weekly frontend stories & curated resources
- 🧩 Portfolio — Projects, talks, and recognitions
- ✍️ Hashnode — Developer blog posts & tech discussions
🎉 If you found this article valuable:
- Leave a 👏 Clap
- Drop a 💬 Comment
- Hit 🔔 Follow for more weekly frontend insights
Let’s build cleaner, faster, and smarter web apps — together.
Stay tuned for more Angular tips, patterns, and performance tricks! 🧪🧠🚀
✨ Share Your Thoughts To 📣 Set Your Notification Preference
This content originally appeared on DEV Community and was authored by Rajat
Rajat | Sciencx (2025-11-04T13:30:00+00:00) Managing Git Submodules in a Micro Frontend Architecture: A Step-by-Step Guide. Retrieved from https://www.scien.cx/2025/11/04/managing-git-submodules-in-a-micro-frontend-architecture-a-step-by-step-guide/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.