Go + HTMX Template

This is a template repository that comes with everything you need to build a Web Application using Go (templ) and HTMX.

The template comes with a basic structure of using a SQL DB (sqlc), E2E testing (playwright), and styling (tailwindcss).

Getting Started

In the top right, select the dropdown Use this template and select Create a new repository.

Once cloned, run the update_module.sh script to change the module to your module name.

./update_module "github.com/me/my-new-module"

Install the following before generating files

• sqlc
• templ

Then you can proceed to generate sqlc and templ files

sqlc generate
make generate-templ

Then you can upgrade your module dependencies with

go get -u
go mod tidy

Run

There are a couple builtin ways to run the application - using air or the Makefile helper commands.

Prerequisites

• Install templ
• Install sqlc
• Install tailwindcss CLI
• Install air

air

air has been configured with the file .air.toml to allow live reloading of the application when a file changes.

To run, install air

go install github.com/cosmtrek/air@latest

Then simply run the command

air

Makefile

Air will detect changes to templ, css, and sql files and rebuild and run the application. You can also run with the provided Makefile. There are commands to generate templ files and tailwind output css.

# Generate and watch templ
make generate-templ-watch

# Genrate and watch tailwindcss
make generate-tailwind-watch

# Run application
make run

Technologies

A few different technologies are configured to help getting off the ground easier.

• sqlc for database layer
  • Stubbed to use SQLite
  • This can be easily swapped with sqlx
  • The script upgrade_sqlc.sh is available to upgrade GitHub Workflow files to latest sqlc version
• Tailwind CSS for styling
  • Output is generated with the CLI
• templ for creating HTML
  • The script upgrade_templ.sh is available to make upgrading easier
• HTMX for HTML interaction
  • The script upgrade_htmx.sh is available to make upgrading easier
  • Already included in this template
• air for live reloading of the application.
• golang migrate for DB migrations.
• playwright-go for E2E testing.

Structure

.
├── Makefile
├── components
│   ├── core
│   │   └── html.templ
│   └── home
│       └── home.templ
├── db
│   ├── db.go
│   ├── local.go
│   ├── migrations
│   │   ├── 20240407203525_init.down.sql
│   │   └── 20240407203525_init.up.sql
│   └── queries
│       └── query.sql
├── db.sqlite3
├── dist
│   ├── assets
│   │   └── js
│   │       └── [email protected]
│   └── dist.go
├── e2e
│   ├── e2e_test.go
│   ├── home_test.go
│   └── testdata
│       └── seed.sql
├── go.mod
├── go.sum
├── log
│   └── log.go
├── main.go
├── server
│   ├── handler
│   │   ├── handler.go
│   │   └── home.go
│   ├── middleware
│   │   ├── cache.go
│   │   ├── logging.go
│   │   └── middleware.go
│   ├── router
│   │   └── router.go
│   └── server.go
├── sqlc.yml
├── styles
│   └── input.css
├── tailwind.config.js
└── version
    └── version.go

Components

This is where templ files live. Anything you want to render to the user goes here. Note, all *.go files will be ignored by git (configured in .gitignore).

DB

This is the directory that sqlc generates to. Update queries.sql to build your database operations.

This project uses golang migrate for DB migrations. sqlc uses the db/migrations directory to generating DB tables. main.go calls db.Migrate(..) to automatically migrate the DB. To add migration call the following command,

migrate create -ext sql -dir db/migrations <name of migration>

This package can be easily update to use sqlx as well.

Example Connection to Turso

If you want to connect to a remote Database, like Turso, you can create a struct that implements Database.

package db

import (
	"database/sql"
	"log/slog"

	"go-htmx-template/db/queries"
	_ "github.com/tursodatabase/libsql-client-go/libsql"
)

type RemoteDB struct {
	logger  *slog.Logger
	db      *sql.DB
	queries *queries.Queries
}

var _ Database = (*RemoteDB)(nil)

func (d *RemoteDB) DB() *sql.DB {
	return d.db
}

func (d *RemoteDB) Queries() *queries.Queries {
	return d.queries
}

func (d *RemoteDB) Logger() *slog.Logger {
	return d.logger
}

func (d *RemoteDB) Close() error {
	return d.db.Close()
}

func newRemoteDB(logger *slog.Logger, name string, token string) (*RemoteDB, error) {
	db, err := sql.Open("libsql", "libsql://"+name+".turso.io?authToken="+token)
	if err != nil {
		return nil, err
	}
	return &RemoteDB{logger: logger, db: db, queries: queries.New(db)}, nil
}

Dist

This is where your assets live. Any Javascript, images, or styling needs to go in the dist/assets directory. The directory will be embedded into the application.

Note, the dist/assets/css will be ignored by git (configured in .gitignore) since the files that are written to this directory are done by the Tailwind CSS CLI. Custom styles should go in the styles/input.css file.

E2E

To test the UI, the e2e directory contains the Go tests for performing End to end testing. To run the tests, run the command

go test -v ./... -tags=e2e

The end to end tests, will start up the app, on a random port, seeding the database using the seed.sql file. Once the tests are complete, the app will be stopped.

The E2E tests use Playwright (Go) for better integration into the Go tooling.

Log

This contains helper function to create a slog.Logger. Log level and output type can be set with then environment variables LOG_LEVEL and LOG_OUTPUT. The logger will write to stdout.

Server

This contains everything related to the HTTP server. It comes with a graceful shutdown handler that handles SIGINT.

Router

This package sets up the routing for the application, such as the /assets/ path and / path. It uses the standard libraries mux for routing. You can easily swap out for other HTTP routers such as gorilla/mux.

Middleware

This package contains any middleware to configured with routes.

Handler

This package contains the handler to handle the actual routes.

Styles

This contains the input.css that the Tailwind CSS CLI uses to generate your output CSS. Update input.css with any custom CSS you need and it will be included in the output CSS.

Version

This package allows you to set a version at build time. If not set, the version defaults to dev. To set the version run the following command,

go build -o ./app -ldflags="-X version.Value=1.0.0"

See the Makefile for building the application.

Github Workflow

The repository comes with two Github workflows as well. One called ci.yml that lints and tests your code. The other called release.yml that creates a tag, GitHub Release, and attaches the Linux binary to the Release.

Note, the version of github.com/a-h/templ/cmd/templ matches the version in go.mod. If these do not match, the build will fail. When upgrading your templ version, make sure to update ci.yml and release.yml.

GoReleaser

If you need to compile for more than Linux, see GoReleaser for a better release process.