Patch Protocol

Enabling

Pass patches to the Vite plugin:

import { defineConfig } from "vite";
import marko from "@marko/run/vite";

export default defineConfig({
  plugins: [marko({ patches: true })],
});

The option compiles every template to answer navigations with patches and installs the client router on each page. Each build answers only its own pages, so a page loaded from an earlier deploy navigates with full document loads until it reloads.

Navigations

The router handles a click on a link to another route of the application, and the submission of a GET or POST form to one. It leaves a navigation to the browser when the link or form targets another origin or window, when a modifier key is held, for a download link, for a link to a fragment of the current page, and for a link or form with rel="external".

A handled navigation requests the route with the same URL, method and body the browser would send, then applies the response as it streams:

• The document title and the route's +meta update with the page.
• A POST that redirects applies the page it redirects to, and the history entry follows the final URL.
• Back and forward restore the scroll position of the entry being visited. A new entry starts at the top, or at the element its fragment names.
• A repeated submission of the same form while the first is in flight is not sent again.

Whenever a response cannot apply as a patch (a response that is not a patch, a network failure, or a build the page does not match), the router loads the URL as a document instead, so a navigation always ends on the page the server rendered. Routes such as +404 and +500 render as patches like any other page.

Shared Layouts

A layout can own state while the page inside it changes. Consider a shop with a cart drawer in the layout:

<let/cartOpen=false>
<header>
  <a href="/">Shop</a>
  <button onClick() {
    cartOpen = !cartOpen;
  }>
    Cart (${$global.cart.count})
  </button>
</header>
<if=cartOpen>
  <aside class="cart-drawer">
    <for|item| of=$global.cart.items by=(item) => item.id>
      <p>${item.name}</p>
    </for>
  </aside>
</if>
<main>
  <${input.content}/>
</main>

export interface Input {
  content: Marko.Body;
}

<let/cartOpen=false>

<header>
  <a href="/">Shop</a>
  <button onClick() { cartOpen = !cartOpen }>
    Cart (${$global.cart.count})
  </button>
</header>

<if=cartOpen>
  <aside class="cart-drawer">
    <for|item| of=$global.cart.items by=(item) => item.id>
      <p>${item.name}</p>
    </for>
  </aside>
</if>

<main>
  <${input.content}/>
</main>

let/cartOpen=false
header
  a href="/" -- Shop
  button onClick() {
    cartOpen = !cartOpen;
  } -- Cart (${$global.cart.count})
if=cartOpen
  aside class="cart-drawer"
    for|item| of=($global.cart.items) by=(item) => item.id
      p -- ${item.name}
main
  ${input.content}

export interface Input {
  content: Marko.Body;
}

let/cartOpen=false

header
  a href="/" -- Shop
  button onClick() { cartOpen = !cartOpen } -- Cart (${$global.cart.count})

if=cartOpen
  aside class="cart-drawer"
    for|item| of=$global.cart.items by=(item) => item.id
      p -- ${item.name}

main
  ${input.content}

<h1>Products</h1>
<a href="/about">About us</a>

h1 -- Products
a href="/about" -- About us

With the drawer open, following the link to /about replaces the page inside <main> and updates the cart count from the server's response. The drawer stays open, because cartOpen belongs to the layout, which is patched in place rather than rendered again. Without persisted pages, the link loads a new document and the drawer closes.

Client State

State belongs to the page, as it does in client rendering. A component rendered in the same place before and after a navigation keeps its <let> values, the text typed into its fields and the elements a script attached to it. Consider a search page:

<form method="get">
  <input name="q" value=$global.search.q>
  <button>Search</button>
</form>

<let/expanded=false>
<button onClick() { expanded = !expanded }>Filters</button>
<if=expanded>
  <filter-panel/>
</if>

form method="get"
  input name="q" value=$global.search.q
  button -- Search

let/expanded=false
button onClick() { expanded = !expanded } -- Filters
if=expanded
  filter-panel

Submitting the form patches the results in, while the open filter panel stays open and the search field keeps its text. The field's value= is the value it renders with. Without a valueChange= handler, what the user typed stays, exactly as when the value changes in the browser.

Scripts and Effects

Effects follow the same rules as in client rendering. A <script> runs when the content that contains it is created, runs again when a value it reads changes, and its $signal aborts before each rerun and when its content is removed. Content a navigation creates runs its effects once the patch applies.

Markup inserted by a navigation is created by the client, so an inline <html-script> in it is added to the page without running.

Content Security Policy

The client evaluates each part of a patch as JavaScript. A page served with a Content Security Policy needs 'unsafe-eval' in its script-src for its navigations to patch. Without it, each navigation loads the document.

Supported Pages

Patches apply to the pages Marko Run renders from route files. Templates rendered some other way, such as a template embedded inside another document, answer every navigation with a document.

Templates must use the Tags API.

Page Size

Every page includes the client router and the part of the patch runtime its templates use, including pages that otherwise ship no JavaScript. Its HTML also carries the markers and values a later patch updates, so a document is larger than the same page built without patches.

A patch is always smaller than the document it replaces: values the page already renders from its own state are left out, and shells the page has already received are not sent again.

Contributors

Helpful? You can thank these awesome people! You can also edit this doc if you see any issues or want to improve it.

• LuLaValva
• You?