pugz/docs/DEMO_QUICKSTART.md

Demo Server - Quick Start Guide

Prerequisites

# From pugz root directory
cd /path/to/pugz
zig build

Running the Demo

cd examples/demo
zig build run

The server will start on http://localhost:8081

Available Routes

Route	Description
GET /	Home page with hero section and featured products
GET /products	All products listing
GET /products/:id	Individual product detail page
GET /cart	Shopping cart (with sample items)
GET /about	About page with company info
GET /include-demo	Demonstrates include directive
GET /simple	Simple compiled template demo

Features Demonstrated

1. Template Inheritance

• Uses extends and block for layout system
• views/layouts/main.pug - Main layout
• Pages extend the layout and override blocks

2. Includes

• views/partials/header.pug - Site header with navigation
• views/partials/footer.pug - Site footer
• Demonstrates code reuse

3. Mixins

• views/mixins/products.pug - Product card component
• views/mixins/buttons.pug - Reusable button styles
• Shows component-based design

4. Data Binding

• Dynamic content from Zig structs
• Type-safe data passing
• HTML escaping by default

5. Iteration

• Product listings with each loops
• Cart items iteration
• Dynamic list rendering

6. Conditionals

• Show/hide based on data
• Feature flags
• User state handling

Testing

Quick Test

# Start server
cd examples/demo
./zig-out/bin/demo &

# Test endpoints
curl http://localhost:8081/
curl http://localhost:8081/products
curl http://localhost:8081/about

# Stop server
killall demo

All Routes Test

cd examples/demo
./zig-out/bin/demo &
DEMO_PID=$!
sleep 1

# Test all routes
for route in / /products /products/1 /cart /about /include-demo /simple; do
  echo "Testing: $route"
  curl -s http://localhost:8081$route | grep -o "<title>.*</title>"
done

kill $DEMO_PID

Project Structure

demo/
├── build.zig           # Build configuration
├── build.zig.zon       # Dependencies
├── src/
│   └── main.zig        # Server implementation
└── views/
    ├── layouts/
    │   └── main.pug    # Main layout
    ├── partials/
    │   ├── header.pug  # Site header
    │   └── footer.pug  # Site footer
    ├── mixins/
    │   ├── products.pug
    │   └── buttons.pug
    └── pages/
        ├── home.pug
        ├── products.pug
        ├── product-detail.pug
        ├── cart.pug
        ├── about.pug
        └── include-demo.pug

Code Walkthrough

Server Setup (main.zig)

// Initialize ViewEngine
const engine = pugz.ViewEngine.init(.{
    .views_dir = "views",
    .extension = ".pug",
});

// Create server
var server = try httpz.Server(*App).init(allocator, .{
    .port = 8081,
}, .{
    .view = engine,
});

// Add routes
server.router().get("/", homePage);
server.router().get("/products", productsPage);
server.router().get("/about", aboutPage);

Rendering Templates

fn homePage(app: *App, _: *httpz.Request, res: *httpz.Response) !void {
    const html = app.view.render(res.arena, "pages/home", .{
        .siteName = "Pugz Store",
        .featured = &products[0..3],
    }) catch |err| {
        return renderError(res, err);
    };
    
    res.content_type = .HTML;
    res.body = html;
}

Common Issues

Port Already in Use

If you see "AddressInUse" error:

# Find and kill the process
lsof -ti:8081 | xargs kill

# Or use a different port (edit main.zig):
.port = 8082,  // Change from 8081

Views Not Found

Make sure you're running from the demo directory:

cd examples/demo  # Important!
zig build run

Memory Leaks

The demo uses ArenaAllocator per request - all memory is freed when the response is sent:

// res.arena is automatically freed after response
const html = app.view.render(res.arena, ...);

Performance

Runtime Mode (Default)

• Templates parsed on every request
• Full Pug feature support
• Great for development

Compiled Mode (Optional)

• Pre-compile templates to Zig functions
• 10-100x faster
• See DEMO_SERVER.md for setup

Next Steps

1. Modify templates - Edit files in views/ and refresh browser
2. Add new routes - Follow the pattern in main.zig
3. Create new pages - Add .pug files in views/pages/
4. Build your app - Use this demo as a starting point

Full Documentation

See DEMO_SERVER.md for complete documentation including:

• Compiled templates setup
• Production deployment
• Advanced features
• Troubleshooting

---

Quick Start Complete! 🚀

Server running at: http://localhost:8081