Welcome to Ztack, the full-stack web framework that allows you to build robust and efficient web applications entirely in Zig. This guide will walk you through setting up your environment, building th
Welcome to Ztack, the full-stack web framework that allows you to build robust and efficient web applications entirely in Zig. This guide will walk you through setting up your environment, building the provided examples, and creating a basic Ztack server application.
For a general overview of Ztack's features and philosophy, please refer to the Ztack - Full Stack Zig Web Framework Overview page.
Before you begin, ensure you have:
First, you need to clone the Ztack repository to your local machine:
Once inside the ztack directory, you can build all the provided examples and the core framework components. Ztack uses the zig build system for project management.
These commands will compile the various targets defined in the build.zig file.
zig build router will start a server demonstrating basic HTTP routing.zig build improved will launch a more comprehensive example showcasing HTML builders, event delegation, and streaming HTML rendering.You can typically access these examples in your web browser at http://localhost:8080 (or a similar address displayed in your terminal after running the command).
Let's create a basic Ztack application that serves a simple "Hello, Ztack!" page. We'll use the "Simple Server" code directly from the Ztack README.
For this simple example, you can create a new file named my_server.zig within the ztack directory, or in a new src subdirectory if you prefer. For simplicity, let's assume my_server.zig in the root.
Open my_server.zig and paste the following Zig code:
Let's break down the key parts of this simple Ztack application:
Imports (const std = @import("std"); etc.):
std: The Zig standard library, providing fundamental utilities like heap for memory management and net for networking.html: Ztack's module for type-safe and efficient HTML generation.router: Ztack's module for defining and dispatching HTTP routes.handleIndex Function:
GET request comes in for the root path (/), the router will call this function.HttpMethod, path, and body as arguments, though they are marked unused (_ = method;) as this simple example doesn't depend on them for its response.var doc = html.HtmlDocument.init(...): Creates an instance of the HTML document builder. The allocator is used internally by the builder to manage memory for the generated HTML. Here, std.heap.page_allocator is used for simplicity.const page = &[_]html.Element{ ... }: This array defines the structure of your HTML page using Ztack's declarative HTML builder functions (e.g., html.h1, html.button_data, html.text).return try doc.build(&[_]html.Element{}, page);: This line tells the document builder to construct the HTML based on the defined elements and return it as a string ([]const u8).main Function:
Zig requires explicit memory management. A
GeneralPurposeAllocator is initialized to handle dynamic memory allocations for the application. The defer statement ensures that the allocator's resources are properly released when main exits, preventing memory leaks.An instance of the
router.Router is created, passing in our allocator. This router will be responsible for mapping incoming requests to their corresponding handler functions. defer app.deinit() ensures its internal resources are freed.This is where you define your application's routes. Here, we're telling the router: "When you receive a
GET request for the root path (/), call the handleIndex function."// ... listen and dispatch ... highlights where the actual HTTP server listening and request dispatching logic would go. This snippet from the README focuses on the router and HTML builder setup, omitting the boilerplate server code. For a complete, runnable server, you would typically integrate std.net.Server and dispatch requests using app.dispatch().To compile and run this specific my_server.zig file, you would typically use zig build-exe or similar, but the build.zig of the Ztack project doesn't include my_server.zig by default.
For now, the easiest way to see the routing and HTML building in action is to stick to the provided examples. The router_server.zig example (zig build router) provides a full, runnable server demonstrating how the router and handlers interact with actual network I/O.
This my_server.zig example primarily serves to illustrate how to define a handler and register a route using Ztack's API. To turn this into a truly runnable web server, you'd integrate it into a build.zig file and add the networking code shown in src/examples/router_server.zig.
Now that you have a foundational understanding of Ztack's structure and how to define basic routes and HTML, you can delve deeper:
src/examples/router_server.zig and src/examples/improved_counter.zig for complete, working Ztack applications. These will show you how to integrate the server listening logic with the router.html.zig module for efficient and type-safe HTML generation.