🚀 NimbleStack

A Modern Go + Templ + Tailwind CSS Starter Template with HTMX, Alpine.js & SQLC

NimbleStack is a lightning-fast, full-stack starter template designed for developers who want to build modern web apps with minimal boilerplate. It features SQLite + SQLC for embedded database magic! ✨

---

🌟 Features

• Go Backend: Blazing-fast API and server logic with Go.
• SQLite + SQLC: Type-safe database access with a single-file embedded database.
• Templ Templates: Clean, type-safe HTML templating.
• Tailwind CSS: JIT-compiled, utility-first CSS.
• HTMX + Alpine.js: Dynamic UI without JavaScript fatigue.
• Docker Containerization: Run NimbleStack anywhere with a single binary, thanks to our multi-stage Dockerfile.

---

🛠️ Why NimbleStack?

• Zero Deployment Hassle: Package your app as a single binary with an embedded SQLite database.
• Full-Stack Type Safety: Enjoy a seamless SQLC → Go → Templ workflow.
• Local Development Bliss: No need to install or configure separate database servers.
• Portability with Docker: Our provided Dockerfile lets you build a container that runs consistently on any platform—whether on your local machine, in the cloud, or in CI/CD pipelines.
• Modern UI/UX: Use HTMX and Alpine.js to create responsive, reactive interfaces without heavy frameworks.

---

🚀 Getting Started

Prerequisites

• Go: 1.21+
• Node.js: 18+ & pnpm
• Tailwind CSS: Although this template uses Tailwind for styling, please note that the Tailwind CLI is installed via the AUR. Users on other platforms will need to set up their own method for building the CSS.
• SQLC

Installation

1. Clone the repository:

   git clone https://github.com/Stan-breaks/nimblestack.git
   cd nimblestack

2. Install dependencies:

   pnpm install
   go mod tidy
   go get modernc.org/sqlite  # SQLite driver

3. Generate code:

   templ generate ./views/
   sqlc generate

4. Start the server:

   go run main.go

5. (Optional) Build and run with Docker/Podman:

   The included Dockerfile lets you containerize NimbleStack. For example, to build and run using Podman:

   podman build -t nimblestack .
   podman run -p 8080:8080 nimblestack

---

📂 Project Structure

nimblestack/
├── database/         # Generated Go models
├── sqlc/             # SQLC schema and queries
├── public/           # Static assets (CSS, images, etc.)
├── views/            # Templ components
├── handlers/         # HTTP handlers
├── Dockerfile        # Multi-stage Dockerfile for containerization
├── sqlc.yaml         # SQLC configuration
└── main.go           # Server entry point

---

🔌 Database Workflow (SQLite + SQLC)

1. Create Migration

db/migrations/001_users.up.sql:

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  name TEXT NOT NULL,
  email TEXT NOT NULL UNIQUE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2. Write Queries

db/query/users.sql:

-- name: CreateUser :one
INSERT INTO users (name, email)
VALUES (?, ?)
RETURNING *;

-- name: GetUserByEmail :one
SELECT * FROM users
WHERE email = ?;

3. Generate Code

sqlc generate

4. Use in Handler

handlers/users.go:

func CreateUserHandler(w http.ResponseWriter, r *http.Request) {
    // Get DB connection
    db, _ := sql.Open("sqlite3", ".sqlite.db")
    defer db.Close()

    queries := db.NewQueries()

    // Type-safe database operation
    user, err := queries.CreateUser(r.Context(), db.CreateUserParams{
        Name:  r.FormValue("name"),
        Email: r.FormValue("email"),
    })

    if err != nil {
        http.Error(w, "Database error", 500)
        return
    }

    // Render response with Templ
    components.UserCard(user).Render(r.Context(), w)
}

---

📈 Roadmap

• Add SQLite migration tool.
• HTMX CRUD example with optimistic UI.
• SQLite connection pool benchmarks.
• ARM64 build support.

---

📚 Learning Resources

• SQLC SQLite Guide
• Modern SQLite Driver Docs
• HTMX Patterns

---

Docker & Portability

The provided Dockerfile enables you to package NimbleStack into a container that runs anywhere—whether on local development machines, cloud servers, or within CI/CD pipelines. This offers several advantages:

• Consistency: The container ensures the environment (OS, dependencies, configuration) remains the same across different deployments.
• Portability: You can run your containerized app on any platform that supports Docker or Podman.
• Ease of Deployment: Single binary + container means minimal configuration and fewer moving parts.

---

License

MIT © [Stan-breaks] | Made with ❤️ for fast web apps