VS Code
תצוגה מקדימה חיה של פריים המסוף לצד הקוד, יצירת שלד App Router, קטעי קוד וקישורי שגיאות TX.
ההרחבה של Text.js ל-VS Code מציגה את פריים המסוף לצד הקוד. היא משקפת את האפליקציה שרצה באמצעות text dev, או מרנדרת את הקובץ הפתוח עצמו כששום אפליקציה לא רצה. היא מוסיפה גם יצירת שלדים ל-App Router, קטעי קוד וקישורים לקודי שגיאה מסוג TX###.
התקנה
יש להתקין את Text.js מתוך Visual Studio Marketplace. ב-VS Code, יש לפתוח את תצוגת ההרחבות (⌘⇧X) ולחפש textjs.vscode-textjs, או להריץ:
code --install-extension textjs.vscode-textjsההרחבה מופעלת בכל תיקייה שמכילה אפליקציית Text.js: קובץ text.config.ts, או חבילה שתלויה ב-@textjs/app ויש בה ספריית app/. גם מאגרי monorepo עם כמה אפליקציות נתמכים.
תצוגה מקדימה חיה
יש לפתוח page.tsx, layout.tsx או רכיב ולהפעיל את Text.js: Open Preview (⌘K V), או ללחוץ על כפתור התצוגה המקדימה בשורת הכותרת של העורך. החלונית מציירת את הפריים באותה מעטפת DevTools ובאותם תאי Menlo כמו מסוף הדפדפן.
התצוגה המקדימה מקבלת את הפריימים מאחד משני מקורות. התג בסרגל הכלים מציג איזה מהם פעיל:
| מקור | מתי | מה מוצג |
|---|---|---|
| Live | text dev פועל והאפליקציה פתוחה בכרטיסייה בדפדפן | האפליקציה האמיתית, עם המצב, הנתונים וגודל הרשת שלה |
| Headless | אין שרת פיתוח, או שאין כרטיסייה פתוחה | הקובץ הפתוח, שההרחבה מרנדרת בגודל החלונית |
auto (ברירת המחדל) משתמש ב-Live כשאפשר וב-Headless במקרים אחרים. אפשר לקבע אחד מהם דרך התג או באמצעות textjs.preview.mode.
מקלדת
יש ללחוץ על המסוף כדי לשלוח מקשים לאפליקציה: חצים, Tab, קיצורי מקשים, הקלדה והדבקה פועלים כולם, כמו בדפדפן. כדי להפסיק, יש ללחוץ מחוץ למסוף. קיצורי מקשים של העורך כמו ⌘P ו-⌘⇧P עדיין נשלחים ל-VS Code. גלילה מעל המסוף שולחת אירועי גלגלת.
בשדה הכתובת אפשר להקליד נתיב, כמו /deployments/dpl_a1, כדי לנווט בכל אחד מהמקורות.
מצב Live
כשתצוגה מקדימה פתוחה, שרת הפיתוח מבקש מהכרטיסיות המחוברות להזרים את הפריימים שלהן. הכרטיסיות שולחות רק את השורות שהשתנו, ומפסיקות לשלוח כשהתצוגה המקדימה נסגרת, כך שאפליקציה ללא תצוגה מקדימה פתוחה אינה נושאת בעלות כלשהי. שמירת קובץ עוברת דרך Fast Refresh, והתצוגה המקדימה מתעדכנת יחד עם הכרטיסייה.
יש להפעיל את Follow (textjs.preview.followEditor) כדי להעביר את כרטיסיית הדפדפן לנתיב של קובץ ה-page.tsx שבעריכה.
כרטיסיות ברקע לא מקבלות פריימים של אנימציה, ולכן בדרך כלל הן משהות את הפריימים שלהן עד שהן שוב גלויות. כשתצוגה מקדימה צופה בכרטיסייה ברקע, הכרטיסייה מציירת פריים ברגע שמגיע קלט, כך שהקלדה בתצוגה המקדימה עדיין גורמת לעדכון. אנימציות בכרטיסייה ברקע מתעדכנות בערך פעם בשנייה. כדי לשמור על תנועה חלקה שלהן, יש להציב את האפליקציה בחלון משלה.
מצב Headless
ההרחבה מפעילה תוכנית הרצה קטנה בפרויקט. היא טוענת קובצי נתיבים דרך Vite ו-@textjs/app של הפרויקט עצמו, כך שכינויים, TypeScript ו-JSX מתנהגים כמו ב-text dev. היא מעגנת את App Router בנתיב של הקובץ הפתוח, עם ה-layout שלו, באמצעות היסטוריה בזיכרון:
| קובץ | תצוגה מקדימה |
|---|---|
app/page.tsx | / |
app/(shop)/items/[id]/page.tsx | /items/id (מקטעים דינמיים משתמשים בשם שלהם) |
app/blog/[[...slug]]/layout.tsx | /blog |
components/Card.tsx | הייצוא המוגדר כברירת מחדל, או הייצוא הראשון בשם PascalCase, ללא props |
קריאות fetch("/api/...") לאותו מקור מפעילות את מטפלי ה-route.ts בתוך התהליך, כמו ב-text run. הרשת מותאמת לגודל החלונית, ושמירת כל קובץ באפליקציה מרנדרת אותה מחדש. שגיאות מופיעות מעל הפריים, עם קישורים לדפי ה-TX### שלהן.
פקודות
| פקודה | תיאור |
|---|---|
| Text.js: Start Dev Server | הפעלת סקריפט ה-dev של הפרויקט (או text dev) בטרמינל |
| Text.js: Stop Dev Server | עצירת שרת פיתוח שהופעל מתוך VS Code |
| Text.js: Open Preview | פתיחת התצוגה המקדימה החיה עבור הקובץ הפעיל |
| Text.js: Open in Browser Console | פתיחת הנתיב הנוכחי בשרת הפיתוח. לאחר מכן יש לפתוח את מסוף הדפדפן |
| Text.js: New Page | app/<route>/page.tsx עם מטא-נתונים ו-params עם טיפוסים |
| Text.js: New Layout | app/<route>/layout.tsx |
| Text.js: New Route Handler | app/<route>/route.ts עם GET ו-POST |
| Text.js: New Loading UI / Error Boundary / Not Found Page | loading.tsx, error.tsx, not-found.tsx |
הפקודות ליצירת שלדים זמינות גם בתפריט ההקשר של תיקיות בסייר. הן מקבלות מקטעי App Router כמו settings, blog/[slug], docs/[...path] ו-(marketing)/about, ומסרבות להציב page ו-route.ts באותו מקטע. פרויקטי JavaScript (ללא tsconfig.json) מקבלים קובצי .jsx ו-.js.
קטעי קוד
| קידומת | תוכן ההוספה |
|---|---|
txpage, txlayout, txloading, txerror | קובצי נתיבים ששמם כשם התיקייה שלהם |
txc | רכיב מסוף ששמו כשם הקובץ |
txroute, txroutep | מטפלי נתיבים, עם פרמטרים או בלעדיהם |
box, boxb, text, scrollbox, link, spinner | רכיבים |
input, select, tabs | רכיבים אינטראקטיביים |
useInput, useKeymap, useFocus, useTheme, useViewport, useRouter, useInterval | הוקים |
metadata, txconfig | מטא-נתונים של נתיב ו-text.config.ts |
קודי שגיאה
יש לרחף מעל קוד TX### בכל מקום: בקוד המקור, ביומנים, בחלונית הפלט או במחסנית קריאות שהודבקה. חלונית הריחוף מציגה את הכותרת, ההודעה והחבילה שלו, עם קישור לדף שלו באתר textjs.org. כל קוד הוא גם קישור (לחיצה עם ⌘).
שורת המצב
הפריט ▼ מציג את מצב שרת הפיתוח ואת גודל רשת המסוף, למשל ▼ :3000 120×36. כרטיסיות מדווחות לשרת הפיתוח על הגודל שלהן בכל פעם שהוא משתנה, גם כשאין תצוגה מקדימה פתוחה. יש ללחוץ על הפריט כדי לגשת לפקודות הראשיות.
הגדרות
| הגדרה | ברירת מחדל | תיאור |
|---|---|---|
textjs.preview.mode | auto | auto, live או headless |
textjs.preview.followEditor | false | מצב Live: מעקב אחר הנתיב שבעריכה |
textjs.preview.fontSize | 12 | גודל הגופן בתא (DevTools משתמש ב-12) |
textjs.preview.runtime | קובץ בינארי של Node.js לתצוגות מקדימות במצב headless (ברירת מחדל: הקובץ שמגיע עם VS Code) | |
textjs.devServer.url | כתובת URL של שרת הפיתוח (ברירת מחדל: איתור ביציאות 3000–3010). נעשה שימוש רק בכתובות loopback מסוג http:// | |
textjs.devServer.command | פקודה עבור Start Dev Server |
אמון בסביבת העבודה
התצוגה המקדימה ושרת הפיתוח מריצים את קוד הפרויקט (הגדרות Vite, text.config.* ורכיבים). במצב מוגבל ההרחבה מציעה רק קטעי קוד, יצירת שלדים וקישורי שגיאות, ומתעלמת מ-textjs.preview.runtime, textjs.devServer.command ו-textjs.devServer.url שבהגדרות סביבת העבודה. כדי להפעיל את התצוגה המקדימה, יש לתת אמון בסביבת העבודה. קבצים מחוץ לתיקיות של סביבת העבודה לעולם אינם מוצגים בתצוגה מקדימה.
אופן הפעולה
text dev מספק שלוש נקודות קצה לעורכים. הן עונות רק לחיבורי loopback שממוענים למארח loopback (localhost, 127.0.0.1, [::1]), ורק לבקשות ללא Origin או עם המקור של שרת הפיתוח עצמו. בקשות חוצות אתרים ובקשות no-cors מדפדפנים נדחות:
| נקודת קצה | |
|---|---|
GET /__textjs/status | שורש הפרויקט, כרטיסיות מחוברות, גודל הרשת והנתיב הנוכחי |
GET /__textjs/frames | אירועים שנשלחים מהשרת: אירוע frame אחד לכל שינוי, מקודד כהפרשים בין שורות |
POST /__textjs/input | מקש, הדבקה, טקסט מ-IME או ממקש מת (text), גלגלת או ניווט עבור הכרטיסייה. נדרשים JSON והכותרת x-textjs-mirror: 1, כך שאתרים אחרים לא יכולים לשלוח הקשות |
כרטיסיות שולחות פריימים לשרת הפיתוח דרך שקע ה-HMR של Vite, שדורש אסימון ייחודי לכל שרת. פורמט התקשורת מיוצא מתוך @textjs/app/frame-protocol (FrameEncoder, FrameDecoder, parseInputMessage) לצורך בניית מציג עצמאי. שום חלק מזה אינו קיים בפלט של text build.