curl and Terminal Clients

Terminalowe klienty HTTP otrzymują pierwszą klatkę strony jako tekst ANSI z kolorami truecolor zamiast dokumentu HTML. Nie musisz niczego konfigurować.

curl https://my-app.example.com/about

#Żądania otrzymujące klatkę

Żądanie otrzymuje klatkę, gdy spełnia wszystkie te warunki:

• metoda to GET lub HEAD;
• User-Agent zaczyna się od curl/, Wget/, wget2/, HTTPie/ lub xh/;
• brakuje nagłówka Accept lub nie zawiera on text/html.

Przeglądarki, roboty indeksujące i podglądy linków otrzymują stronę HTML. Aby otrzymać HTML za pomocą curl, poproś o niego:

curl -H 'Accept: text/html' https://my-app.example.com/about

Klatka jest wybierana w momencie, w którym zostałaby zwrócona strona: po middleware, rewrites i handlerach tras, ale nigdy dla plików ani ścieżek, których ostatni segment zawiera kropkę. Przekierowania middleware, odpowiedzi 401, nagłówki i przepisywanie ścieżek działają dla curl tak samo jak dla przeglądarek. /api/health nadal uruchamia swój handler, a /robots.txt nadal zwraca plik.

#Zawartość klatki

Klatka to pierwszy wynik renderowania strony, jak w prerenderowanej powłoce: każda granica <Suspense>, która nadal czeka, pokazuje swoją zawartość zastępczą. Asynchroniczne komponenty serwerowe nie są uruchamiane, a fetch() nigdy nie kończy działania, więc dane ładowane w efektach pozostają w stanie ładowania.

• Rozmiar: 80 × 24 komórki. Aplikacja ze stałym obszarem widoku (viewport.responsive: false) używa zamiast tego viewport.width × viewport.height.
• Kolory: 24-bitowe sekwencje sterujące SGR zgodne z viewport.theme aplikacji. Każdy wiersz kończy się resetem, a klatka znakiem nowego wiersza.
• Status: 200 lub 404 ze stroną błędu „nie znaleziono” aplikacji, gdy żadna strona nie pasuje lub strona wywołuje notFound(). Strona, która wywołuje redirect() podczas renderowania, zwraca HTML.

Odpowiedzi mają typ text/plain; charset=utf-8 oraz nagłówki Vary: User-Agent, Accept i Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate, więc współdzielone pamięci podręczne nigdy nie zapisują klatki, by następnie zwrócić ją przeglądarce. Strona HTML pod ścieżką, dla której curl otrzymuje klatkę, ma ten sam nagłówek Vary.

#Obsługiwane środowiska

Strony renderowane po stronie serwera wymagają text start lub bun (zobacz Wdrażanie).

Hosty statyczne nie mogą odpowiadać różnie różnym klientom, więc adapter static nie obsługuje klatek. Na platformach Vercel i Cloudflare klatki stron statycznych są dostarczane wraz z wynikiem budowania. Strony dynamiczne ([id], force-dynamic) zwracają tam HTML, ponieważ adaptery vercel i cloudflare nie wdrażają renderera.

text start i bun dist/server.js renderują pozostałe strony na żądanie za pomocą .text/server/live.mjs i przechowują ostatnie 128 klatek przez 10 sekund. Każdy serwer renderuje najwyżej 20 stron spoza pamięci podręcznej na 10 sekund. Po przekroczeniu tego limitu curl otrzymuje stronę HTML do czasu odnowienia limitu. Jeśli nie można załadować live.mjs na serwerze, na przykład dlatego, że moduł strony odczytuje window na najwyższym poziomie, te strony zwracają HTML.

text build raportuje prerenderowane klatki:

 ✓ Prerendering curl frames (5/5)

#Konfiguracja

Zmień rozmiar dla całej aplikacji lub wyłącz klatki:

import { defineConfig } from "@textjs/app";export default defineConfig({  ansi: { cols: 100, rows: 30 },  // ansi: false,});

Strona może zmienić własny rozmiar lub zwracać HTML także terminalom:

export const ansi = { cols: 120, rows: 40 };// export const ansi = false;

Rozmiary są ograniczane do 1–500 komórek. Przy ansi: false w text.config.ts eksporty stron są ignorowane.

#Zwykły HTTP

curl nie podąża za przekierowaniami, chyba że podasz -L. Vercel przekierowuje żądania http:// do https://, podobnie jak Cloudflare z włączoną opcją Zawsze używaj HTTPS, więc curl http://… wypisuje przekierowanie zamiast klatki. Udostępniaj adresy URL z https://.

#Własne serwery

@textjs/app/ansi eksportuje funkcje pomocnicze do wykrywania żądań i tworzenia odpowiedzi dla serwerów i funkcji, które nie uruchamiają text start ani adaptera:

import { ansiResponse, wantsAnsi } from "@textjs/app/ansi";import { frameToAnsi } from "@textjs/react";if (wantsAnsi(request)) return ansiResponse(frameToAnsi(buffer, { theme: "geistDark" }), request.method);

wantsAnsi(request) przyjmuje też (method, headers) z obiektem Headers interfejsu Web API lub IncomingHttpHeaders ze środowiska Node.js. frameToAnsi(buffer, { theme }) koduje wyrenderowany CellBuffer tak samo jak framework.