Zig Starter

A production-ready Zig starter template for building libraries and CLI applications. This template integrates essential Zig utilities and follows best practices for project structure, dependency management, testing, and version control.

Features

Modern Dependency Management - Uses Pantry for managing local and remote dependencies
CLI Framework - zig-cli with type-safe argument parsing and interactive prompts
Configuration Management - zig-config with multi-source loading and type safety
Error Handling - zig-error-handling with Rust-inspired Result types
Testing Framework - zig-test-framework with Jest/Vitest-style syntax
Version Management - zig-bump for automatic version bumping and changelog generation
Production Ready - Optimized build configuration for multiple platforms

Requirements

Zig 0.15.1 or later
Pantry package manager
Git

Quick Start

1. Clone or Copy This Template

# Copy to a new project
cp -r zig-starter my-new-project
cd my-new-project

2. Install Dependencies

# Using Pantry package manager
pantry install

# This will install:
# - zig-cli
# - zig-config
# - zig-error-handling
# - zig-test-framework
# - zig-bump

3. Build the Project

# Build the project
zig build

# Or using package.jsonc scripts
pantry run build

4. Run Tests

# Run all tests
zig build test

# Or using package.jsonc scripts
pantry run test

5. Run the Application

# Run with default command
zig build run

# Run with arguments
zig build run -- --help
zig build run -- config --show
zig build run -- process input.txt -o output.txt

Project Structure

zig-starter/
├── build.zig              # Build configuration
├── build.zig.zon          # Zig package manifest
├── package.jsonc          # Pantry dependency configuration
├── README.md              # This file
├── CHANGELOG.md           # Auto-generated changelog (via zig-bump)
├── src/
│   ├── main.zig          # CLI entry point
│   └── lib.zig           # Core library functionality
└── zig-out/              # Build output (generated)
    ├── bin/
    └── lib/

Configuration

package.jsonc

The package.jsonc file manages your dependencies and build configuration:

{
  "name": "zig-starter",
  "version": "0.1.0",

  "dependencies": {
    // Local development paths (fast iteration)
    "zig-cli": "~/Code/zig-cli",
    "zig-config": "~/Code/zig-config",
    // ... etc
  },

  "scripts": {
    "build": "zig build",
    "test": "zig build test",
    "run": "zig build run"
  }
}

Switching to Production Dependencies

For production releases, update package.jsonc to use GitHub repositories:

{
  "dependencies": {
    // Production (GitHub releases)
    "stacksjs/zig-cli": "latest",
    "stacksjs/zig-config": "latest",
    "stacksjs/zig-error-handling": "latest",
    "stacksjs/zig-test-framework": "latest",
    "stacksjs/zig-bump": "latest"
  }
}

Usage Examples

Basic Library Usage

const std = @import("std");
const starter = @import("starter");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var lib = try starter.StarterLib.init(allocator);
    defer lib.deinit();

    const result = lib.processData("Hello, Zig!");
    if (result.isOk()) {
        const data = result.unwrap();
        defer allocator.free(data);
        std.debug.print("Processed: {s}\n", .{data});
    }
}

CLI Command Usage

# Show version
./zig-out/bin/zig-starter --version

# Show configuration
./zig-out/bin/zig-starter config --show

# Process a file
./zig-out/bin/zig-starter process input.txt -o output.txt

# Enable verbose output
./zig-out/bin/zig-starter --verbose process data.txt

Error Handling with Result Type

const errors = @import("zig-error-handling");

fn riskyOperation() errors.Result(i32, error{Failed}) {
    if (some_condition) {
        return errors.Result(i32, error{Failed}).ok(42);
    } else {
        return errors.Result(i32, error{Failed}).err(error.Failed);
    }
}

// Usage
const result = riskyOperation();
if (result.isOk()) {
    std.debug.print("Success: {}\n", .{result.unwrap()});
} else {
    std.debug.print("Error: {}\n", .{result.unwrapErr()});
}

Writing Tests

const testing = @import("zig-test-framework");

test "example test" {
    const value = 42;
    try testing.expect(value == 42);
    try testing.expectEqual(42, value);
}

test "string comparison" {
    const str = "hello";
    try testing.expectEqualStrings("hello", str);
}

test "error handling" {
    try testing.expectError(error.EmptyData, someFunction());
}

Development Workflow

Adding New Features

Create feature branch
```
git checkout -b feature/my-feature
```

Implement and test

# Edit source files
vim src/lib.zig

# Run tests continuously
zig build test

Commit changes

git add .
git commit -m "feat: add new feature"

Version Management

This template uses zig-bump for version management:

# Bump patch version (0.1.0 → 0.1.1)
pantry run bump:patch

# Bump minor version (0.1.0 → 0.2.0)
pantry run bump:minor

# Bump major version (0.1.0 → 1.0.0)
pantry run bump:major

# These commands will:
# 1. Update version in build.zig.zon
# 2. Generate CHANGELOG.md entry
# 3. Create git commit
# 4. Create git tag
# 5. Push to remote (if configured)

Manual Version Bump

# Without pantry scripts
bump patch --changelog
bump minor --changelog --no-push
bump major --dry-run

Build Options

Optimize for Release

# Build with optimizations
zig build -Doptimize=ReleaseFast

# Build for multiple targets
zig build -Dtarget=x86_64-linux
zig build -Dtarget=aarch64-macos
zig build -Dtarget=x86_64-windows

Build Library Only

zig build install
# Output: zig-out/lib/libzig-starter.a

Build Executable Only

zig build install
# Output: zig-out/bin/zig-starter

Testing

Run All Tests

zig build test

Run Specific Test

# Filter by test name
zig build test --test-filter "processData"

Test with Coverage (if enabled)

zig build test -- --coverage

Customization

1. Update Project Name

Edit build.zig.zon:

.{
    .name = "my-project",
    .version = "0.1.0",
    // ...
}

Edit package.jsonc:

{
  "name": "my-project",
  // ...
}

2. Add Dependencies

Edit package.jsonc:

{
  "dependencies": {
    "my-new-dep": "~/Code/my-new-dep"
  }
}

Then run:

pantry install

Update build.zig to add the module:

const my_dep_mod = b.addModule("my-dep", .{
    .root_source_file = b.path("../my-new-dep/src/root.zig"),
    .target = target,
});

// Add to imports
lib_mod.addImport("my-dep", my_dep_mod);

3. Add CLI Commands

Edit src/main.zig:

var new_cmd = try app.addCommand("mycommand", .{
    .description = "My new command",
    .handler = myCommandHandler,
});

try new_cmd.addArgument("arg", .{
    .description = "Command argument",
    .required = true,
});

Deployment

Building for Production

# Update dependencies to use GitHub releases
# Edit package.jsonc to reference GitHub repos

# Install production dependencies
pantry install --frozen-lockfile

# Build optimized binary
zig build -Doptimize=ReleaseFast

# Binary is in: zig-out/bin/zig-starter

Cross-Compilation

# Linux
zig build -Dtarget=x86_64-linux -Doptimize=ReleaseFast

# macOS (Intel)
zig build -Dtarget=x86_64-macos -Doptimize=ReleaseFast

# macOS (Apple Silicon)
zig build -Dtarget=aarch64-macos -Doptimize=ReleaseFast

# Windows
zig build -Dtarget=x86_64-windows -Doptimize=ReleaseFast

Troubleshooting

Build Errors

# Clean build cache
rm -rf zig-cache zig-out

# Rebuild
zig build

Dependency Issues

# Reinstall dependencies
rm -rf .pantry node_modules
pantry install

# Check dependency status
pantry list

Module Not Found

Ensure build.zig has the correct relative paths to dependencies:

.root_source_file = b.path("../zig-cli/src/root.zig"),

Contributing

Fork the repository
Create your feature branch
Commit your changes (follow conventional commits)
Push to the branch
Create a Pull Request

License

MIT License - feel free to use this template for any project.

Resources

Support

For issues, questions, or contributions, please open an issue in the repository.

Happy Coding with Zig! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.zig		build.zig
build.zig.full		build.zig.full
build.zig.zon		build.zig.zon
package.jsonc		package.jsonc

Uh oh!

License

Uh oh!

zig-utils/zig-starter

Folders and files

Latest commit

History

Repository files navigation

Zig Starter

Features

Requirements

Quick Start

1. Clone or Copy This Template

2. Install Dependencies

3. Build the Project

4. Run Tests

5. Run the Application

Project Structure

Configuration

package.jsonc

Switching to Production Dependencies

Usage Examples

Basic Library Usage

CLI Command Usage

Error Handling with Result Type

Writing Tests

Development Workflow

Adding New Features

Version Management

Manual Version Bump

Build Options

Optimize for Release

Build Library Only

Build Executable Only

Testing

Run All Tests

Run Specific Test

Test with Coverage (if enabled)

Customization

1. Update Project Name

2. Add Dependencies

3. Add CLI Commands

Deployment

Building for Production

Cross-Compilation

Troubleshooting

Build Errors

Dependency Issues

Module Not Found

Contributing

License

Resources

Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Languages