$ go install github.com/Elagoht/collage/cmd/collage@latest
$ collage new <project_name>
$ cd <project_name>
$ go mod tidy
$ collage dev

A Go framework for the server-rendered web

HTML from the server, fragment by fragment.

Pages rendered on the server from fragments, cached by what they depend on, and updated one part at a time. In one Go binary.

A landing page is not a single-page app

A product page, a landing page, a site of a few pages with little to click: none of them needs a JavaScript server runtime, a client framework and a hydration step. Such a runtime is slower than Go and keeps more memory and disk busy on the server, and a client framework sends the browser a program to build the HTML it could have received. collage sends the HTML.

A typical stack — a JavaScript bundle, hydration, an SSR framework, a dependency tree and a JavaScript runtime — beside collage: HTML, a few lines of JavaScript and one Go binary.a typical stackJS bundlehydrationSSR frameworkdependency treeJS runtimecollageHTMLa few lines of JSone Go binaryno runtime to install

Fragments, not components

A page is a layout around fragments. Each fragment is a template and a function that fetches its own data; siblings fetch at once, and the page still comes out in order. Open one at a URL of its own with WithFragmentPath, and three lines of fetch replace just that part of the page: the server's state, rendered on the server, one fragment at a time.

fetch, XHR, server-sent events and WebSockets were made for exactly this. When you would rather not write the script, a plugin refreshes fragments on an interval or when the server pushes, and can morph them in place. elagoht/live

collage.NewPage("search").
  	WithLayouts(layout).
  	WithContent(searchPage).
  	WithPath("en", "/search").
  	WithFragmentPath("en", "/search/results", results).
  	Build()
input.addEventListener("input", async () => {
    const res = await fetch("/search/results?q=" + encodeURIComponent(input.value));
    document.querySelector("#results").outerHTML = await res.text();
  });

Layouts and slots

A layout leaves a slot for the page's content, and a fragment can leave slots of its own. Fill them with fragments and collage assembles the page.

Cached by what it depends on

Every page and every cached value carries the tags of what it was built from: post:hello, author:ada. InvalidateTags marks the pages that used a tag stale and renders them again in the background, keeping the old page to fall back on. PurgeTags removes them outright, for what must never be shown again. Everything else stays cached.

app.InvalidateTags(ctx, "author:ada")
  app.PurgeTags(ctx, "user:42")

Invalidate by tag

A page remembers what it was built from. Invalidate one tag and only the pages that used it are rendered again; the rest stay as they are.

Middleware and plugins, as many as you need

Where a framework gives you one middleware file and every concern a request needs is chained inside it by hand, collage's app.Use takes any func(http.Handler) http.Handler, as many times as you like, and each plugin brings its own middleware, in the order you list them. The core stays small: sessions, spam protection, live updates, SEO and metrics are plugins. Forty-five are published, and one of your own is a Go type with the hooks it needs.

app, err := collage.New(&collage.Config{
  	Plugins: []collage.Plugin{
  		session.New(session.Options{KeyEnv: "SESSION_KEY"}),
  		honeypot.New(honeypot.Options{KeyEnv: "HONEYPOT_KEY"}),
  		client.New(),
  		live.New(live.Options{}),
  	},
  })

  app.Use(requestID)
  app.Use(auditLog)

Still Writing Go

There is no second language and no second process. Your data layer is your Go code: the database, the queue, the external API. An API or a service you already have mounts on collage's own mux with app.Handle, beside the pages and behind the same middleware. One project, one binary.

api := http.NewServeMux()
  api.HandleFunc("GET /api/users/{id}", users.Get)
  api.HandleFunc("POST /api/users", users.Create)

  app.Handle("/api/", api)

A small core, for sites and web apps

collage is not batteries-included, and it says what it leaves to you. What it has is what a server-rendered front end needs, so a multi-user, role-based web app is as much at home as a landing page: sessions and roles, forms that cannot be forged, spam protection, parts of the page that update live.

In the core

  • Fragments and fragment paths
  • Actions, with forgery protection
  • Cache, tags, invalidate and purge
  • Guards for private pages and roles
  • Locale URLs and links by name
  • Static export

With a plugin

  • Sessions
  • Honeypot and validation
  • Flash messages
  • Live fragments over SSE or WebSocket
  • OAuth, basic auth, rate limits

Not included

  • A backend: business rules and services are your Go code
  • An ORM
  • Migrations
  • A database layer: that is your Go code

How it works

Fetch at once

Every fragment has its own data handler. Sibling fragments fetch together, and the HTML still comes out in order.

Stream fragments live

With collage-live, invalidating a tag re-renders every open fragment that used it and pushes it to the browser over one stream. Only that part changes. For example CPU usage of the server here.

Save and see

collage dev reloads the browser when a template changes and rebuilds when Go does. A failed render shows its file and line in the browser.

Build, export, serve

collage build makes one static binary, the site's whole server, for any operating system and architecture. collage export writes the site as static files, and collage serve serves them the way a static host would.

The guide