Wdrażanie

text build tworzy przenośny katalog dist/. Adapter przekształca go w wynik oczekiwany przez platformę.

#Adaptery

text build --adapter <name>

Adapter może też pochodzić ze zmiennej TEXTJS_ADAPTER. Gdy text build działa na platformie Vercel (VERCEL=1) lub Cloudflare Pages (CF_PAGES=1), odpowiedni adapter jest wybierany automatycznie.

Adaptery serwerowe (bun, vercel i cloudflare) uruchamiają ten sam potok co text start: middleware, rewrites, handlery tras z pamięcią podręczną tras, zasoby statyczne, a następnie dokument konsoli dla adresów URL stron. Klienty terminalowe, takie jak curl, otrzymują zamiast tego pierwszą klatkę strony jako tekst ANSI. W przypadku vercel i cloudflare dotyczy to tylko stron statycznych (zobacz curl i klienty terminalowe). Adaptery serwerowe udostępniają pliki z hashem pod /assets/ z nagłówkiem Cache-Control: public, max-age=31536000, immutable.

#Hosting statyczny

text build --adapter static

Użyj go na hostingach bez serwera, takich jak GitHub Pages, S3 lub CDN. Handlery tras GET z dynamic = "force-static" lub revalidate przechodzą prerenderowanie do plików: app/api/feed.json/route.ts staje się dist/api/feed.json. Kopia index.html jest zapisywana jako 404.html, aby głębokie linki otwierały aplikację konsolową. Hosting statyczny nie potrafi odróżnić curl od przeglądarki, więc curl otrzymuje stronę HTML.

Budowanie kończy się błędem z listą wszystkich powodów, jeśli aplikacja potrzebuje serwera: middleware.ts, trasy renderowane po stronie serwera, dynamiczne handlery tras, handlery tras z segmentami dynamicznymi lub metody inne niż GET. Zamiast tego skonfiguruj rewrites na hostingu.

#Bun

text build --adapter bunPORT=8080 bun dist/server.js

Adapter bun zapisuje pojedynczy, samodzielny serwer, który nie potrzebuje node_modules podczas działania. Odczytuje PORT (domyślnie 3000) i HOSTNAME (domyślnie 0.0.0.0) i nigdy nie udostępnia server.js ani .text/. To długotrwały proces, więc obsługuje również trasy renderowane po stronie serwera (export const runtime = "server") i ich aktywne sesje, tak jak text start. Użyj go w kontenerze:

FROM oven/bun:1COPY dist /appCMD ["bun", "/app/server.js"]

#Vercel

text build --adapter vercelvercel deploy --prebuilt

Możesz też wypchnąć zmiany do repozytorium Git połączonego z platformą Vercel: proces budowania uruchamia text build, wykrywa Vercel i zapisuje .vercel/output.

Middleware edge używa protokołu x-middleware-next / x-middleware-rewrite, więc nadpisywanie nagłówków i przepisywanie odbywa się w routerze platformy Vercel przed dotarciem do funkcji lub CDN. Wszystkie reguły dopasowania współdzielą jeden wzorzec trasy src. Żądania nieobjęte żadną regułą pomijają middleware, chyba że ich ścieżka może nie mieć postaci kanonicznej (sekwencje procentowe, znaki kodowane przez parser URL, //, segmenty . lub .., końcowy ukośnik). Middleware dopasowuje wtedy ścieżkę kanoniczną, sprawdza has / missing i przepisuje żądanie na tę ścieżkę, aby Vercel kierował je w ten sam sposób. Aplikacje bez middleware.ts otrzymują tę samą funkcję edge, która wykonuje tylko przepisywanie. Ponieważ każdy wynik budowania zawiera funkcję Edge, wdrażaj z zalogowanego konta Vercel: anonimowe wdrożenia (vercel deploy --temporary) nie akceptują funkcji Edge.

Funkcja handlera jest wewnętrzna. Każda trasa handlera przekazuje jej dopasowaną ścieżkę w nagłówku żądania x-textjs-path. Ten nagłówek jest usuwany z każdego żądania przed middleware i po nim, a middleware edge nigdy go nie przekazuje (ani od klienta, ani z middleware.ts), więc tylko trasy handlerów mogą go ustawić. Żądania do /_textjs/* zwracają 404 bez uruchamiania funkcji, przed middleware i regułami przepisywania oraz po nich. Wygenerowane trasy uwzględniają wielkość liter przy dopasowaniu, tak jak reguły dopasowania i przepisywania na każdym innym hostingu.

Testy adaptera uruchamiają ten wynik w lokalnej emulacji routera platformy Vercel. Zachowanie przy dopasowaniu src, przechwytywaniu dest, przekształcaniu nagłówków i trasach status sprawdzono na rzeczywistych wdrożeniach; middleware Edge nie sprawdzono, ponieważ nie można go wdrożyć anonimowo.

#Cloudflare Pages

text build --adapter cloudflarebunx wrangler pages dev dist --compatibility-flags=nodejs_compatbunx wrangler pages deploy dist

Wynik korzysta z trybu zaawansowanego Pages:

Katalog .text/ (pakiety serwera i manifesty kompilacji) jest usuwany z dist/, ponieważ Pages publikuje katalog bez zmian.

Włącz flagę zgodności nodejs_compat w projekcie Pages (Ustawienia → Środowisko wykonawcze) lub w pliku wrangler.toml; pamięć podręczna danych korzysta z AsyncLocalStorage. Pliki statyczne są udostępniane przez powiązanie ASSETS, a rewalidacja w tle korzysta z ctx.waitUntil().

Przy włączonym middleware każde żądanie uruchamia workera, również dla zasobów z hashem, aby middleware widział każdą ścieżkę, pod którą można uzyskać dostęp do pliku. Każde żądanie uruchamiające workera to jedno wywołanie Functions i wlicza się do twojego limitu żądań Workers. Przy wczytywaniu strony obejmuje to dokument i każdy pobierany przez niego plik (2 dla małej aplikacji testowej z jednym pakietem JavaScript; więcej dla aplikacji z większą liczbą plików). W planie Workers Free po wyczerpaniu dziennego limitu Pages udostępnia pliki statyczne bez workera, co pomija middleware. Jeśli middleware chroni cokolwiek w dist/, ustaw Ustawienia → Środowisko wykonawcze → Działanie po awarii: otwarte / zamknięte na Zamknięte po awarii.

name = "my-console"pages_build_output_dir = "dist"compatibility_date = "2025-01-01"compatibility_flags = ["nodejs_compat"]

#Aktualizacja

Poprawki bezpieczeństwa w @textjs/app trafiają do wdrożenia dopiero po ponownym zbudowaniu i wdrożeniu aplikacji:

• Vercel: wdróż nowy katalog .vercel/output.
• Cloudflare Pages: wdróż nowy katalog dist/ z plikami _worker.js i _routes.json.
• Bun: wdróż cały nowy katalog dist/ (server.js, zasoby i pakiety aktywnych sesji) i uruchom serwer ponownie.
• text start: uruchom text build i uruchom serwer ponownie.

Starsze wdrożenia pozostają dostępne pod własnymi adresami URL (na przykład adresami podglądu Vercel i Cloudflare Pages). Usuń je lub obejmij ochroną dostępu platformy.

#Trasy renderowane po stronie serwera

Trasy renderowane po stronie serwera utrzymują sesję dla każdej otwartej karty, więc potrzebują długotrwale działającego serwera: text start lub adaptera bun. Adaptery static, vercel i cloudflare przerywają budowanie błędem TX030, gdy strona eksportuje runtime = "server".

#Za serwerem proxy

text start nasłuchuje na 127.0.0.1 i podczas nasłuchiwania na interfejsie pętli zwrotnej odpowiada tylko hostom localhost, *.localhost i hostom z adresem IP (ochrona przed DNS rebinding). Pozostałe hosty otrzymują 403 z TX028. Umieść ustawienia publiczne w pliku text.config.ts:

import { defineConfig } from "@textjs/app";export default defineConfig({  server: {    origin: "https://console.example.com", // request.url always uses it (or TEXTJS_ORIGIN)    trustProxy: true, // read X-Forwarded-Host / -Proto from your proxy (or TRUST_PROXY=1)    allowedHosts: [".example.com"],  },});

Bez origin ani trustProxy adres request.url jest budowany ze zweryfikowanego nagłówka Host z użyciem http.

#Ograniczenia

• proxy w pliku text.config.ts działa tylko w text dev i text start; adaptery go nie uwzględniają. Użyj rewrites, które obsługuje każdy adapter serwerowy.
• Każda instancja serverless ma własną pamięć podręczną w pamięci operacyjnej. Zobacz Buforowanie.
• Reguły rewrites używające surowych grup wyrażeń regularnych są tłumaczone na trasy Vercel w miarę możliwości; parametry nazwane (:slug, :path*) są odwzorowywane dokładnie.