Multi‐Repository Structure - lasswellt/playbook-library GitHub Wiki

Note: This step assumes you have completed Step 1 – Google Cloud & Firebase Setup. We will dive deeper into Quasar setup, router/Pinia configuration, and other advanced topics in Step 3.

2.1. High-Level Architecture

You’ll maintain one host repository and multiple sub-project repositories. For example:

  1. example-host
  2. example-knowledge
  3. example-administration

Each sub-project is a Quasar application that exposes part of your system via Module Federation. The host app is responsible for:

  • Global Routing (directing users to the sub-projects)
  • Global CSS & Theming (common styles)
  • Global Store (Pinia)
  • Shared Layouts (header, sidebar, etc., if needed)

Why Module Federation?
Module Federation (built into Webpack) allows you to load and integrate separate, independently built “microfrontends” (sub-projects) into a single host application. This approach is ideal for large-scale apps or multi-tenancy solutions where different teams maintain distinct parts of the system.

2.2. Create Repositories on GitHub

  1. Navigate to your GitHub organization or personal account.

  2. Click on “New Repository” and create each repo with the following settings:

    • Owner: e.g., YOUR_ORG or your username
    • Repository Name: e.g., example-host, example-knowledge, etc.
    • Description: (Optional) Provide a brief summary.
    • Visibility: Choose either public or private.
    • Initialize with a README if desired.
    • Add .gitignore: Select the Node template.
    • Choose a license: Select MIT License, or another license required by your organization.

  3. Create a Parent Folder Locally for all your repositories:

    mkdir example-project
cd example-project

  4. Clone Each Repository Locally:

    # Clone the host repository
git clone https://github.com/YOUR_ORG/example-host.git

# Clone the knowledge sub-project
git clone https://github.com/YOUR_ORG/example-knowledge.git

# Clone the administration sub-project
git clone https://github.com/YOUR_ORG/example-administration.git

  5. Set Up the Local Environment so that your directory looks like this:

    example-project/
├─ example-host/
├─ example-knowledge/
└─ example-administration/

2.3. Initialize Quasar in Each Repository

2.3.1. Install Quasar CLI Globally (If Needed)

If you haven’t already installed the Quasar CLI in Step 1, do it now:

pnpm add -g @quasar/cli

If you prefer not to install Quasar CLI globally, you can run commands locally (e.g., pnpm quasar dev or pnpm quasar build).

2.3.2. Initialize Quasar in Each Repository

From your parent directory (example-project), navigate into each repository and run the exact Quasar CLI commands. For example, for example-administration:

cd example-administration
pnpm create quasar@latest

#### During the Quasar setup, follow these steps:
√ What would you like to build? » App with Quasar CLI, let's go!
√ Project folder: ... example-administration
√ Target directory "example-administration" is not empty. Remove existing files and continue? ... yes
√ Pick Quasar version: » Quasar v2 (Vue 3 | latest and greatest)
√ Pick script type: » Typescript
√ Pick Quasar App CLI variant: » Quasar App CLI with Webpack (v4)
√ Package name: ... pb-example-administration
√ Project product name: (must start with letter if building mobile apps) ... pb-example-administration
√ Project description: ... A Quasar Project
√ Pick a Vue component style: » Composition API with <script setup>
√ Pick your CSS preprocessor: » Sass with SCSS syntax
√ Check the features needed for your project: » Linting (ESLint), State Management (Pinia), axios
√ Add Prettier for code formatting? ... yes
√ Install project dependencies? (recommended) » Yes, use pnpm

Repeat for example-knowledge and example-host, each time going into the relevant folder before running pnpm create quasar@latest.

Why Choose Webpack?
We’re using Webpack because it provides Module Federation out of the box, allowing dynamic loading and integration of sub-projects into the host application. Its advanced build capabilities make it a strong choice for large-scale, modular architectures.

2.3.3. Commit & Push the Newly Created Quasar Projects

Inside each repository (e.g., example-administration):

git add .
git commit -m "Initialize Quasar project"
git push origin main

Repeat for the other repositories.

2.4. Adjust Folder Structure & Add Additional Directories

After running the Quasar create commands, you can now add any extra folders that Quasar didn’t create by default. For example, docs, tests, config, and build:

mkdir docs
mkdir tests
mkdir config
mkdir build
mv README.md docs/README.md

Note: Quasar typically places its config file (e.g., quasar.config.js) at the root of your project. There are no default files that are automatically moved into config. If you do decide to relocate Quasar config or environment files, update references accordingly (e.g., in your build or dev scripts).

When this step is complete, your final folder structure for each repository might look like this:

example-host/
|─ src/
├─ docs/
│  └─ README.md
├─ tests/
├─ config/
├─ build/
├─ quasar.config.js  (or left in root, per Quasar defaults)
├─ package.json
└─ ...

Repeat these steps in the host and sub-project repositories as needed.

2.4.1. Finalize & Commit

After creating these additional folders (and possibly reorganizing Quasar’s default files), commit and push again:

git add .
git commit -m "Add docs, config, build, and tests folders"
git push origin main

2.5. Add Basic Files to Each Repository

  1. README.md (in root or /docs):

    • Summarize the purpose of the repository (host or sub-project).
    • Outline how to install dependencies, run development, build, and deploy.

  2. .gitignore:

    • Ensure node_modules, dist, build, or other generated folders are ignored.
    • Quasar provides a .gitignore by default; confirm it meets your needs.

  3. LICENSE (Optional):

    • Add a license file if the project is open source or has specific licensing requirements.

2.6. Git Branching & Collaboration

  1. Decide on a branching strategy (e.g., Git Flow or GitHub Flow).
  2. Protect the main branch to maintain code quality through reviews.
  3. Create Feature Branches for new development and open Pull Requests for review.

2.7. Summary of Commands for Step 2

Below is a sample workflow assuming you’ve already created and cloned each repo:

# Step 2: Multi-Repository Structure Setup

# 1. Create a parent directory and navigate into it
mkdir example-project
cd example-project

# 2. Clone the repositories
git clone https://github.com/YOUR_ORG/example-host.git
git clone https://github.com/YOUR_ORG/example-knowledge.git
git clone https://github.com/YOUR_ORG/example-administration.git

# 3. Initialize Quasar in the host repository
cd example-host
pnpm create quasar@latest
# Follow the interactive Quasar prompts (Quasar v2, Webpack, TypeScript, Pinia, etc.)
git add .
git commit -m "Initialize Quasar project in example-host"
git push origin main
cd ..

# 4. Initialize Quasar in the knowledge sub-project
cd example-knowledge
pnpm create quasar@latest
# Same Quasar prompts
git add .
git commit -m "Initialize Quasar project in example-knowledge"
git push origin main
cd ..

# 5. Initialize Quasar in the administration sub-project
cd example-administration
pnpm create quasar@latest
# Same Quasar prompts
git add .
git commit -m "Initialize Quasar project in example-administration"
git push origin main
cd ..

# 6. Add additional folders after Quasar is initialized
cd example-host
mkdir docs tests config build
mv README.md docs/README.md
git add .
git commit -m "Add docs, config, build, and tests folders"
git push origin main
cd ..

# 7. Repeat folder creation in knowledge
cd example-knowledge
mkdir docs tests config build
mv README.md docs/README.md
git add .
git commit -m "Add docs, config, build, and tests folders"
git push origin main
cd ..

# 8. Repeat folder creation in administration
cd example-administration
mkdir docs tests config build
mv README.md docs/README.md
git add .
git commit -m "Add docs, config, build, and tests folders"
git push origin main
cd ..

Notes:

  • Adjust the repository URLs (e.g., https://github.com/YOUR_ORG/...) to match your GitHub organization or personal account.
  • Each sub-project’s quasar.config.js (or quasar.conf.js) remains at the project’s root by default; only move it to /config if you prefer a custom layout (and then update paths accordingly).
  • Use consistent SCSS variables, theming, and Quasar config to maintain a cohesive UI across projects.

2.8. Next Steps

You now have:

  1. Three GitHub repositories (host + two sub-projects), each with a Quasar application initialized.
  2. A consistent folder structure (src, tests, docs, config, build) applied after Quasar creation.
  3. A multi-repo strategy in place for your project.

Proceed to Step 3, where you’ll:

  • Dive deeper into Quasar configuration, Module Federation, and router/Pinia setups,
  • Integrate Firebase configurations and deployment details,
  • Set up CI/CD pipelines using the service account from Step 1.

End of Step 2: Multi-Repository Structure

You have completed the necessary preparations for a multi-repo Quasar project using Webpack Module Federation, Vue 3, Pinia, and SCSS. Your next step is to refine the Quasar configuration, expand routing and state management, and incorporate Firebase and CI/CD processes as outlined in Step 3.