DocsDeveloper SectionStorefront Management & Component Sync

Storefront Management, Loomix Sync & GitHub CI/CD

The project features a dedicated Storefront Management panel inside Strapi Admin alongside automated GitHub Actions CI/CD pipelines. This eliminates the need for manual CLI tools, allowing you to synchronize styles from the Loomix Registry, queue changes, and deploy seamlessly to production.

Automated Cloud Sync & Local Development

All storefront component syncing and production deployments are handled directly through the Strapi Admin Storefront Management panel and GitHub Actions CI/CD.

Strapi Storefront Management Panel

Inside the Strapi Admin dashboard, navigate to the Storefront Management menu. From this interface, you can:

Select Component: Choose from predefined groups (Home, Layout, Account, Cart & Checkout, Common, Pages).
Select Style or Sync All: Enter a specific style (e.g. style-4) or check Sync all styles to download the complete component folder.
Deploy Immediately: Optionally check this box to trigger a deployment right away upon syncing.
Add / Remove Style: Click Add / Sync Style to pull the latest code or Remove Style to delete unused styles.
Live Deployment Status: An interactive status widget at the top of the page displays the real-time build state (🟡 Building, 🟢 Live & Deployed, 🔴 Failed), with auto-refresh and direct GitHub log links.

Strapi Admin Storefront UI Route

bash

# Access in Strapi Dashboard:
http://admin.local/admin -> Storefront Management
# Or via direct API:
POST /api/storefront/sync-component

Pending Updates & Batch Deployments

To prevent redundant builds, style changes are queued locally in a .sync-history.json file:

Pending Queue: View all pending additions and deletions before deploying.
Undo Capability: Easily undo any pending change with a single click before building.
Update Storefront: When ready, click Update Storefront to dispatch a single batch payload to GitHub Actions for production rebuild.

GitHub Actions CI/CD Pipeline (Production)

When running in production (NODE_ENV=production), the sync workflow operates as follows:

1. Dispatch: Clicking Update Storefront calls the GitHub API (repository_dispatch event deploy-storefront).

2. Sync & Commit: The deploy-storefront.yml workflow checks out the repo, pulls component files from the registry, and commits changes back to main.

3. Build Image: It triggers build-storefront.yml which compiles the Next.js production image and pushes it to GitHub Packages (ghcr.io).

4. Self-Hosted Deploy: The GitHub Actions Self-Hosted Runner on your VPS pulls the new image and restarts the container with zero downtime.

5. Live Notification & Status in Strapi: You don't need to stay on GitHub. The Strapi Storefront Management page automatically tracks the build progress and displays a celebration alert (🎉) once the new styles are deployed and live on your server!

4. Automated Component Sync Architecture

When you click Update Storefront in Strapi Admin, the backend sends a repository_dispatch event to GitHub. The GitHub Actions runner executes the sync pipeline in the cloud, updates store/src/modules/, commits changes, and deploys to the VPS using the Self-Hosted Runner.

GitHub Actions Sync Step

bash

# Executed automatically in GitHub Actions:
node scripts/sync-loom-component.js "$ACTION" "$COMPONENT"
git add store/src/modules
git commit -m "chore(storefront): sync components from Loomix registry [skip ci]"
git push

5. Open Registry Ecosystem & Custom Registry Architecture

The component synchronization engine downloads blocks directly from GitHub. You have full freedom to use the public Loomix Blocks registry or build your own custom registry for your team and clients.

Registry Source Options:

Option A: Official Public Loomix Blocks Registry (Free & No Token Required)

Instant, open-source access to all official styles and upcoming components directly from GitHub. No tokens or login required, and community developers can contribute via Pull Requests.

Option B: Your Own Custom In-House Registry

You can create your own public or private GitHub repository to host your agency's private design system and custom client blocks.

Registry Folder Structure Specification:

The sync engine requires the registry repository to match the internal structure of src/modules/:

Registry Tree Structure

text

my-loomix-registry/
└── src/
    └── modules/
        ├── home/
        │   └── components/
        │       ├── FeaturesBlock/
        │       │   ├── style-1.tsx
        │       │   ├── style-2.tsx
        │       │   ├── style-3.tsx
        │       │   └── style-4.tsx
        │       ├── ProductShowcase/
        │       │   ├── style-1.tsx
        │       │   ├── style-2.tsx
        │       │   └── style-3.tsx
        │       ├── Blog/
        │       ├── CategoryCollection/
        │       └── SplitBanner/
        ├── layout/
        │   └── components/
        │       ├── Header/
        │       └── Footer/
        └── account/ | cart/ | checkout/ | common/

How to Create and Connect Your Own Registry:

1. Create Repository: Create a new public or private repository on GitHub (e.g. my-agency/loomix-styles-registry).
2. Setup Directory Structure: Create the root folder src/modules/ and replicate the component hierarchy matching Strapi's component groups.
3. Permissions: If using a private repository, create a Personal Access Token (classic) with repo scope.
4. Update .env: Set REGISTRY_URL to your raw GitHub URL in your .env file.

Registry Environment Configuration (.env)

env

# Option A: Official Public Loomix Registry (Default - No Token Required)
REGISTRY_URL=https://raw.githubusercontent.com/landa33/loom-blocks-registry/main/src/modules
 
# Option B: Custom Private GitHub Registry
# REGISTRY_URL=https://raw.githubusercontent.com/your-org/your-custom-registry/main/src/modules
# GITHUB_PAT=ghp_your_personal_access_token # (only if private)