Zbudowaliśmy webowy konfigurator aplikacji AI Agent — 75+ opcji, pobierz jako ZIP

Narzędzia CLI są potężne. Ale bywają też przytłaczające.

Nasz full-stack-ai-agent-template ma ponad 75 opcji konfiguracyjnych. Baza danych, uwierzytelnianie, framework AI, zadania w tle, cache, rate limiting, observability, Docker, Kubernetes, CI/CD, frontend, i18n — lista jest długa. CLI świetnie sprawdza się dla programistów, którzy już wiedzą, czego chcą. Dla wszystkich pozostałych to ściana flag i promptów.

Dlatego zbudowaliśmy webowy konfigurator. 9-krokowy wizualny kreator, który przeprowadza przez każdą opcję, waliduje zależności w czasie rzeczywistym i generuje gotowy do produkcji projekt jako plik ZIP — pobierany bezpośrednio z przeglądarki.

Co ciekawe: nie ma tu żadnego serwera. Wszystko — renderowanie szablonów, walidacja zależności, generowanie ZIP — dzieje się po stronie klienta.

9-krokowy kreator

Konfigurator przeprowadza przez konfigurację projektu w logicznych grupach:

Informacje o projekcie — nazwa, opis, autor, wersja Pythona
Baza danych — PostgreSQL, MongoDB, SQLite lub brak + wybór ORM
Uwierzytelnianie — JWT, API Key, oba lub brak + OAuth
AI Agent — wybór frameworka (Pydantic AI, LangChain, LangGraph, CrewAI, DeepAgents), dostawca LLM, streaming przez WebSocket, persystencja konwersacji
Infrastruktura — zadania w tle (Celery, TaskIQ, ARQ), Redis, cache, rate limiting, Logfire, Sentry, Prometheus
Integracje — WebSockets, storage plików, webhooks, CORS, panel administracyjny
Narzędzia deweloperskie — Docker, Kubernetes, pytest, pre-commit, CI/CD (GitHub Actions, GitLab CI)
Frontend — Next.js lub brak, i18n
Podsumowanie — karty podsumowania, plakietki funkcji, opcje pobierania

Każdy krok waliduje w czasie rzeczywistym. Wybierz PostgreSQL w kroku 2 → pojawiają się opcje ORM. Włącz Logfire w kroku 5 → stają się dostępne pod-funkcje instrumentacji bazy danych, Redis i Celery.

3 presety: od zera do pobrania w 10 sekund

Większość użytkowników nie chce konfigurować 75 opcji. Chcą punktu wyjścia:

Preset	Co dostajesz	Zastosowanie
Minimal	Bez bazy danych, bez auth, bez Dockera, bez CI	Szybkie prototypy, nauka FastAPI
Production	PostgreSQL, JWT, Redis, cache, rate limiting, Sentry, Prometheus, Docker, K8s, GitHub Actions	Backend gotowy do wdrożenia
AI Agent	PostgreSQL, JWT, Redis, Pydantic AI, WebSockets, persystencja konwersacji, Docker, GitHub Actions	Aplikacje chatbot/agent AI

Kliknij preset → wszystkie 75+ pól się wypełnia → przejdź do Podsumowania → Pobierz ZIP. Mniej niż 10 sekund od strony głównej do pobranego projektu.

Wyzwanie techniczne: renderowanie szablonów po stronie klienta

Tu zaczęło robić się ciekawie. Nasze szablony używają składni Jinja2 (przez pythonowy cookiecutter). Musieliśmy renderować je w przeglądarce bez serwera.

Krok 1: Zbundlowanie 246 szablonów w czasie budowania

Skrypt budowania przechodzi przez katalog szablonów i serializuje każdy plik do pojedynczego JSON-a:

const SLUG_DIR = join(TEMPLATE_ROOT, "{{cookiecutter.project_slug}}");
// Walks all files, skips binaries (.png, .pyc, .so)
// Output: public/templates.json (~1.1 MB)

Wynik: templates.json — słownik, gdzie klucze to względne ścieżki plików, a wartości to stringi z zawartością szablonów. Pobierany raz na sesję, cachowany w pamięci.

Krok 2: Nunjucks jako przeglądarkowy Jinja2

Nunjucks to silnik szablonów JavaScript z kompatybilną składnią Jinja2. Te same {% if %}, {% for %}, {{ variable }} — nasze pythonowe szablony renderują się identycznie w przeglądarce.

const env = new nunjucks.Environment(undefined, {
  autoescape: false,
  throwOnUndefined: false,
  trimBlocks: true,
  lstripBlocks: true,
});

const rendered = env.renderString(templateContent, { cookiecutter: ctx });

Krok 3: Inteligentna logika wykluczeń

Nie każdy plik pasuje do każdego projektu. Jeśli wyłączysz AI agenta, wszystkie pliki frameworka agentowego zostają wykluczone. Jeśli wybierzesz Pydantic AI, pliki LangChain zostają usunięte. Logika wykluczeń odzwierciedla nasz pythonowy post_gen_project.py.

Krok 4: Generowanie ZIP przez JSZip

Po renderowaniu i filtrowaniu JSZip pakuje wszystko z kompresją DEFLATE:

const blob = await zip.generateAsync({
  type: "blob",
  compression: "DEFLATE",
});
downloadBlob(blob, `${projectName}.zip`);

Cały pipeline — pobranie bundla, renderowanie 246 szablonów, wykluczenie nieużywanych plików, wygenerowanie ZIP — zajmuje 1-2 sekundy.

Automatyczna naprawa zależności

Niektóre opcje mają zależności. Zamiast pokazywać błędy walidacji, konfigurator naprawia je automatycznie:

const needsRedis =
  cur.enable_caching ||
  (cur.enable_rate_limiting && cur.rate_limit_storage === "redis") ||
  (cur.background_tasks !== "none") ||
  (cur.enable_logfire && cur.logfire_features.redis);

if (needsRedis && !cur.enable_redis) {
  form.setValue("enable_redis", true);
}

Włącz cache → Redis cicho się aktywuje. Wyłącz bazę danych → instrumentacja bazy danych w Logfire cicho się wyłącza. Użytkownik nigdy nie widzi nieprawidłowego stanu.

Walidacja Zod: ten sam schemat, inny runtime

CLI używa modeli Pydantic do walidacji. Web używa Zod. Oba wymuszają te same ograniczenia:

Nazwa projektu: ^[a-z][a-z0-9_]*$
Porty: 1024-65535
14 typów enum (baza danych, metoda auth, framework AI, itd.)
28 przełączników boolean
Warunkowa widoczność między polami (12 funkcji widoczności)

Opcje pobierania

Krok Podsumowania oferuje trzy sposoby na pobranie projektu:

Plik ZIP — pełne pobranie projektu (główne CTA)
JSON — cookiecutter.json, który możesz zaimportować do CLI
Komenda CLI — jednolinijkowa komenda skopiowana do schowka

Oznacza to, że webowy konfigurator i CLI są wymienne. Skonfiguruj wizualnie, wyeksportuj jako JSON, użyj w CLI. Lub odwrotnie.

Kluczowe wnioski

Renderowanie po stronie klienta eliminuje koszty serwera — brak backendu do hostowania, brak API do utrzymania, skaluje się do nieskończonej liczby użytkowników za darmo
Nunjucks to Jinja2 dla przeglądarki — jeśli twoje szablony używają składni Jinja2, możesz renderować je po stronie klienta z niemal zerowym nakładem portowania
Automatyczna naprawa > błędy walidacji — ciche włączenie Redis gdy cache jest aktywowany to lepszy UX niż wyświetlanie “Redis jest wymagany do cache”
Presety + stopniowe ujawnianie — 3 presety obsługują 80% użytkowników, 9-krokowy kreator służy pozostałym 20%
Bundlowanie w czasie budowania — serializacja 246 plików do jednego JSON-a pozwala uniknąć 246 żądań HTTP

Wypróbuj: Webowy konfigurator — lub zainstaluj przez CLI: pip install fastapi-fullstack

full-stack-ai-agent-template na GitHubie