Skip to main content

Getting Started

Welcome to Luat! This guide will help you build your first web application using LUAT templating with SvelteKit-style routing.

What is Luat?​

Luat is a Svelte-inspired server-side Lua templating engine for Rust that combines:

  • LUAT Templating - Server-side rendering with Svelte-like syntax
  • SvelteKit-Style Routing - File-based routing with +page.luat and +layout.luat
  • Integrated Toolchain - Auto-configured Tailwind CSS, Sass, and TypeScript
  • Live Development - Hot reloading with file watching

Installation​

Choose your preferred installation method:

npm install -g @maravilla-labs/luat

Homebrew (macOS)​

brew install maravilla-labs/tap/luat

Shell Script (Linux/macOS)​

curl -fsSL https://raw.githubusercontent.com/maravilla-labs/luat/main/scripts/install.sh | sh

Cargo (Rust developers)​

cargo install luat-cli

Quick Start​

1. Create Your First Project​

luat init my-app
cd my-app

This creates a project with SvelteKit-style structure:

my-app/
├── luat.toml                    # Project configuration
├── src/
│   ├── app.html                 # HTML shell template
│   ├── routes/
│   │   ├── +layout.luat         # Root layout
│   │   ├── +page.luat           # Home page (/)
│   │   └── +page.server.lua     # Data loading
│   └── lib/                     # Shared Lua modules
├── static/                      # Static assets
└── public/                      # Generated assets (CSS, JS)

2. Start Development Server​

luat dev

Visit http://localhost:3000 to see your app running with live reload!

3. Create Your First Page​

Create src/routes/about/+page.luat:

<h1>About Us</h1>
<p>This is the about page.</p>
<a href="/">Back to Home</a>

Visit http://localhost:3000/about to see your new page.

4. Add Data Loading​

Create src/routes/about/+page.server.lua:

function load(ctx)
    return {
        title = "About Us",
        team = {
            { name = "Alice", role = "Developer" },
            { name = "Bob", role = "Designer" }
        }
    }
end

Update src/routes/about/+page.luat:

<h1>{props.title}</h1>

<h2>Our Team</h2>
<ul>
{#each props.team as member}
    <li>{member.name} - {member.role}</li>
{/each}
</ul>

Key Concepts​

LUAT Templates​

LUAT uses familiar Svelte-like syntax. Try editing the code below:

Loading Luat...

File-Based Routing​

Your file structure defines your URLs:

FileURL
src/routes/+page.luat/
src/routes/about/+page.luat/about
src/routes/blog/+page.luat/blog
src/routes/blog/[slug]/+page.luat/blog/:slug

Script Blocks​

Use script blocks to import components and prepare data:

<script>
    local Card = require("Card")
    local Button = require("Button")

    local title = props.title or "Default Title"
    local isActive = props.status == "active"
</script>

<Card title={title}>
    <Button variant={isActive and "primary" or "secondary"}>
        Click me
    </Button>
</Card>

HTML Shell (app.html)​

The src/app.html file provides the document structure:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>%luat.title%</title>
    <link rel="stylesheet" href="/css/tailwind.css">
    %luat.head%
</head>
<body>
    %luat.body%
</body>
</html>

CLI Commands​

CommandDescription
luat init [name]Create a new project
luat devStart development server with live reload
luat buildBuild for production
luat serveServe production build
luat watchWatch files and rebuild

Next Steps​

Now that you have a basic understanding, explore these topics:

Core Concepts​

Routing & Projects​

Advanced​

Ready to build something amazing? Continue with the LUAT Templating guide or explore the Routing documentation.