Przejdź do treści
dvnt.io

Open source · licencja MIT · plugin Payload CMS

Edycja strony tam, gdzie ją widać.

Klient klika w to, co widzi na stronie, i od razu edytuje właściwe pole — zamiast szukać go w formularzu obok podglądu.

Kod na GitHubieZobacz, jak działa

payload-visual-editorMIT
Wersja
1.1.0
Zgodność
Payload 3.x
pnpm add @digitalvantage/payload-visual-editor @digitalvantage/payload-visual-editor-react

Przejęliśmy rozwój pluginu z zachowaniem licencji MIT i informacji o autorach.

// Wyzwanie

Formularz po lewej, podgląd po prawej

Oddajemy klientom strony na Payload CMS, a klient ma je potem zmieniać sam. W Payload wygląda to tak: po lewej formularz, po prawej podgląd strony. Strona składa się z bloków — nagłówek, sekcja z ofertą, galeria, opinie, kontakt — a w formularzu każdy blok to rozwijany wiersz z polami. Żeby poprawić jedno zdanie, klient musi najpierw znaleźć, który wiersz i które pole odpowiada temu, co widzi na stronie.

Nie tylko my to widzimy. Autor jednego z pluginów do Payload pisze, że przy wielu blokach redaktor „gubi się, który wiersz odpowiada czemu na stronie”, a podgląd „pokazuje tylko wynik”. Agencje porównujące systemy piszą wprost, że Payload bez dopracowania „wygląda dla marketingowca jak edytor bazy danych”. Oficjalny edytor wizualny Payload jest zapowiedziany, ale tylko w planie Enterprise i wciąż jako „wkrótce”.

Dla nas to nie jest kwestia wygody. Budujemy platformę, na której stoją strony naszych klientów: jedna instalacja Payload, a w niej osobne strony z własnymi domenami, wyglądem i modułami branżowymi — na przykład dla kancelarii czy dewelopera. Jeden z celów platformy brzmi wprost: edytor wizualny, w którym klient sam zmienia treść. Jeśli klient nie umie sam poprawić strony, dzwoni przy każdej zmianie albo przestaje ją aktualizować.

Plan zakładał do tego Pucka — osobny kreator stron, który zapisuje treść we własnym formacie. To oznaczało drugi model danych obok Payload i osobną drogę dla wersji roboczych, historii zmian i języków. Obok istniał plugin open source od zespołu what-digital, który robił to, czego potrzebowaliśmy, na zwykłych polach Payload. Miał jednak jednego autora, ostatnią zmianę w lipcu 2026 roku, dokładał skrypt na stronie każdemu odwiedzającemu i brakowało mu cofania zmian, obsługi klawiaturą, polskiej wersji i testów poza przeglądarką Chrome.

// Decyzja

Zamiast budować — przejąć

Pod koniec października zdecydowaliśmy: zamiast Pucka bierzemy ten plugin i przejmujemy jego rozwój, z zachowaniem licencji MIT i informacji o autorach. Z planu wypadł prawie cały etap budowy edytora.

Klient klika w to, co widzi. Dwuklik w nagłówek otwiera obok niego okienko z tym jednym polem. Dwuklik w cały blok — okienko ze wszystkimi jego polami, łącznie ze zdjęciem i tekstem z formatowaniem. To są te same pola co w panelu, więc obowiązują te same zasady: walidacja, uprawnienia, wersje robocze, publikacja. Na platformie tak samo edytuje się wpis na blogu, osobę z zespołu, obszar praktyki kancelarii czy lokal w inwestycji. Nagłówek i stopka strony otwierają się z boku, bez wychodzenia z edytowanej podstrony.

Bloki przestawia się na stronie. Przy każdym bloku są przyciski: dodaj nad lub pod, skopiuj, usuń, przeciągnij w inne miejsce. Każdą taką zmianę można cofnąć przyciskiem albo skrótem Ctrl+Z — także usunięcie, razem z całą treścią bloku. Kto woli klawiaturę, przechodzi między blokami strzałkami i przesuwa je bez myszy. Użytkownik, który ma tylko prawo podglądu, nie zobaczy przycisków, których nie może użyć. Panel mówi po polsku.

Treść zostaje tam, gdzie była. Edytor nie ma własnego formatu danych. Pracuje na blokach i polach, które strona już ma, więc wdrożenie nie wymaga przenoszenia treści. Strona oznacza, który fragment odpowiada któremu polu, jawnymi atrybutami w kodzie — bez ukrywania znaczników w samym tekście, co w innych systemach potrafi psuć adresy i dane dla wyszukiwarek. Na platformie te oznaczenia pojawiają się tylko w podglądzie w panelu, więc odwiedzający dostaje czystą stronę, bez dodatkowego kodu edytora.

Wygląd strony nie rozbije edytora. Każda strona na platformie ma własne kolory, fonty i style. Ramki i przyciski edytora są od nich odcięte, więc nawet agresywny arkusz CSS ich nie ukryje ani nie przestawi. Sprawdzamy to na specjalnie „wrogich” stronach testowych w trzech przeglądarkach.

Wydanie dopiero po teście na czystej instalacji. Przed każdą wersją pakujemy plugin dokładnie tak, jak trafi do npm, instalujemy w pustej aplikacji Payload — w najstarszej wspieranej wersji i w najnowszej — i przechodzimy test w przeglądarce. Potem wersja kandydująca trafia najpierw na naszą platformę i naszą stronę, a dopiero później do wszystkich. Po drodze ten proces złapał błędy, których nie widać przy szybkim przeklikaniu: zaznaczenie, które po przestawieniu bloku zostawało przy starym miejscu i działało na sąsiedni blok, albo anulowane dodawanie bloku, na które strona czekała minutę.

Co potrafi

  • Edycja w okienku przy treściDwuklik w pole albo blok otwiera obok klikniętego miejsca te same pola, które są w panelu
  • Operacje na blokach na stronieDodaj nad lub pod, skopiuj, usuń, przeciągnij; „Dodaj blok” w pustej sekcji
  • Cofnij i ponówPrzyciski i Ctrl/⌘+Z na stronie i w panelu — także usunięcie bloku razem z treścią
  • Obsługa klawiaturąStrzałki między blokami, Enter edytuje, Alt+strzałka przesuwa blok
  • Edycja innych dokumentówNagłówek i stopka strony otwierają się z boku, bez wychodzenia z podstrony
  • Pełnoekranowy edytorPasek z zapisem, publikacją, wyborem języka i panelem bloków
  • UprawnieniaUżytkownik tylko do podglądu nie widzi przycisków, których nie może użyć
  • TłumaczeniaTeksty panelu i edytora przez i18n Payload, polska wersja w zestawie
  • DiagnostykaOstrzeżenia w trybie deweloperskim o oznaczeniach niepasujących do schematu
  • Oba tryby Live PreviewPodgląd po stronie klienta i odświeżanie renderowane na serwerze
// payload.config.ts
import { visualEditor } from '@digitalvantage/payload-visual-editor'

export default buildConfig({
  // ...
  plugins: [visualEditor()],
})

Jak wygląda

Okienko przy klikniętym miejscu.

  • Schemat działania edytora wizualnego: plugin w panelu Payload, formularz dokumentu, Live Preview i SDK na stronie

    Jak to działa: plugin w panelu Payload rozmawia ze stroną w podglądzie, a dane dokumentu płyną zwykłą drogą Live Preview

  • Publiczne repozytorium payload-visual-editor na GitHubie, fork projektu what-digital

    Kod jest publiczny na GitHubie, na licencji MIT — rozwijamy go jako fork projektu what-digital

Dwuklik od miejsca na stronie do pola, które je zmienia
1
Rodzajów treści edytowanych na stronie
8
Migracji treści przy wdrożeniu
0
Znaczników edytora w kodzie strony dla odwiedzających
0

Klient, który ma stronę na naszej platformie, poprawia ją, klikając w to, co widzi. Nie musi wiedzieć, jak nazywa się pole ani w którym wierszu formularza jest blok. Zmienia tekst w okienku przy nagłówku, przestawia sekcje przeciąganiem, a pomyłkę cofa skrótem. Zapis, wersje i publikacja działają tak jak wcześniej.

Dla nas zmienia się to, co oddajemy klientom. Zamiast instrukcji, w którym bloku i której zakładce szukać pola — strona, którą edytuje się jak stronę. Edytor obejmuje osiem rodzajów treści: strony i moduły branżowe, które mają własną podstronę. Nie musieliśmy budować osobnego kreatora ani drugiego modelu danych.

Plugin jest darmowy, na licencji MIT, a wersja 1.1.0 jest dostępna na npm dla każdego, kto buduje na Payload. Działa na naszej platformie i na digitalvantage.pl. Każde wydanie przechodzi 36 scenariuszy w silnikach Chrome, Firefoksa i Safari oraz test na czystej instalacji w dwóch wersjach Payload.

Czego jeszcze nie wiemy: domeny pierwszych klientów dopiero przenosimy na platformę, więc nie mamy jeszcze danych, ile czasu edytor oszczędza klientowi ani jak często z niego korzysta. Następny krok to zgodność z Payload 4.

Kod jest otwarty. Cały kod pluginu, testy i historia zmian są publiczne na GitHubie, na licencji MIT. Każdy może go przejrzeć, użyć we własnym projekcie i zgłosić poprawkę.

Technologie

  • Payload CMS 3
  • React 19
  • TypeScript
  • Shadow DOM
  • Next.js 15 / 16
  • pnpm workspaces
  • Vitest
  • Playwright
  • publint + attw
  • Payload Live Preview
  • Payload i18n
  • Lexical
  • Next.js (App Router)
  • Dowolny front przez SDK bez zależności

Zespół

Konrad Barejko — dvnt — rozwój od wersji 1.0.2

what-digital — Autor oryginalnego pluginu (do wersji 1.0.1, MIT)

// współtwórz

Kod jest publiczny

Zgłoś błąd, zaproponuj funkcję albo wyślij pull request. Używasz Payload u siebie? Pomożemy wdrożyć.

Otwórz repozytorium →

15 minut. Zero sprzedaży.

Budujesz na Payload CMS i potrzebujesz pluginu albo wsparcia? W 15 minut powiemy, co da się zrobić.