Skip to main content

​
What is Go Template?

Go Template is an opinionated, production-ready project template designed specifically for scraper, bot, and service workloads. It provides a complete foundation for building robust Go applications without starting from scratch. Instead of spending days configuring infrastructure and boilerplate, you can scaffold a new project in seconds and start building your domain logic immediately.

​
Who is it for?

Go Template is ideal for developers building:
  • Web scrapers that need TLS fingerprinting and proxy rotation
  • Bot applications requiring concurrent task processing
  • API services with PostgreSQL persistence
  • Background workers with retry logic and state management
Whether you’re building a one-off scraper or a production service, Go Template provides the infrastructure you need without the complexity you don’t.

​
Key Features

​
Production-Ready Infrastructure

TLS Fingerprinting

HTTP client with customizable TLS/HTTP2 fingerprints to mimic real browsers

Bounded Concurrency

Worker pool primitives for controlled parallel processing via errgroup

Exponential Backoff

Retry logic with jitter for graceful transient error recovery

PostgreSQL Support

Type-safe database queries with sqlc and goose migrations

​
Optional Packages

Go Template uses an interactive setup wizard that lets you choose exactly what you need:
  • HTTP Client - TLS fingerprinting, proxy support, cookie management, HTTP/2 control
  • Worker Pool - Bounded concurrency primitives for parallel processing
  • Retry - Exponential backoff with full jitter
  • State - File-backed JSON persistence with cross-platform file locking
  • Cycle - Thread-safe round-robin file rotator
  • Fake Data - Helpers for generating test data

​
Docker & Development

  • Multi-stage Dockerfile optimized for Alpine Linux
  • Docker Compose with hot reload via docker compose watch
  • Local development with make dev
  • Full test suite with race detector

​
Database Management

  • PostgreSQL connection pooling with pgx
  • Type-safe queries generated by sqlc
  • Migration management via goose
  • Optional: Use Docker postgres or bring your own database

​
Project Philosophy

Batteries included, but removable. Go Template ships with everything you might need, but the interactive setup wizard strips out what you don’t. This means:
  • No unused dependencies in your final project
  • Clean codebase tailored to your needs
  • Production-ready defaults that you can customize
Real-world tested. Every package in Go Template solves actual problems encountered in production scraping and bot workloads: 
// Example: Retry with exponential backoff
err := retry.Do(ctx, func(ctx context.Context) error {
    return client.Do(req)
}, retry.WithMaxAttempts(5))

// Example: Bounded concurrency worker pool
err := worker.Run(ctx, urls, 10, func(ctx context.Context, url string) error {
    return scrapeURL(url)
})
Go Template requires Go 1.26+ for the latest generics and standard library features.

​
What’s Included

The template provides a complete project structure: 
go-template/
├── cmd/template/       # Application entrypoint
├── pkg/
│   ├── client/         # HTTP client with TLS fingerprinting
│   ├── worker/         # Bounded concurrency primitives
│   ├── retry/          # Exponential backoff with jitter
│   ├── state/          # File-backed JSON persistence
│   ├── cycle/          # Round-robin file rotator
│   ├── db/             # PostgreSQL with sqlc queries
│   ├── env/            # Environment variable loader
│   ├── log/            # Structured logging with slog
│   └── template/       # Your domain logic (replace this)
├── Dockerfile          # Multi-stage build
├── compose.yaml        # Docker Compose with watch mode
└── Makefile            # Common development tasks

​
Quick Example

Here’s what a typical service looks like with Go Template: 
package main

import (
    "context"
    "log/slog"
    
    "github.com/you/myproject/pkg/db"
    "github.com/you/myproject/pkg/env"
    _ "github.com/you/myproject/pkg/log"
)

func main() {
    ctx := context.Background()
    
    // Load configuration from .env
    config, err := env.New()
    if err != nil {
        slog.ErrorContext(ctx, "config error", "error", err)
        return
    }
    
    // Connect to PostgreSQL
    database, err := db.New(ctx, config.DatabaseURL)
    if err != nil {
        slog.ErrorContext(ctx, "database error", "error", err)
        return
    }
    defer database.Close()
    
    // Your domain logic here
}

​
Next Steps

Quick Start

Scaffold your first project in under 2 minutes

Setup Guide

Learn about the interactive setup wizard

Build docs developers (and LLMs) love

Get started for freeTalk to us