Liquid Loom: פריימוורק מבוסס-מקור לפיתוח תבניות Shopify

זה כל הרעיון מאחורי Liquid Loom:

src/theme/sections/home/hero.liquid
                    ↓
dist/theme/sections/hero.liquid

קוד המקור נשאר במקום שבו מפתח מצפה למצוא אותו. הפלט מגיע בדיוק למקום ש-Shopify דורשת.

המיפוי הקטן הזה פותר מתח קבוע בפיתוח תבניות Shopify. תבניות Shopify משתמשות במבנה תיקיות מוגדר, ורוב תיקיות הפריסה אינן תומכות בתיקיות משנה שרירותיות. לעומת זאת, קל יותר להבין בסיס קוד שגדל כאשר sections, snippets, סגנונות והתנהגות שקשורים לאותה יכולת יכולים לחיות יחד לפי פיצ'ר.

Liquid Loom הוא פריימוורק קוד פתוח, מבוסס-מקור, שנבנה סביב הגבול הזה. הוא מאפשר למפתחים לכתוב תבנית Online Store 2.0 בסביבת עבודה מאורגנת, לקמפל נכסי frontend מודרניים באמצעות Vite ו-Tailwind CSS, ולייצר תיקיית dist/theme/ קונבנציונלית ש-Shopify CLI יכולה להציג בתצוגה מקדימה או להעלות ישירות.

הוא לא מחליף את Liquid. הוא לא מוסיף runtime לחנות. הוא הופך את ה-build בין קוד המקור לבין הפלט המוכן ל-Shopify למפורש, דטרמיניסטי וניתן לבדיקה.

למה פיתוח תבניות מבוסס-מקור חשוב

החוזה של Shopify בזמן ריצה שימושי דווקא מפני שהוא קונבנציונלי. לתבנית מוכנה לפריסה יש תיקיות מוכרות כמו layout, sections, snippets, templates, config, locales ו-assets. הפלטפורמה, עורך התבנית, Theme Check ו-Shopify CLI מבינים את המבנה הזה.

הבעיה מתחילה כאשר פורמט הפריסה הופך גם לפורמט הכתיבה.

דמיינו תבנית עם עשרות sections. אזור hero לדף הבית, אוסף מוצרים, גלריית מוצר, המלצות, עגלת צד, חיפוש וניווט גלובלי יושבים זה לצד זה בתיקיית sections/ שטוחה. ה-snippets הקשורים אליהם נמצאים בתיקייה שטוחה אחרת. JavaScript ו-CSS מצטברים סביבם בלי גבול בעלות ברור.

התבנית תקינה, אבל עץ המקור מפסיק להסביר כיצד המוצר מאורגן.

Liquid Loom מתייחס למבנה התיקיות של Shopify כאל יעד build, לא כאל מגבלה על צורת הארגון של קוד המקור. מפתחים יכולים לקבץ קבצים לפי תחום:

src/
├── entrypoints/
│   └── theme.js
├── public/
│   └── icons/
│       └── cart.svg
├── styles/
│   └── theme.css
└── theme/
    ├── sections/
    │   ├── home/
    │   │   └── hero.liquid
    │   └── products/
    │       └── main-product.liquid
    └── snippets/
        └── product/
            └── price.liquid

לאחר מכן ה-build מייצר את המבנה ש-Shopify מצפה לו:

dist/theme/
├── assets/
│   ├── cart.svg
│   ├── style.css
│   └── theme.js
├── sections/
│   ├── hero.liquid
│   └── main-product.liquid
└── snippets/
    └── price.liquid

זו אינה הפשטה לשם הפשטה. עץ המקור מספר למפתחים היכן פיצ'ר שייך, בעוד העץ שנוצר נשאר פשוט מספיק כדי ש-Shopify תבין אותו.

חוזה המיפוי הוא הפריימוורק

Liquid Loom מפריד בכוונה בין שתי משימות.

הממפה הסטטי אחראי על קובצי Liquid, JSON וקבצים ציבוריים. Vite אחראי על JavaScript ו-CSS. שניהם כותבים לאותה תבנית שנוצרת, אבל אף אחד מהם אינו מעמיד פנים שסוגי הקבצים עובדים באותה צורה.

לכל נתיב מקור נתמך יש יעד צפוי אחד. נתיבים שאינם נתמכים נכשלים. קובצי תבנית נדרשים שחסרים נכשלים. JSON לא תקין נכשל. התיקייה שנוצרת ניתנת למחיקה ואסור לערוך אותה ידנית.

החוזה הזה גם תואם להנחיות של Shopify CLI. Shopify מציינת שפקודות theme צריכות לרוץ מול מבנה התיקיות הסטנדרטי, ושפרויקטים שמשתמשים בכלי build עשויים להזדקק להריץ אותן מתוך הפלט שנוצר. Liquid Loom עושה בדיוק את זה: shopify theme dev --path dist/theme.

השטחה דורשת אסטרטגיית התנגשויות

תיקיות פיצ'רים יוצרות סיכון חשוב אחד.

src/theme/sections/home/hero.liquid
src/theme/sections/campaigns/hero.liquid

שני הקבצים ימופו אל:

dist/theme/sections/hero.liquid

מעתיק פזיז יאפשר לקובץ האחרון לנצח. ה-build יצליח, section אחד ייעלם, והתוצאה עלולה להיות תלויה בסדר הקבצים במערכת.

Liquid Loom מתכנן מראש את פעולת ההעתקה המלאה. אם שני קובצי מקור נפתרים לאותו יעד, הוא מעלה BuildCollisionError לפני שאחד מהם מועתק. השגיאה מציינת את היעד ואת שני מקורות ההתנגשות.

ההתנהגות הזו חשובה יותר מהתיקיות המקוננות עצמן. ארגון מועיל רק כאשר התהליך שמשטח אותו בטוח.

בניות אינקרמנטליות ללא פלט מיושן

Liquid Loom שומר manifest תחת .cache/manifest.json. לכל קובץ מקור סטטי נשמרים טביעת תוכן SHA-256, נתיב הפלט וגודל הקובץ בבייטים.

ב-build הבא, קובץ נדלג רק כאשר שלושה תנאים מתקיימים:

1. טביעת התוכן שלו לא השתנתה

2. היעד הממופה שלו לא השתנה

3. קובץ הפלט הצפוי עדיין קיים

קבצים שהשתנו מועתקים שוב. קובצי מקור שנמחקו מסירים את הפלט המיושן שלהם. שינוי שם של קובץ אינו משאיר artifact ישן שמוכן לפריסה.

ה-manifest נכתב לקובץ זמני ייחודי לתהליך ומשנה שם רק לאחר שה-build הסטטי מצליח. לכן build שנקטע אינו יכול להשאיר מטמון חלקי שטוען שהפלט עדכני.

כך נראה דיווח טיפוסי של build ללא שינויים:

LIQUID LOOM · production build
✓ 27 theme files · 0 copied · 27 cached · 0 removed · 21.4 KiB · 1.85s
output dist/theme

המטרה אינה טרמינל תיאטרלי. זהו דיווח שעונה מה השתנה, במה נעשה שימוש חוזר, מה הוסר והיכן נמצאת כעת התבנית המוכנה לפריסה.

פקודות ניקוי צריכות להיות הגנתיות

כלי build מוחקים בסופו של דבר קבצים שנוצרו. לכן אימות נתיבים הוא חלק ממודל הבטיחות של הפריימוורק.

לפני ש-Liquid Loom מריץ build נקי או מסיר את המטמון, הוא פותר את הנתיבים המלאים של שורש הפרויקט, שורש המקור ושורש הפלט. הוא דוחה יעד פלט כאשר היעד הוא:

• שורש הפרויקט עצמו

• תיקיית המקור או אחת מתיקיות המשנה שלה

• כל מיקום מחוץ למאגר

אותו עיקרון חל גם על נתיבי פלט ישנים שנקראים מ-manifest המטמון. רשומת מטמון פגומה או ששונתה אינה יכולה להפנות ניקוי מחוץ ל-dist/theme/.

הבדיקות מכסות את המקרים האלה, מפני שפקודת clean צריכה להיות נוחה, לא אמיצה.

starter אמיתי של OS 2.0, בלי להעמיד פנים שהוא חנות

המאגר כולל תבנית reference ניטרלית לסוחרים עבור Online Store 2.0. היא מכסה את המשטחים הדרושים כדי להוכיח את תהליך העבודה:

• templates לדף הבית, מוצר, אוסף, עגלה, עמוד, חיפוש ו-404

• JSON templates וקבוצות sections ניתנות לעריכה עבור header ו-footer

• הגדרות תבנית שחשופות כ-CSS custom properties

• ניווט סמנטי, מצבי focus גלויים, קישורי דילוג ותמיכה ב-reduced motion

• טפסי מוצר ועגלה סטנדרטיים של Shopify שממשיכים לעבוד ללא JavaScript

• שיפורים קטנים ומדורגים לניווט במובייל ולבקרי כמות

זה חשוב מפני שקל יותר להעריך פריימוורק מול התנהגות אמיתית של תבנית מאשר מול תיקייה ריקה.

ה-starter אינו מתיימר להיות חנות production. אין בו נתוני סוחר, אינטגרציות פרטיות, ספק אנליטיקה, מזהי חנות, תהליך לקוח או מערכת עיצוב לענף מסוים. התפקיד שלו הוא להדגים את חוזה ה-build ואת ברירות המחדל הסבירות. את המראה אמורים להחליף.

שער האיכות הוא פקודה אחת

pnpm validate משחזר מקומית את שער ה-CI של המאגר. הוא מריץ:

test coverage
→ formatting check
→ clean production build
→ project validation
→ Shopify Theme Check
→ public-readiness scan

בזמן ההשקה, המאגר מדווח על 15 בדיקות שעוברות, 96.92% כיסוי שורות, 91.67% כיסוי ענפים, 100% כיסוי פונקציות ואפס עבירות Shopify Theme Check ב-starter שנוצר. ה-CI מריץ את אותה פקודת אימות על Node 24.

סריקת public-readiness מוסיפה בדיקת שחרור פחות נפוצה. היא בוחנת שמות קבצים וטקסטים ציבוריים במאגר כדי לאתר מונחי מוצר או מותג ישנים שהוגדרו להחרגה, תוך דילוג על dependencies, פלט שנוצר, נתוני Git ומטמון. היא מדווחת על מיקום הממצא בלי לחזור על הערך המוחרג בלוגים של CI.

הבדיקה הזו מבטאת עיקרון רחב יותר: מאגר קוד פתוח צריך להוכיח שהוא נייד, לא רק לטעון שהפרטים הפרטיים הוסרו.

מתחילים לבנות עם Liquid Loom

Liquid Loom ציבורי תחת רישיון MIT. הוא דורש Node.js 22.12 ומעלה, Corepack ו-pnpm. חנות פיתוח של Shopify נדרשת רק לתצוגה מקדימה חיה ולפריסה.

git clone https://github.com/yotamon/Liquid-Loom.git liquid-loom
cd liquid-loom

corepack enable
pnpm install
pnpm build

לאחר אימות חד-פעמי, אפשר להפעיל יחד את צופה ה-build ואת תבנית הפיתוח של Shopify:

pnpm exec shopify auth login
pnpm dev

לקומפילציה מקומית ללא תצוגה מקדימה של Shopify, השתמשו ב-pnpm watch. לפני פתיחת pull request, השתמשו ב-pnpm validate.

למי Liquid Loom מתאים

Liquid Loom מתאים לצוותי תבניות Shopify שרוצים:

• התנהגות native של Liquid ו-Online Store 2.0

• תיקיות מקור לפי פיצ'רים בלי לוותר על פלט Shopify סטנדרטי

• קומפילציה מודרנית של CSS ו-JavaScript באמצעות Tailwind ו-Vite

• builds דטרמיניסטיים עם מצבי כשל מפורשים

• starter קטן שמדגים משטחי מסחר בלי לכפות מותג או app stack

הוא אינו חנות headless, פריימוורק אפליקציה או תחליף ל-Shopify CLI. הוא סביבת העבודה שמקיפה תבנית: קלטים מאורגנים, טרנספורמציות מוגנות ותוצאה מוכנה לפריסה שנשארת native לפלטפורמה.

כלי הקוד הפתוח השימושיים ביותר לא תמיד מוחקים מגבלות. הם הופכים מגבלות לחוזים שמפתחים יכולים לראות, לבדוק ולסמוך עליהם.

היכנסו ל-מאגר Liquid Loom ב-GitHub, הריצו את חבילת האימות ופתחו issue ממוקד או pull request כאשר תמצאו דרך להפוך את פיתוח תבניות Shopify לצפוי יותר.