$ go install github.com/Elagoht/collage/cmd/collage@latest
$ collage new <project_name>
$ cd <project_name>
$ go mod tidy
$ collage devA 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.
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)Delivery and operations
minimizercompressbundleopti-imagedeployprometheusotelhealthjobsaccesslog
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
Getting started
- IntroductionWhy collage exists, what it is built on, what it leaves to you, and when it is the right tool.
- InstallationInstall Go and the collage CLI, scaffold a project with collage new, and run it under collage dev.
- Your first pageA hands-on tutorial: build a recipe page with a layout, a data handler and a template, add a second fragment in a slot, and export every recipe to static files.
- Update part of a pageA hands-on tutorial with no plugins: a shopping list whose items are a fragment at its own URL, updated in place by a form and a few lines of JavaScript.
Core concepts
- Pages and layoutsWhat a page is: its layouts and content, who may see it, the paths that reach it, how it is cached, what it shows when it fails, and what registration does.
- Fragments and slotsFragments, the slots they expose, what happens when one fails, and slots filled from content at render time.
- Data handlersHow a fragment fetches its data: the handler contract, dependency tags, 404s, concurrency, the render context, timeouts, and checking templates against data.
- TemplatesWhere templates live, how they are loaded and embedded, how they reload in development, slots, built-in and custom functions, and escaping.
Building a site
- CachingHow collage caches rendered pages and the data they are made from, and how it knows what to throw away.
- Forms and actionsHandling form posts, fetch calls and webhooks with actions, and protecting them from request forgery.
- Links and localesServing a site in several languages, and linking between pages by name so links follow them in every locale.
- Head and SEOTitles, meta tags, stylesheets and structured data declared by the fragment that knows them, placed by the layout.
- Static assetsServing stylesheets, scripts, images and downloads from a directory or an embedded file system, with URLs that can be cached for a year.
- Documents: sitemaps, feeds, robots.txtRoutes that answer with bytes instead of HTML — sitemaps, feeds, robots.txt, JSON — cached and invalidated like pages.
- Middleware and your own APIStandard net/http middleware with app.Use, cache keys that depend on a header with collage.Vary, and your own http.Handler with app.Handle.
- PreviewsShow editors unpublished drafts on the real site, without the cache serving them the published page or anyone else the draft.
Shipping
- Static exportRender the site to static files with collage export — what is written, what is skipped and why, dynamic paths, and publishing to a static host.
- DeploymentBuild the binary, run it in a container or under systemd, set what production needs, and put it behind TLS.
- SecurityWhat collage does against request forgery, open redirects, path tricks, cache leaks and oversized bodies — and what is left to you.
- TestingTest the real application through app.Handler() with pkg/collagetest, a client that keeps cookies and submits forms like a browser: pages, forms, the export.
Extending
- Using pluginsWhat a plugin can do, how to register and configure one, and the forty-six published plugins, grouped by what they are for.
- Writing a pluginThe plugin contract, what Host and ConfigHost expose, every hook and what it may change, and a complete plugin with its tests.
- Writing a plugin: the repository contractWhat a repository needs for collage plugin add to install it — a name, a manifest, a New with no setup, a release tag — and how collage plugin check proves it.
Reference
- The collage CLIEvery command of the collage CLI, from new, add and dev to plugin, ai, completion and man, with its flags and exactly what it runs.
- ConfigurationEvery field of collage.Config and its sub-structs, with its default and what validation checks.
- Template functionsEvery built-in template function — slot, hoist, asset, the URL functions, json, arithmetic, strings and lists — with its signature and an example.
- ErrorsEvery exported error value in collage, grouped by where it comes from, with what it means and what to do about it.