{"id":25274533,"url":"https://github.com/piszmog/go-htmx-template","last_synced_at":"2025-07-17T06:35:02.500Z","repository":{"id":221468716,"uuid":"754465357","full_name":"Piszmog/go-htmx-template","owner":"Piszmog","description":"Template for creating a Go and HTMX application","archived":false,"fork":false,"pushed_at":"2025-05-21T01:53:03.000Z","size":210,"stargazers_count":17,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-21T02:43:57.119Z","etag":null,"topics":["air","docker","golang","htmx","playwright-go","sqlc","tailwindcss","templ"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Piszmog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-02-08T05:26:37.000Z","updated_at":"2025-05-21T01:53:06.000Z","dependencies_parsed_at":"2024-04-19T02:46:55.297Z","dependency_job_id":null,"html_url":"https://github.com/Piszmog/go-htmx-template","commit_stats":null,"previous_names":["piszmog/go-htmx-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/Piszmog/go-htmx-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Piszmog%2Fgo-htmx-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Piszmog%2Fgo-htmx-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Piszmog%2Fgo-htmx-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Piszmog%2Fgo-htmx-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Piszmog","download_url":"https://codeload.github.com/Piszmog/go-htmx-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Piszmog%2Fgo-htmx-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265573597,"owners_count":23790468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air","docker","golang","htmx","playwright-go","sqlc","tailwindcss","templ"],"created_at":"2025-02-12T14:30:33.590Z","updated_at":"2025-07-17T06:35:02.482Z","avatar_url":"https://github.com/Piszmog.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go + HTMX Template\n\nThis is an _opinionated_ template repository that comes with everything you need to build a Web Application using Go (with templ) and HTMX. \n\nThe template comes with a basic structure of using a SQL DB (`sqlc`), E2E testing (playwright), and styling (tailwindcss).\n\n## Getting Started\n\nIn the top right, select the dropdown __Use this template__ and select __Create a new repository__.\n\nOnce cloned, run the `update_module.sh` script to change the module to your module name.\n\n```shell\n./update_module \"github.com/me/my-new-module\"\n```\n\nOnce ran, delete the script.\n\nThen you can upgrade your module dependencies with\n\n```shell\ngo mod tidy\ngo get -u\ngo get -u tool\n# To upgrade test dependencies, run\ngo get -u all\n```\n\nFinally, you can proceed to generate sqlc and templ files\n\n```shell\ngo tool sqlc generate\ngo tool templ generate -path ./components\n```\n\n## Run\n\n`air` is the primary way to run the applications for local development. It watches for file changes. When a file changes, it will rebuild and re-run the application.\n\nWhen the application is running, go to http://localhost:8080/\n\n### Prerequisites\n\n- Install [air](https://github.com/air-verse/air#installation)\n\n`templ`, `sqlc`, and `tailwindcss` (via [`go-tw`](https://github.com/Piszmog/go-tw)) are included as `go tool` directives. When running\nthe application for the first time, it may take a little time as `templ`, `sqlc` and `go-tw` are being downloaded and installed.\n\n### air\n\n`air` has been configured with the file `.air.toml` to allow live reloading of the application \nwhen a file changes.\n\nTo run, install `air`\n\n```shell\ngo install github.com/air-verse/air@latest\n```\n\nThen simply run the command\n\n```shell\nair\n```\n\n## Technologies\n\nA few different technologies are configured to help getting off the ground easier.\n\n- [sqlc](https://sqlc.dev/) for database layer\n  - Stubbed to use SQLite\n  - This can be easily swapped with [sqlx](https://jmoiron.github.io/sqlx/)\n- [Tailwind CSS](https://tailwindcss.com/) for styling\n  - Output is generated with the [CLI](https://tailwindcss.com/docs/installation/tailwind-cli)\n- [templ](https://templ.guide/) for creating HTML\n- [HTMX](https://htmx.org/) for HTML interaction\n  - The script `upgrade_htmx.sh` is available to make upgrading easier\n  - Already included in this template\n- [air](https://github.com/air-verse/air) for live reloading of the application.\n- [golang migrate](https://github.com/golang-migrate/migrate) for DB migrations.\n- [playwright-go](https://github.com/playwright-community/playwright-go) for E2E testing.\n\n## Structure\n\n```text\n.\n├── .air.toml\n├── .github\n│   └── workflows\n│       ├── ci.yml\n│       └── release.yml\n├── .gitignore\n├── .goreleaser.yaml\n├── Dockerfile\n├── components\n│   ├── core\n│   │   └── html.templ\n│   └── home\n│       └── home.templ\n├── db\n│   ├── db.go\n│   ├── local.go\n│   ├── migrations\n│   │   ├── 20240407203525_init.down.sql\n│   │   └── 20240407203525_init.up.sql\n│   └── queries\n│       └── query.sql\n├── dist\n│   ├── assets\n│   │   └── js\n│   │       └── htmx@2.0.4.min.js\n│   └── dist.go\n├── e2e\n│   ├── e2e_test.go\n│   ├── home_test.go\n│   └── testdata\n│       └── seed.sql\n├── go.mod\n├── go.sum\n├── log\n│   └── log.go\n├── main.go\n├── server\n│   ├── handler\n│   │   ├── handler.go\n│   │   └── home.go\n│   ├── middleware\n│   │   ├── cache.go\n│   │   ├── logging.go\n│   │   └── middleware.go\n│   ├── router\n│   │   └── router.go\n│   └── server.go\n├── sqlc.yml\n├── styles\n│   └── input.css\n├── update_module.sh\n├── upgrade_htmx.sh\n└── version\n    └── version.go\n```\n\n### Components\n\nThis is where `templ` files live. Anything you want to render to the user goes here. Note, all\n`*.go` files will be ignored by `git` (configured in `.gitignore`).\n\n### DB\n\nThis is the directory that `sqlc` generates to. Update `queries.sql` to build \nyour database operations.\n\nThis project uses [golang migrate](https://github.com/golang-migrate/migrate) for DB \nmigrations. `sqlc` uses the `db/migrations` directory to generating DB tables. `main.go` calls `db.Migrate(..)` to automatically migrate the DB. To add migration\ncall the following command,\n\n```shell\nmigrate create -ext sql -dir db/migrations \u003cname of migration\u003e\n```\n\n#### Example Connection to Turso\n\nIf you want to connect to a remote Database, like [Turso](https://turso.tech/), you can create a struct that implements `Database`.\n\n```golang\npackage db\n\nimport (\n\t\"database/sql\"\n\t\"log/slog\"\n\n\t\"go-htmx-template/db/queries\"\n\t_ \"github.com/tursodatabase/libsql-client-go/libsql\"\n)\n\ntype RemoteDB struct {\n\tlogger  *slog.Logger\n\tdb      *sql.DB\n\tqueries *queries.Queries\n}\n\nvar _ Database = (*RemoteDB)(nil)\n\nfunc (d *RemoteDB) DB() *sql.DB {\n\treturn d.db\n}\n\nfunc (d *RemoteDB) Queries() *queries.Queries {\n\treturn d.queries\n}\n\nfunc (d *RemoteDB) Logger() *slog.Logger {\n\treturn d.logger\n}\n\nfunc (d *RemoteDB) Close() error {\n\treturn d.db.Close()\n}\n\nfunc newRemoteDB(logger *slog.Logger, name string, token string) (*RemoteDB, error) {\n\tdb, err := sql.Open(\"libsql\", \"libsql://\"+name+\".turso.io?authToken=\"+token)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn \u0026RemoteDB{logger: logger, db: db, queries: queries.New(db)}, nil\n}\n```\n\n### Dist\n\nThis is where your assets live. Any Javascript, images, or styling needs to go in the \n`dist/assets` directory. The directory will be embedded into the application.\n\nNote, the `dist/assets/css` will be ignored by `git` (configured in `.gitignore`) since the \nfiles that are written to this directory are done by the Tailwind CSS CLI. Custom styles should\ngo in the `styles/input.css` file.\n\n### E2E\n\nTo test the UI, the `e2e` directory contains the Go tests for performing End to end testing. To\nrun the tests, run the command\n\n```shell\ngo test -v ./... -tags=e2e\n```\n\nThe end to end tests, will start up the app, on a random port, seeding the database using the \n`seed.sql` file. Once the tests are complete, the app will be stopped.\n\nThe E2E tests use Playwright (Go) for better integration into the Go tooling.\n\n### Log\n\nThis contains helper function to create a `slog.Logger`. Log level and output type can be set\nwith then environment variables `LOG_LEVEL` and `LOG_OUTPUT`. The logger will write to \n`stdout`.\n\n### Server\n\nThis contains everything related to the HTTP server. It comes with a graceful shutdown handler\nthat handles `SIGINT`.\n\n#### Router\n\nThis package sets up the routing for the application, such as the `/assets/` path and `/` path.\nIt uses the standard libraries mux for routing. You can easily swap out for other HTTP \nrouters such as [gorilla/mux](https://github.com/gorilla/mux).\n\n#### Middleware\n\nThis package contains any middleware to configured with routes.\n\n#### Handler\n\nThis package contains the handler to handle the actual routes.\n\n#### Styles\n\nThis contains the `input.css` that the Tailwind CSS CLI uses to generate your output CSS. \nUpdate `input.css` with any custom CSS you need and it will be included in the output CSS.\n\n#### Version\n\nThis package allows you to set a version at build time. If not set, the version defaults to \n`dev`. To set the version run the following command,\n\n```shell\ngo build -o ./app -ldflags=\"-X version.Value=1.0.0\"\n```\n\n## Github Workflow\n\nThe repository comes with two Github workflows as well. One called `ci.yml` that lints and \ntests your code. The other called `release.yml` that creates a tag, GitHub Release, run [GoReleaser](https://goreleaser.com/) to build and \nattach all the binaries, and published the docker image. See release [v1.0.2](https://github.com/Piszmog/go-htmx-template/releases/tag/v1.0.2) as an example.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiszmog%2Fgo-htmx-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiszmog%2Fgo-htmx-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiszmog%2Fgo-htmx-template/lists"}