Server-Driven UI (SDUI) to podejście, w którym backend nie wysyła samych danych, tylko opis ekranu: listę komponentów z design systemu, ich właściwości i akcje. Frontend lub aplikacja mobilna ma gotowe komponenty i jedynie renderuje je w kolejności podanej przez serwer. Dzięki temu układ ekranu, testy A/B i personalizację zmienia się po stronie serwera, bez wydawania nowej wersji aplikacji.
W artykule o tym, czym jest design system i jak go zbudować, komponenty były narzędziem frontendowca: programista sięga po Button czy Alert i składa z nich ekran. Server-Driven UI idzie krok dalej. Skoro komponenty mają stałe nazwy i jasno opisane propsy, to o tym, które z nich wyświetlić i w jakiej kolejności, może decydować backend. Poniżej pokazuję, jak wygląda taki kontrakt, jak napisać renderer w React, jak zbudować odpowiedź w Pythonie i Go oraz kiedy to podejście bardziej szkodzi, niż pomaga.
Czym jest Server-Driven UI (SDUI)?
Server-Driven UI (SDUI, interfejs sterowany przez serwer) to architektura, w której API zwraca opis widoku, a nie model domenowy. Zamiast obiektu Product z ceną i nazwą backend odsyła informację: „wyrenderuj baner, pod nim karuzelę produktów, a na końcu komunikat ostrzegawczy”. Klient (aplikacja webowa albo mobilna) ma te komponenty zaprogramowane wcześniej i tylko je składa.
Najłatwiej zobaczyć różnicę na tym samym ekranie zwróconym na dwa sposoby. Klasyczne API:
{
"promotion": { "name": "Zimowa wyprzedaż", "discount": 50 },
"maintenance": true
}
Frontend sam decyduje, że promocję pokaże jako baner, a flagę maintenance zamieni na żółty komunikat. To SDUI:
{
"screenId": "home",
"schemaVersion": 2,
"components": [
{
"type": "HERO_BANNER",
"id": "hero_winter",
"props": {
"title": "Zimowa wyprzedaż",
"subtitle": "Do -50% na wybrane kolekcje",
"imageUrl": "https://assets.example.com/banners/winter.jpg",
"theme": "DARK"
},
"action": { "type": "NAVIGATE", "destination": "/wyprzedaz" }
},
{
"type": "ALERT_MESSAGE",
"id": "alert_maintenance",
"props": {
"intent": "WARNING",
"message": "Dziś w nocy sklep może działać wolniej z powodu prac technicznych.",
"dismissible": true
}
}
]
}
Tutaj decyzja o wyglądzie zapadła na serwerze. Frontend nie wie, że to promocja, wie tylko, że ma narysować HERO_BANNER z podanymi propsami.
| Klasyczne API | Server-Driven UI | |
|---|---|---|
| Co zwraca backend | dane domenowe (Product, User) | drzewo komponentów z propsami i akcjami |
| Kto decyduje o układzie ekranu | frontend | backend |
| Zmiana kolejności sekcji | nowy deploy frontendu (lub aktualizacja w sklepie z aplikacjami) | zmiana odpowiedzi API |
| Wiedza frontendu | logika prezentacji każdego ekranu | biblioteka komponentów i renderer |
| Główne ryzyko | wolniejsze zmiany UI | trudniejsze debugowanie i wersjonowanie kontraktu |
Jak design system i SDUI są ze sobą powiązane?
Design system daje słownik, a SDUI układa z niego zdania. Bez design systemu SDUI nie ma sensu: backend musiałby wysyłać kolory, marginesy i fonty, czyli de facto pisać CSS w JSON-ie. Z design systemem wysyła tylko nazwę komponentu i wartości, które ten komponent przewiduje.
To przekłada się na trzy konkretne zasady kontraktu:
typeodpowiada nazwie komponentu z design systemu. Jeśli w Figmie i w Storybooku komponent nazywa sięAlertMessage, w API jest toALERT_MESSAGE, a nieNotificationBox.- Wygląd przekazujesz jako role, nie wartości. Backend wysyła
"intent": "WARNING"albo"theme": "DARK", a nie"color": "#f59f00". Kolor wynika z tokenów design systemu, tak samo jak--color-primaryw CSS. - Każdy prop o ograniczonym zbiorze wartości to enum. Komponent alertu ma cztery stany (
INFO,SUCCESS,WARNING,ERROR), więc API nie może wysłać"CRITICAL"ani"czerwony". W dalszej części zobaczysz, jak wymusić to w kodzie po obu stronach.
Jak wygląda kontrakt odpowiedzi w SDUI?
Każdy element tablicy components ma te same cztery pola. Warto je ustalić raz dla całego systemu i trzymać się ich w każdym komponencie:
| Pole | Do czego służy | Przykład |
|---|---|---|
type | wskazuje komponent z biblioteki klienta | "HERO_BANNER" |
id | stabilny identyfikator klocka: klucz w React, analityka, podmiana po akcji | "hero_winter" |
props | dane wstrzykiwane do komponentu, już sformatowane | { "title": "Zimowa wyprzedaż" } |
action | co się dzieje po interakcji (opcjonalne) | { "type": "NAVIGATE", "destination": "/wyprzedaz" } |
Do tego dochodzą pola całego ekranu: screenId i schemaVersion. O wersji schematu więcej w części o wersjonowaniu.
Kolejność w tablicy components jest kolejnością na ekranie. Chcesz przenieść formularz nad baner? Zamieniasz kolejność obiektów w odpowiedzi, a frontend nawet o tym nie wie.
Dwie zasady, które oszczędzają później dużo pracy:
- Backend wysyła gotowe do wyświetlenia wartości. Cena przychodzi jako
"89,00 zł", a nie jako89i osobna waluta do sformatowania. Inaczej logika formatowania musi istnieć w każdym kliencie (web, iOS, Android) i prędzej czy później się rozjedzie. idmusi być stabilne. Ten sam baner w kolejnej odpowiedzi powinien mieć to samoid. Na nim opiera się React przy aktualizacji listy, analityka kliknięć i podmiana klocka po akcji.
Jak opisać akcje: nawigację i wysłanie danych?
Akcja to też kontrakt, nie kod. Zamiast zaszywać w aplikacji „po kliknięciu otwórz ekran X”, backend opisuje, co ma się stać. W praktyce wystarcza kilka typów akcji:
| Typ akcji | Pola | Co robi klient |
|---|---|---|
NAVIGATE | destination | przechodzi pod adres lub do ekranu (w aplikacji mobilnej: deep link) |
API_REQUEST | method, endpoint | wysyła żądanie, a odpowiedź renderuje jako nowe klocki |
Z poziomu API możesz zmienić przycisk „Zobacz” w przycisk „Dodaj do koszyka”, który robi POST, bez nowej wersji aplikacji. Lista typów akcji powinna być jednak krótka i zamknięta. Każdy nowy typ to kod, który musi obsłużyć każdy klient.
Jak w SDUI obsłużyć formularz i wysłać dane z powrotem na serwer?
To jedno z częstszych pytań o SDUI, na które trudno znaleźć dobrą odpowiedź: skoro backend opisuje pola formularza, to jak wysłać na serwer to, co wpisał użytkownik? Działa prosty podział ról:
- backend opisuje pola (
name,label, typ, czy wymagane) i akcjęAPI_REQUEST, - klient trzyma wartości lokalnie w stanie formularza, w słowniku kluczowanym polem
name, - po wysłaniu klient robi żądanie z tym słownikiem, a serwer odpowiada kolejnymi klockami, np. komunikatem o sukcesie, który zastępuje formularz.
{
"type": "NEWSLETTER_FORM",
"id": "newsletter",
"props": {
"title": "Zapisz się na newsletter",
"fields": [
{ "name": "email", "label": "Adres e-mail", "inputType": "EMAIL", "required": true }
],
"submitLabel": "Zapisz mnie"
},
"action": { "type": "API_REQUEST", "method": "POST", "endpoint": "/api/newsletter" }
}
Odpowiedź na POST /api/newsletter z {"email": "ola@example.com"}:
{
"components": [
{
"type": "ALERT_MESSAGE",
"id": "newsletter_ok",
"props": {
"intent": "SUCCESS",
"message": "Dzięki! Potwierdzenie wysłaliśmy na ola@example.com.",
"dismissible": true
}
}
]
}
Walidacja w przeglądarce (np. required, type="email") poprawia wygodę, ale ostateczną walidację zawsze robi serwer, tak jak przy każdym formularzu. Jeśli dane są błędne, serwer może odesłać ten sam formularz z komunikatem błędu przy polu.
Jak zbudować Component Mapper w React?
Component Mapper (spotkasz też nazwy dynamic renderer albo dynamic zone resolver) to słownik, który zamienia tekstowy type z API na prawdziwy komponent. Sam pomysł, czyli wybór komponentu ze struktury danych zamiast łańcucha if-ów, znasz może z artykułu o dynamicznym renderowaniu komponentów w React. W SDUI dochodzą dwie rzeczy: dane przychodzą z sieci, więc trzeba je sprawdzić, a klient musi przeżyć komponent, którego nie zna.
Przykład składa się z trzech plików: kontraktu, komponentów z mapą i renderera. Kod sprawdziliśmy w TypeScript 7 (tryb strict), Zod 4 i React 19.
Jak otypować kontrakt w TypeScript i sprawdzić go w runtime?
Typy TypeScriptu znikają po kompilacji, więc same nie ochronią cię przed odpowiedzią API, która nie pasuje do kontraktu. Dlatego kontrakt opisujemy w Zod, a typy z niego wyprowadzamy. Kluczowe jest pole type jako dyskryminator unii (discriminated union): po sprawdzeniu type TypeScript wie, jakie props ma dany klocek.
// contract.ts
import { z } from "zod";
export const Action = z.discriminatedUnion("type", [
z.object({ type: z.literal("NAVIGATE"), destination: z.string() }),
z.object({
type: z.literal("API_REQUEST"),
method: z.enum(["POST", "DELETE"]),
endpoint: z.string(),
}),
]);
const base = { id: z.string(), action: Action.optional() };
const HeroBanner = z.object({
...base,
type: z.literal("HERO_BANNER"),
props: z.object({
title: z.string(),
subtitle: z.string().optional(),
imageUrl: z.url(),
theme: z.enum(["LIGHT", "DARK"]),
}),
});
const AlertMessage = z.object({
...base,
type: z.literal("ALERT_MESSAGE"),
props: z.object({
intent: z.enum(["INFO", "SUCCESS", "WARNING", "ERROR"]),
message: z.string(),
dismissible: z.boolean(),
}),
});
const NewsletterForm = z.object({
...base,
type: z.literal("NEWSLETTER_FORM"),
props: z.object({
title: z.string(),
fields: z.array(
z.object({
name: z.string(),
label: z.string(),
inputType: z.enum(["EMAIL", "TEXT"]),
required: z.boolean(),
}),
),
submitLabel: z.string(),
}),
});
export const Block = z.discriminatedUnion("type", [
HeroBanner,
AlertMessage,
NewsletterForm,
]);
export type Action = z.infer<typeof Action>;
export type Block = z.infer<typeof Block>;
export type BlockType = Block["type"];
const Screen = z.object({
screenId: z.string(),
schemaVersion: z.number(),
components: z.array(z.unknown()),
});
export function parseScreen(json: unknown) {
const screen = Screen.parse(json);
const blocks: Block[] = [];
for (const raw of screen.components) {
const result = Block.safeParse(raw);
if (result.success) {
blocks.push(result.data);
} else {
// nieznany typ albo złe propsy: pomijamy klocek, a nie cały ekran
console.warn("Pominięto komponent:", (raw as { type?: string }).type);
}
}
return { screenId: screen.screenId, blocks };
}
Zwróć uwagę na components: z.array(z.unknown()) i osobne safeParse dla każdego klocka. Gdybyś walidował całą tablicę naraz, jeden nieznany komponent odrzuciłby cały ekran. Tak sprawdzaliśmy to na odpowiedzi z czterema klockami, w tym VIDEO_PLAYER (klient go nie zna) i alertem z "intent": "CRITICAL" (spoza enuma):
Pominięto komponent: VIDEO_PLAYER
Pominięto komponent: ALERT_MESSAGE
[ 'HERO_BANNER', 'NEWSLETTER_FORM' ]
Użytkownik widzi ekran z dwoma poprawnymi klockami, a w logach zostaje ślad, co pominięto. Na produkcji warto ten console.warn zamienić na zgłoszenie do narzędzia do monitoringu błędów.
Jak połączyć typ z API z komponentem?
Mapa jest typowana tak, że każdy typ z kontraktu musi mieć swój komponent, a komponent dostaje dokładnie te propsy, które opisuje kontrakt:
// blocks.tsx
import { useState, type ComponentType } from "react";
import type { Action, Block, BlockType } from "./contract";
type PropsOf<T extends BlockType> = Extract<Block, { type: T }>["props"];
type BlockProps<T extends BlockType> = PropsOf<T> & {
action?: Action;
onAction: (action: Action, payload?: Record<string, string>) => void;
};
export type ComponentMap = { [T in BlockType]: ComponentType<BlockProps<T>> };
function HeroBanner({ title, subtitle, imageUrl, theme, action, onAction }: BlockProps<"HERO_BANNER">) {
return (
<section className={`hero hero--${theme.toLowerCase()}`} style={{ backgroundImage: `url(${imageUrl})` }}>
<h2>{title}</h2>
{subtitle && <p>{subtitle}</p>}
{action && <button onClick={() => onAction(action)}>Zobacz</button>}
</section>
);
}
function AlertMessage({ intent, message }: BlockProps<"ALERT_MESSAGE">) {
return (
<div role="alert" className={`alert alert--${intent.toLowerCase()}`}>
{message}
</div>
);
}
function NewsletterForm({ title, fields, submitLabel, action, onAction }: BlockProps<"NEWSLETTER_FORM">) {
const [values, setValues] = useState<Record<string, string>>({});
return (
<form
onSubmit={(e) => {
e.preventDefault();
if (action) onAction(action, values);
}}
>
<h2>{title}</h2>
{fields.map((field) => (
<label key={field.name}>
{field.label}
<input
name={field.name}
type={field.inputType === "EMAIL" ? "email" : "text"}
required={field.required}
value={values[field.name] ?? ""}
onChange={(e) => setValues({ ...values, [field.name]: e.target.value })}
/>
</label>
))}
<button type="submit">{submitLabel}</button>
</form>
);
}
export const componentMap: ComponentMap = {
HERO_BANNER: HeroBanner,
ALERT_MESSAGE: AlertMessage,
NEWSLETTER_FORM: NewsletterForm,
};
Typ ComponentMap to twoja siatka bezpieczeństwa. Gdy dopiszesz do kontraktu nowy komponent i zapomnisz dodać go do mapy, kompilacja się nie uda. Sprawdziliśmy to, usuwając NEWSLETTER_FORM z mapy:
error TS2741: Property 'NEWSLETTER_FORM' is missing in type '{ HERO_BANNER: ...; ALERT_MESSAGE: ...; }' but required in type 'ComponentMap'.
Komponenty w mapie to w prawdziwym projekcie importy z biblioteki design systemu, a nie komponenty pisane od zera. Tutaj są w jednym pliku tylko po to, żeby przykład był kompletny.
Jak napisać renderer, który nie wywróci całego ekranu?
Renderer przechodzi po klockach, wybiera komponent z mapy i obejmuje każdy klocek osobną granicą błędu (error boundary). Jeśli jeden komponent rzuci wyjątek, znika tylko on, a nie cały ekran:
// renderer.tsx
import { Component, useState, type ComponentType, type ReactNode } from "react";
import { componentMap } from "./blocks";
import { Block, type Action } from "./contract";
class BlockBoundary extends Component<{ type: string; children: ReactNode }, { failed: boolean }> {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error: Error) {
console.error(`Komponent ${this.props.type} rzucił błąd`, error);
}
render() {
return this.state.failed ? null : this.props.children;
}
}
type RendererProps = {
blocks: Block[];
onAction: (action: Action, sourceId: string, payload?: Record<string, string>) => void;
};
export function ScreenRenderer({ blocks, onAction }: RendererProps) {
return (
<>
{blocks.map((block) => {
// TypeScript nie wiąże typu z mapy z typem propsów, stąd jedno rzutowanie
const BlockComponent = componentMap[block.type] as ComponentType<any>;
return (
<BlockBoundary key={block.id} type={block.type}>
<BlockComponent
{...block.props}
action={block.action}
onAction={(action: Action, payload?: Record<string, string>) =>
onAction(action, block.id, payload)
}
/>
</BlockBoundary>
);
})}
</>
);
}
export function ScreenPage({ initialBlocks }: { initialBlocks: Block[] }) {
const [blocks, setBlocks] = useState(initialBlocks);
async function handleAction(action: Action, sourceId: string, payload?: Record<string, string>) {
if (action.type === "NAVIGATE") {
window.location.assign(action.destination);
return;
}
const res = await fetch(action.endpoint, {
method: action.method,
headers: { "Content-Type": "application/json" },
body: payload ? JSON.stringify(payload) : undefined,
});
const { components } = await res.json();
const replacement = Block.array().parse(components);
// klocek, który wywołał akcję, zastępujemy tym, co odesłał serwer
setBlocks((prev) => prev.flatMap((b) => (b.id === sourceId ? replacement : [b])));
}
return <ScreenRenderer blocks={blocks} onAction={handleAction} />;
}
Kilka decyzji w tym kodzie, które łatwo przeoczyć:
key={block.id}, nigdyMath.random()ani indeks. Losowy klucz przy każdym renderze każe Reactowi niszczyć i tworzyć komponent od nowa, więc np. formularz traci wpisany tekst. Indeks psuje się, gdy serwer zmieni kolejność klocków. Dlatego stabilneidjest obowiązkowym polem kontraktu.- Jedno rzutowanie
as ComponentType<any>. TypeScript nie potrafi powiązać typu komponentu wybranego z mapy z typem propsów tego samego klocka. Bezpieczeństwo zapewniają tu dwie rzeczy: typComponentMap(komponent pasuje do kontraktu) i walidacja Zod (dane pasują do kontraktu). - Akcja dostaje
sourceId. Dzięki temu odpowiedź serwera po wysłaniu formularza podmienia dokładnie ten klocek, który ją wywołał.
Użycie na stronie sprowadza się do pobrania ekranu i przekazania klocków:
const response = await fetch("/api/screens/home");
const { blocks } = parseScreen(await response.json());
<ScreenPage initialBlocks={blocks} />
W Next.js z App Routerem pobranie i parseScreen możesz zrobić w komponencie serwerowym, a ScreenPage (ze stanem i obsługą akcji) oznaczyć jako komponent kliencki.
Jak nie ładować kodu wszystkich komponentów naraz?
Gdy biblioteka ma kilkadziesiąt komponentów, a ekran używa pięciu, nie ma sensu wysyłać przeglądarce kodu wszystkich. Komponenty w mapie możesz ładować leniwie przez React.lazy. Pułapka: leniwy komponent zaczyna się pobierać dopiero wtedy, gdy React próbuje go wyrenderować, więc przy zagnieżdżonych klockach pobieranie idzie kaskadą (waterfall): rodzic, potem dziecko, potem wnuk. Rozwiązanie jest proste, bo z odpowiedzi API wiesz z góry, jakich typów potrzebujesz:
const loaders = {
HERO_BANNER: () => import("./blocks/HeroBanner"),
ALERT_MESSAGE: () => import("./blocks/AlertMessage"),
NEWSLETTER_FORM: () => import("./blocks/NewsletterForm"),
};
// zaraz po parseScreen: pobierz równolegle kod wszystkich typów z odpowiedzi
function preloadBlocks(blocks: Block[]) {
new Set(blocks.map((b) => b.type)).forEach((type) => loaders[type]());
}
Moduły są ładowane tylko raz, więc późniejsze React.lazy(loaders[type]) dostanie moduł, który już się pobrał (albo właśnie się pobiera), zamiast startować pobieranie od zera.
Jak zbudować odpowiedź SDUI na backendzie w Pythonie?
Po stronie serwera SDUI nie renderuje żadnych pikseli. Zadanie backendu to zbudować poprawną strukturę JSON i pilnować, żeby zawsze pasowała do kontraktu. W FastAPI robi to Pydantic: każdy komponent to model, a unia z dyskryminatorem type działa tak samo jak w Zod. Jeśli dopiero zaczynasz z tym narzędziem, zobacz, jak działa walidacja danych w FastAPI z Pydantic.
Kod uruchomiliśmy na FastAPI 0.163 i Pydantic 2.14:
# screens.py
from typing import Annotated, Literal
from fastapi import FastAPI, Header
from pydantic import BaseModel, ConfigDict, Field
from pydantic.alias_generators import to_camel
class SduiModel(BaseModel):
# w Pythonie snake_case, w JSON-ie camelCase, jak oczekuje frontend
model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
class Navigate(SduiModel):
type: Literal["NAVIGATE"] = "NAVIGATE"
destination: str
class ApiRequest(SduiModel):
type: Literal["API_REQUEST"] = "API_REQUEST"
method: Literal["POST", "DELETE"]
endpoint: str
Action = Annotated[Navigate | ApiRequest, Field(discriminator="type")]
class HeroBannerProps(SduiModel):
title: str
subtitle: str | None = None
image_url: str
theme: Literal["LIGHT", "DARK"]
class HeroBanner(SduiModel):
type: Literal["HERO_BANNER"] = "HERO_BANNER"
id: str
props: HeroBannerProps
action: Action | None = None
class AlertMessageProps(SduiModel):
intent: Literal["INFO", "SUCCESS", "WARNING", "ERROR"]
message: str
dismissible: bool = True
class AlertMessage(SduiModel):
type: Literal["ALERT_MESSAGE"] = "ALERT_MESSAGE"
id: str
props: AlertMessageProps
class FormField(SduiModel):
name: str
label: str
input_type: Literal["EMAIL", "TEXT"]
required: bool = True
class NewsletterFormProps(SduiModel):
title: str
fields: list[FormField]
submit_label: str
class NewsletterForm(SduiModel):
type: Literal["NEWSLETTER_FORM"] = "NEWSLETTER_FORM"
id: str
props: NewsletterFormProps
action: Action
Block = Annotated[HeroBanner | AlertMessage | NewsletterForm, Field(discriminator="type")]
class Screen(SduiModel):
screen_id: str
schema_version: int = 2
components: list[Block]
Teraz endpoint, który składa ekran. Dwie rzeczy pokazują, po co cały ten wysiłek: wariant testu A/B zmienia kolejność sekcji, a nagłówek X-SDUI-Components pozwala klientowi powiedzieć, które komponenty zna (wrócimy do tego przy wersjonowaniu):
app = FastAPI()
def winter_hero() -> HeroBanner:
return HeroBanner(
id="hero_winter",
props=HeroBannerProps(
title="Zimowa wyprzedaż",
subtitle="Do -50% na wybrane kolekcje",
image_url="https://assets.example.com/banners/winter.jpg",
theme="DARK",
),
action=Navigate(destination="/wyprzedaz"),
)
def newsletter() -> NewsletterForm:
return NewsletterForm(
id="newsletter",
props=NewsletterFormProps(
title="Zapisz się na newsletter",
fields=[FormField(name="email", label="Adres e-mail", input_type="EMAIL")],
submit_label="Zapisz mnie",
),
action=ApiRequest(method="POST", endpoint="/api/newsletter"),
)
@app.get("/api/screens/home", response_model=Screen)
def home_screen(
variant: Literal["A", "B"] = "A",
x_sdui_components: Annotated[str | None, Header()] = None,
):
components: list[Block] = [winter_hero(), newsletter()]
if variant == "B":
# test A/B: w wariancie B formularz idzie na górę ekranu
components.reverse()
if x_sdui_components:
supported = set(x_sdui_components.split(","))
components = [c for c in components if c.type in supported]
return Screen(screen_id="home", components=components)
class NewsletterSignup(BaseModel):
email: str
@app.post("/api/newsletter")
def subscribe(signup: NewsletterSignup):
# tu zapis do bazy; odpowiedź to znowu klocki do wyrenderowania
return {
"components": [
AlertMessage(
id="newsletter_ok",
props=AlertMessageProps(
intent="SUCCESS",
message=f"Dzięki! Potwierdzenie wysłaliśmy na {signup.email}.",
),
).model_dump(by_alias=True)
]
}
Co pokazały testy przez TestClient:
| Żądanie | Wynik |
|---|---|
GET /api/screens/home | HERO_BANNER, potem NEWSLETTER_FORM, pola w camelCase (imageUrl, submitLabel) |
GET /api/screens/home?variant=B | ta sama treść, odwrotna kolejność |
nagłówek X-SDUI-Components: HERO_BANNER,ALERT_MESSAGE | tylko HERO_BANNER, bo klient nie zna formularza |
POST /api/newsletter | jeden klocek ALERT_MESSAGE z intent: SUCCESS |
HeroBannerProps(theme="BLUE") | ValidationError, zanim cokolwiek trafi do klienta |
Najważniejsze jest to ostatnie: błąd w kontrakcie wychodzi na serwerze, a nie u użytkownika. JSON zwrócony przez ten backend przepuściliśmy też przez parseScreen z frontendu i przeszedł walidację Zod bez pominięć, czyli obie strony mówią tym samym kontraktem.
W prawdziwym projekcie nie utrzymujesz dwóch kopii kontraktu ręcznie. FastAPI generuje z modeli schemat OpenAPI, z którego można wygenerować typy dla frontendu. Albo odwrotnie: kontrakt trzymasz w jednym miejscu jako JSON Schema i generujesz z niego modele dla obu stron.
Jak połączyć SDUI z MUI i backendem w Pythonie?
W artykule o design systemie pokazałem MUI, najpopularniejszą bibliotekę komponentów dla Reacta. Dobrze łączy się z SDUI z dwóch powodów: komponenty mają stany opisane enumami, które pasują do naszego kontraktu, a motyw da się zbudować z tokenów przysłanych przez serwer. Backend w Pythonie decyduje wtedy nie tylko o tym, jakie klocki zobaczy użytkownik, ale też w jakich barwach marki.
Jak zamienić klocki z kontraktu na komponenty MUI?
Kontrakt się nie zmienia. Zmieniasz tylko implementację komponentów w mapie. Enum intent z naszego ALERT_MESSAGE odpowiada propowi severity w komponencie Alert z MUI:
intent w kontrakcie | severity w MUI |
|---|---|
INFO | info |
SUCCESS | success |
WARNING | warning |
ERROR | error |
// blocks-mui.tsx
import { useState } from "react";
import { Alert, Button, Stack, TextField, Typography } from "@mui/material";
import type { BlockProps } from "./blocks";
const severityByIntent = {
INFO: "info",
SUCCESS: "success",
WARNING: "warning",
ERROR: "error",
} as const;
export function AlertMessage({ intent, message, dismissible }: BlockProps<"ALERT_MESSAGE">) {
const [open, setOpen] = useState(true);
if (!open) return null;
return (
<Alert severity={severityByIntent[intent]} onClose={dismissible ? () => setOpen(false) : undefined}>
{message}
</Alert>
);
}
export function NewsletterForm({ title, fields, submitLabel, action, onAction }: BlockProps<"NEWSLETTER_FORM">) {
const [values, setValues] = useState<Record<string, string>>({});
return (
<Stack
component="form"
spacing={2}
onSubmit={(e) => {
e.preventDefault();
if (action) onAction(action, values);
}}
>
<Typography variant="h5" component="h2">{title}</Typography>
{fields.map((field) => (
<TextField
key={field.name}
name={field.name}
label={field.label}
type={field.inputType === "EMAIL" ? "email" : "text"}
required={field.required}
value={values[field.name] ?? ""}
onChange={(e) => setValues({ ...values, [field.name]: e.target.value })}
/>
))}
<Button type="submit" variant="contained">{submitLabel}</Button>
</Stack>
);
}
W componentMap podmieniasz importy (ALERT_MESSAGE: AlertMessage z blocks-mui), a renderer, walidacja i backend zostają bez zmian. Obiekt severityByIntent z as const sprawia, że TypeScript zgłosi błąd, jeśli w kontrakcie pojawi się nowy intent, a ktoś zapomni o nim w mapowaniu. Flaga dismissible z backendu decyduje, czy alert ma przycisk zamknięcia: MUI pokazuje go wtedy, gdy przekażesz onClose.
Jak serwować tokeny motywu z backendu w Pythonie?
To scenariusz z aplikacji dla wielu klientów (white-labeling): ten sam sklep działa pod różnymi markami, a każda ma własny kolor główny i zaokrąglenia. Tokeny trzymasz w bazie, a backend wystawia je przez API. Pydantic pilnuje, żeby do frontendu nie trafił kolor "zielony" albo zaokrąglenie 100 px:
# theme_api.py
from typing import Annotated
from fastapi import FastAPI, HTTPException
from pydantic import Field
from screens import SduiModel
HexColor = Annotated[str, Field(pattern=r"^#[0-9a-fA-F]{6}$")]
class ThemeTokens(SduiModel):
primary_color: HexColor
text_color: HexColor = "#212529"
border_radius: int = Field(default=8, ge=0, le=24)
font_family: str = "Inter, system-ui, sans-serif"
# w prawdziwej aplikacji: tabela w bazie, edytowana w panelu klienta
TENANT_THEMES = {
"sklep-zimowy": ThemeTokens(primary_color="#3b5bdb"),
"sklep-ogrodowy": ThemeTokens(primary_color="#2f9e44", border_radius=2),
}
app = FastAPI()
@app.get("/api/tenants/{tenant}/theme", response_model=ThemeTokens)
def tenant_theme(tenant: str):
theme = TENANT_THEMES.get(tenant)
if theme is None:
raise HTTPException(status_code=404, detail="Nieznany klient")
return theme
SduiModel to ta sama klasa bazowa co wcześniej, więc pola wychodzą w camelCase. Na froncie tokeny jeszcze raz przechodzą przez Zod i trafiają do createTheme:
// theme.ts
import { z } from "zod";
import { createTheme } from "@mui/material/styles";
const ThemeTokens = z.object({
primaryColor: z.string().regex(/^#[0-9a-fA-F]{6}$/),
textColor: z.string().regex(/^#[0-9a-fA-F]{6}$/),
borderRadius: z.number().int().min(0).max(24),
fontFamily: z.string(),
});
export async function loadTenantTheme(tenant: string) {
const res = await fetch(`/api/tenants/${tenant}/theme`);
return buildTheme(await res.json());
}
export function buildTheme(json: unknown) {
const tokens = ThemeTokens.parse(json);
return createTheme({
cssVariables: true,
palette: {
primary: { main: tokens.primaryColor },
text: { primary: tokens.textColor },
},
shape: { borderRadius: tokens.borderRadius },
typography: { fontFamily: tokens.fontFamily },
});
}
Gotowy motyw przekazujesz do <ThemeProvider theme={theme}> wokół ScreenPage. Ekran pobierasz z /api/screens/home, motyw z /api/tenants/<klient>/theme, i oba żądania mogą iść równolegle.
Co pokazał test całości?
Połączyliśmy oba backendy z frontendem: tokeny klienta sklep-ogrodowy z FastAPI, ekran z /api/screens/home i odpowiedź po zapisie do newslettera.
| Sprawdzenie | Wynik |
|---|---|
GET /api/tenants/sklep-ogrodowy/theme | 200, {"primaryColor": "#2f9e44", "textColor": "#212529", "borderRadius": 2, ...} |
| nieznany klient | 404 |
ThemeTokens(primary_color="zielony"), border_radius=100 | ValidationError na serwerze |
| motyw MUI z tokenów | w HTML --mui-palette-primary-main:#2f9e44 i --mui-shape-borderRadius:2px |
klocek NEWSLETTER_FORM | pole type="email" i przycisk MuiButton-contained w kolorze klienta |
klocek ALERT_MESSAGE z intent: SUCCESS | zielony Alert z przyciskiem zamknięcia, bo dismissible: true |
Podział odpowiedzialności jest więc czytelny: design system (MUI + motyw) wie, jak wygląda alert sukcesu, kontrakt SDUI mówi, że w tym miejscu ma być alert sukcesu z daną treścią, a backend w Pythonie decyduje, kiedy go pokazać i w jakich barwach marki.
Jak wygląda SDUI w Go i wzorzec Backend for Frontend?
W Go SDUI najczęściej spotkasz w warstwie BFF (Backend for Frontend): osobnym serwisie, który dla konkretnego klienta (np. aplikacji mobilnej) zbiera dane z wielu mikroserwisów i składa z nich jeden ekran. Go dobrze się do tego nadaje, bo równoległe wywołania kilku serwisów są w nim tanie dzięki gorutynom. Jeśli ten temat jest dla ciebie nowy, zacznij od artykułu o współbieżności w Go i Pythonie.
Kontrakt opisujesz strukturami z tagami JSON. Konstruktory pilnują, że typ klocka zawsze idzie w parze z właściwymi propsami:
package main
import (
"context"
"encoding/json"
"net/http"
"sync"
"time"
)
type Intent string
const (
IntentInfo Intent = "INFO"
IntentWarning Intent = "WARNING"
)
type Action struct {
Type string `json:"type"`
Destination string `json:"destination,omitempty"`
Method string `json:"method,omitempty"`
Endpoint string `json:"endpoint,omitempty"`
}
type Component struct {
Type string `json:"type"`
ID string `json:"id"`
Props any `json:"props"`
Action *Action `json:"action,omitempty"`
}
type HeroBannerProps struct {
Title string `json:"title"`
Subtitle string `json:"subtitle,omitempty"`
ImageURL string `json:"imageUrl"`
Theme string `json:"theme"`
}
type AlertMessageProps struct {
Intent Intent `json:"intent"`
Message string `json:"message"`
Dismissible bool `json:"dismissible"`
}
// konstruktory pilnują, że typ klocka pasuje do jego propsów
func HeroBanner(id string, p HeroBannerProps, a *Action) Component {
return Component{Type: "HERO_BANNER", ID: id, Props: p, Action: a}
}
func AlertMessage(id string, p AlertMessageProps) Component {
return Component{Type: "ALERT_MESSAGE", ID: id, Props: p}
}
type Screen struct {
ScreenID string `json:"screenId"`
SchemaVersion int `json:"schemaVersion"`
Components []Component `json:"components"`
}
Handler BFF pyta dwa serwisy równolegle i daje im łącznie 300 ms. Serwis, który nie zdąży, nie blokuje ekranu: jego sekcja po prostu się nie pojawi. To tzw. łagodna degradacja (graceful degradation), którą SDUI daje niemal za darmo, bo ekran i tak jest listą niezależnych klocków:
func homeScreen(w http.ResponseWriter, r *http.Request) {
ctx, cancel := context.WithTimeout(r.Context(), 300*time.Millisecond)
defer cancel()
var (
wg sync.WaitGroup
hero *Component
alert *Component
)
wg.Add(2)
go func() {
defer wg.Done()
hero = fetchCampaignBanner(ctx) // np. serwis marketingu
}()
go func() {
defer wg.Done()
alert = fetchMaintenanceAlert(ctx) // np. serwis statusu
}()
wg.Wait()
components := []Component{}
for _, c := range []*Component{hero, alert} {
if c != nil { // serwis nie zdążył: pomijamy sekcję, ekran i tak się wyświetli
components = append(components, *c)
}
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(Screen{ScreenID: "home", SchemaVersion: 2, Components: components})
}
func fetchMaintenanceAlert(ctx context.Context) *Component {
select {
case <-time.After(50 * time.Millisecond): // symulacja wywołania innego serwisu
c := AlertMessage("alert_maintenance", AlertMessageProps{
Intent: IntentWarning,
Message: "Dziś w nocy sklep może działać wolniej z powodu prac technicznych.",
Dismissible: true,
})
return &c
case <-ctx.Done():
return nil
}
}
fetchCampaignBanner wygląda analogicznie i zwraca HeroBanner(...). Rejestracja handlera to jedna linia: http.HandleFunc("GET /api/screens/home", homeScreen) (wzorce z metodą HTTP działają od Go 1.22).
Słabość tego podejścia w Go: Props any nie pilnuje, czy ktoś nie zbuduje Component ręcznie z niepasującymi propsami. Dlatego konstruktory powinny być jedyną drogą tworzenia klocków, a test kontraktu (np. walidacja wygenerowanego JSON-a względem wspólnego JSON Schema) powinien działać w CI.
Czy SDUI to tylko aplikacje mobilne? Headless CMS i web
Nie. SDUI zyskało popularność w aplikacjach mobilnych, bo pozwala zmienić ekran bez czekania na przegląd aktualizacji w App Store i Google Play i bez zmuszania użytkowników do aktualizacji. Na webie ten argument jest słabszy, bo deploy frontendu i tak trwa minuty. Mimo to ten sam wzorzec jest na webie codziennością, tylko pod inną nazwą: strony budowane z bloków w headless CMS.
Redakcja układa stronę w panelu z dostępnych bloków (np. baner, galeria, formularz), a CMS wystawia tę strukturę jako JSON. Frontend ma Component Mapper, który zamienia bloki na komponenty. Różnica jest taka, że układ ustala człowiek w panelu, a nie logika backendu.
W Strapi takie bloki to dynamic zones. Każdy element ma pole __component z nazwą w formacie kategoria.nazwa i to ono pełni rolę type:
{
"blocks": [
{ "__component": "blocks.hero-banner", "id": 1, "title": "Zimowa wyprzedaż" },
{ "__component": "blocks.newsletter-form", "id": 2, "title": "Zapisz się" }
]
}
Najczęstszy problem: obrazki i zagnieżdżone komponenty w strefie dynamicznej nie przychodzą w odpowiedzi. REST API Strapi domyślnie nie dołącza relacji, mediów, komponentów ani stref dynamicznych. populate=blocks zwraca tylko proste pola pierwszego poziomu, a do mediów konkretnego bloku trzeba użyć składni on, osobno dla każdego typu komponentu:
/api/pages?populate[blocks][on][blocks.hero-banner][populate]=image&populate[blocks][on][blocks.newsletter-form][populate]=*
Składnię potwierdza dokumentacja Strapi (sekcja Populate & Select w REST API). Przy bardziej złożonych zapytaniach wygodniej zbudować je biblioteką qs niż ręcznie.
W mapperze zmienia się tylko klucz: zamiast componentMap[block.type] używasz componentMap[block.__component], a nazwy w mapie to "blocks.hero-banner" itd. Często prościej jest jednak przemapować odpowiedź CMS-a do własnego kontraktu (type, id, props) w jednej funkcji. Wtedy renderer nie zależy od konkretnego CMS-a, a zmiana Strapi na inny system dotyka jednego pliku.
Gdzie SDUI jest używane w praktyce?
| Gdzie | Jak to wygląda |
|---|---|
| Aplikacje mobilne dużych firm | Airbnb opisało publicznie swój system Ghost Platform: ekrany składane z sekcji, które definiuje backend, wspólne dla webu, iOS i Androida |
| Headless CMS (Strapi, Contentful, Storyblok, Sanity) | strefy dynamiczne lub bloki układane przez redakcję, renderowane przez Component Mapper |
| Wagtail (Django) | StreamField zapisuje treść jako listę bloków; w API każdy blok ma type, value i id |
| Dash (Python) | układ aplikacji opisany w Pythonie trafia do przeglądarki jako drzewo komponentów React z type, namespace i props |
| FastUI (Python) | biblioteka twórcy Pydantic, w której FastAPI zwraca komponenty, a gotowy frontend React je rysuje; repozytorium jest dziś zarchiwizowane, więc traktuj ją jako przykład idei, nie wybór do nowego projektu |
| Panele administracyjne i narzędzia wewnętrzne | ekrany generowane z konfiguracji (np. formularze z JSON Schema) |
Streamlit działa w podobnym duchu, choć bez JSON-owego kontraktu: skrypt w Pythonie opisuje interfejs, a gotowy frontend w przeglądarce go rysuje.
Jak wersjonować kontrakt SDUI, żeby nie zepsuć starszych wersji aplikacji?
Na webie wszyscy użytkownicy mają tę samą wersję frontendu. W aplikacji mobilnej część osób ma wersję sprzed roku i nie da się jej zaktualizować z serwera. To największe wyzwanie SDUI, bo backend wysyła ekran do klientów, które znają różne zestawy komponentów.
Zasady, które działają:
| Zasada | Dlaczego |
|---|---|
| Klient pomija nieznane typy i niepoprawne klocki | stary klient nie wywraca się na nowym komponencie (patrz parseScreen wyżej) |
| Klient mówi, co zna (nagłówek z listą komponentów lub wersja aplikacji) | serwer może pominąć klocek albo wysłać zamiennik, np. prosty baner zamiast nowej karuzeli |
Nowe pola w props są opcjonalne | stary klient je zignoruje, nowy z nich skorzysta |
| Nigdy nie zmieniaj znaczenia istniejącego pola ani typu | HERO_BANNER z innymi propsami to nowy typ, np. HERO_BANNER_V2 |
schemaVersion zmieniasz tylko przy zmianach łamiących kontrakt | klient może wtedy pokazać komunikat „zaktualizuj aplikację” zamiast pustego ekranu |
| Ekran ma wersję awaryjną | przy błędzie API klient pokazuje ostatnią zapisaną odpowiedź lub ekran wbudowany w aplikację |
W przykładzie z FastAPI nagłówek X-SDUI-Components realizuje drugą zasadę w najprostszej formie: serwer odfiltrowuje klocki, których klient nie zna. W większym systemie zamiast listy komponentów częściej wysyła się wersję aplikacji, a serwer ma tabelę „od której wersji klient obsługuje który komponent”.
Co jeszcze backendowiec powinien wiedzieć o design systemie?
Nawet bez SDUI design system wpływa na to, jak projektuje się API. Kilka punktów styku, o które warto zadbać:
- Stany jako enumy. Komponenty mają skończoną listę stanów (
success,warning,error,empty,disabled). API, które zwracastatus: "CRITICAL"zamiast hex-a czy przypadkowego słowa, mapuje się na nie bez zgadywania. - Jednolity format błędów. Design system określa, jak aplikacja pokazuje błędy (toast, modal, komunikat przy polu). Backend powinien zwracać błędy zawsze w tym samym kształcie, np. według RFC 9457 (Problem Details for HTTP APIs, następca RFC 7807), z kodem błędu i informacją, którego pola dotyczy.
- Metadane dla tabel i list. Komponent tabeli potrzebuje
totalCount, informacji o następnej stronie i dostępnych filtrach. Jeśli API ich nie zwraca, frontend musi je zgadywać albo pobierać osobno. - Tokeny w aplikacjach dla wielu klientów (white-labeling). W SaaS, gdzie każda firma ma własną markę, backend przechowuje w bazie podstawowe tokeny klienta (kolory, logo, zaokrąglenia) i serwuje je frontendowi, który podstawia je pod zmienne CSS.
- Wspólne nazewnictwo. Jeśli w design systemie element to
UserProfileCard, nie nazywaj odpowiedzi APICustomerPanelResponse. Ta sama idea stoi za wspólnym językiem (ubiquitous language) z Domain-Driven Design: jedna nazwa na jedno pojęcie, w kodzie i w rozmowach.
Kiedy SDUI się opłaca, a kiedy to przerost formy?
SDUI rozwiązuje konkretny problem: interfejs musi zmieniać się szybciej, niż pozwala na to cykl wydawniczy klienta. Jeśli tego problemu nie masz, płacisz koszty bez korzyści.
| Opłaca się | Raczej nie |
|---|---|
| aplikacja mobilna, w której ekrany zmieniają się co tydzień (promocje, kampanie, onboarding) | mały projekt z jednym frontendem i szybkim deployem |
| kilka platform (web, iOS, Android, TV) renderuje te same ekrany | ekrany z dużą ilością logiki po stronie klienta (edytory, gry, złożone formularze z walidacją zależną od pól) |
| dużo testów A/B i personalizacji układu | zespół bez dojrzałego design systemu |
| strony budowane przez marketing z gotowych bloków | brak osoby, która pilnuje kontraktu i jego wersji |
Koszty, o których rzadko się mówi:
- Debugowanie jest trudniejsze. „Czemu ten baner jest na górze?” Odpowiedź leży w logice serwera, a nie w kodzie ekranu. Logowanie, który wariant i jakie klocki dostał użytkownik, jest obowiązkowe.
- Kontrakt staje się publicznym API. Każdy typ komponentu i każde pole trzeba utrzymywać tak długo, jak istnieją klienci, którzy go używają.
- Kusi, żeby przenieść do JSON-a logikę. Więcej o tej pułapce poniżej.
- Wydajność i tryb offline. Ekran wymaga odpowiedzi serwera, zanim cokolwiek się pokaże. Potrzebujesz cache i ekranu awaryjnego.
Rozsądny kompromis to SDUI tylko dla ekranów, które często zmienia biznes (strona główna, kampanie, onboarding), i klasyczne API dla ekranów z logiką (koszyk, płatność, ustawienia konta). Nie musisz przepisywać całej aplikacji, żeby skorzystać z tego podejścia.
Jakie 3 pytania zadać przed wprowadzeniem SDUI?
Zanim zaczniesz przepisywać ekrany, odpowiedz zespołowo na trzy pytania:
- Czy ten ekran zmienia się częściej, niż wydajecie aplikację? Jeśli strona główna zmienia się raz na kwartał, a deploy trwa kilka minut, SDUI niczego nie przyspieszy.
- Czy macie design system z ustalonymi nazwami komponentów i ich propsów? Jeśli
Cardw Figmie, w kodzie i w rozmowach znaczy trzy różne rzeczy, kontrakt SDUI tylko utrwali ten chaos. - Czy ktoś odpowiada za kontrakt i jego wersje? Kontrakt SDUI to API, z którego korzystają wszystkie klienty. Bez właściciela szybko obrasta w niespójne typy i pola, których nikt nie odważy się usunąć.
Jeśli choć na jedno pytanie odpowiedź brzmi „nie”, zostań przy klasycznym API. Wrócisz do SDUI, gdy problem z tempem zmian stanie się realny.
Dlaczego logika w JSON-ie to pułapka?
Typowy scenariusz wygląda tak. Na początku backend wysyła prosty baner. Potem pojawia się prośba: „pokaż go tylko zalogowanym”. Ktoś dodaje pole:
{
"type": "HERO_BANNER",
"id": "hero_winter",
"visibleIf": { "field": "user.isLoggedIn", "equals": true },
"props": { "title": "Zimowa wyprzedaż" }
}
Po kilku tygodniach pojawia się „i tylko, jeśli koszyk jest pusty”, więc visibleIf dostaje and i or. Potem „cena z rabatem, jeśli użytkownik ma kartę lojalnościową”, więc w kontrakcie lądują wyrażenia arytmetyczne. Każdy klient (web, iOS, Android) musi mieć własny interpreter tego mini-języka, każdy interpretuje go trochę inaczej, a błędy wychodzą dopiero u użytkowników.
Zasada, która tego unika: warunki liczy serwer, klient dostaje wynik. Serwer wie, czy użytkownik jest zalogowany i co ma w koszyku, więc po prostu nie dołącza baneru do odpowiedzi albo od razu wysyła gotową cenę "71,20 zł". Jedyne warunki, które zostają po stronie klienta, to te, które zależą od stanu znanego tylko klientowi (np. czy pole formularza jest wypełnione). Te obsługuje kod komponentu, a nie kontrakt.
Jeśli zauważysz, że kontrakt dostaje pola typu visibleIf, expression czy script, to sygnał, żeby zatrzymać się i przenieść tę decyzję na serwer.
Co zapamiętać?
- SDUI to API, które zwraca opis ekranu (komponenty, propsy, akcje), a nie same dane.
- Bez design systemu nie ma SDUI:
typeto nazwa komponentu, a wygląd przekazujesz rolami i enumami, nie kolorami. - Waliduj kontrakt po obu stronach (Zod na froncie, Pydantic lub struktury Go na backendzie) i pomijaj pojedyncze błędne klocki, zamiast odrzucać cały ekran.
- Stabilne
idklocka jest obowiązkowe: od niego zależą klucze w React, analityka i podmiana klocka po akcji. - Wersjonuj ostrożnie: nowe pola opcjonalne, nowe znaczenie to nowy typ, klient mówi serwerowi, co zna.
- Stosuj SDUI tam, gdzie interfejs zmienia się szybciej niż cykl wydawniczy, a nie wszędzie.
Jeśli chcesz zbudować taki projekt w praktyce, z design systemem, typowanym kontraktem API i code review, zobacz naukę frontendu z mentorem.


