Luat sites

Luat renders Studio content with Svelte-like templates and server code in Lua. There is no JavaScript framework and no Node toolchain: pages render on the server, and the Studio editor edits them inline exactly as it does a SvelteKit or Astro site. The rendering contract is the same; the adapter is the Luat package @maravilla/studio, published on the Luat package registry.

What the package gives a site:

• Content reads on the branch the request may read, with references resolved by the database (RESOLVE(properties, 2)) — images inside fragments included.
• Drafts and preview: an author’s unsaved draft is shown only inside their signed preview session; one route file serves the editor’s preview handshake.
• Inline editing in the Studio editor: the data-studio-* annotations, the editor mount and live re-render after every edit.
• Personalisation: block variants, whole-page variations, managed segments, persona preview.
• The standard blocks as Luat components (Hero, Prose, Heading, Figure, Section, FeatureGrid, Variants), rich text in both storage formats, and a registry for your own blocks.

The example site is examples/site-luat in the Studio repository; it renders the same pages as examples/site-svelte.

1. The project

maravilla init acme-site        # choose "Luat"
cd acme-site
maravilla luat add @maravilla/studio

maravilla luat add records the dependency in luat.toml, pins it in luat.lock and installs it into .luat/ (not committed). maravilla build and maravilla dev install packages on their own.

2. Configuration

# .env (production: project variables in the console)
RAISINDB_URL=https://<your-raisindb>
RAISINDB_API_KEY=<server-side key>
STUDIO_REPO=studio
STUDIO_WORKSPACE=stories
STUDIO_STORY=/acme                 # the story's root
STUDIO_WORKING_BRANCH=main
STUDIO_LIVE_BRANCH=main            # `publish` once the site reads published content
STUDIO_PREVIEW_SECRET=<long random string>
STUDIO_LOCALES=en,de,fr
STUDIO_DEFAULT_LOCALE=en

The names are the ones the JavaScript sites use. maravilla dev reaches a RaisinDB on your machine directly (RAISINDB_URL=http://localhost:8080).

3. Routes

Three route files carry the whole site:

-- src/routes/[...path]/+page.server.lua   (and src/routes/+page.server.lua for "/")
local studio = require("@maravilla/studio")
function load(ctx) return studio.new():load_page(ctx) end

-- src/routes/studio-preview/[action]/+server.lua   (the editor's preview handshake)
local studio = require("@maravilla/studio")
function GET(ctx) return studio.new():preview(ctx) end
function POST(ctx) return studio.new():preview(ctx) end

-- src/routes/studio-media/[...path]/+server.lua    (stable image and file URLs)
local studio = require("@maravilla/studio")
function GET(ctx) return studio.new():media(ctx) end

load_page resolves the URL to a page of the story (locales as /de/… or ?lang=), picks the page variation, overlays the author’s draft in a preview session, resolves block variants for the visitor and sends the right response headers — framing for the editor, noindex and no caching for previews, Vary for geo-personalised pages. An unknown path is a 404.

4. Deploy

Push to main: the Luat starter’s pipeline runs maravilla build, which installs @maravilla/studio from the lockfile and compiles it into the site. Set the variables of step 2 on the project, with STUDIO_LIVE_BRANCH=publish once the site should show published content only.

Next: templates and blocks, then editing and personalisation. For the Luat language itself, see the Luat documentation.