goshtoso

module

v0.1.0 Latest Latest Go to latest Published: Jul 29, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/araihu/goshtoso

Links

Open Source Insights

README ¶

Goshtoso

Goshtoso mascot

Goshtoso is a Go UI component library for server-rendered web apps. It combines templ, Tailwind CSS, HTMX, and Alpine.js into a set of importable components with bundled CSS and JavaScript assets.

The project began as a hard fork of PenguinUI and has grown into a Go-first component system for applications that prefer rendered HTML, small client-side sprinkles, and versioned dependency ownership instead of floating copy-paste snippets.

Goshtoso is actively evolving. The components are usable, but the API surface is still being refined as the library moves toward a stable public release. See ROADMAP.md for the alpha stability policy and release path.

Highlights

52 public component packages documented across 50 documentation pages, exposing 82 renderable primitives for composition, forms, navigation, overlays, data display, feedback, layout, and richer inputs.
Server-rendered by default with HTMX-friendly markup and Alpine.js where instant local interaction makes sense.
Bundled assets for Tailwind CSS, Alpine.js, HTMX, htmx extensions, fonts, and images. No runtime CDN dependency is required.
Theme system included with light/dark support and 15 built-in themes.
Two-module repository: a slim publishable library at the repo root and a demo/test site under site/.
Go-native examples and tests using templ generation and Playwright-backed E2E coverage.

Quick Start

Goshtoso requires Go 1.26.5 or newer.

Install the library:

go get github.com/araihu/goshtoso@latest

Mount the embedded assets in your server:

package main

import (
    "net/http"

    "github.com/araihu/goshtoso/assets"
)

func main() {
    http.Handle("/assets/", assets.Handler())

    http.ListenAndServe(":8080", nil)
}

Include Goshtoso's CSS and JavaScript in your page shell:

import "github.com/araihu/goshtoso/components/head"

templ Layout() {
    <html>
        <head>
            @head.Dependencies()
        </head>
        <body>
            { children... }
        </body>
    </html>
}

head.Dependencies() uses version-pinned unpkg URLs first and automatically retries the matching embedded JavaScript when a CDN download fails. The CSS, loader, first-party helpers, and fallback files still come from assets.Handler(); third-party bytes are protected by generated SHA-384 SRI. For an offline PWA or desktop/mobile WebView, an air-gapped deployment, or another application that must never request a CDN, use:

@head.Dependencies(head.WithLocalRuntime())

Functional options can replace the CDN and local URL of each dependency, disable fallback, omit an application-owned runtime, or move the stylesheet, loader, and combobox helper. See docs/USAGE.md.

Render components from their packages:

import "github.com/araihu/goshtoso/components/button"

templ Example() {
    @button.Button(
        button.WithTone(button.TonePrimary),
        button.WithType("button"),
    ) {
        Save changes
    }
}

Goshtoso components ship pre-generated, so consumers do not run templ generate on the library itself. You still run templ generate for your own .templ files.

For a complete integration guide, including custom Tailwind builds and manual asset wiring, see docs/USAGE.md. The Goshtoso Component Model documents the common component interface, concrete return values, constructor styles, stable Kind identity, and rendered defaults. Release changes are recorded in the changelog; applications upgrading from v0.0.11 should follow the component API migration guide.

AI Agent Skill

Goshtoso ships an installable skill for AI coding agents that need to use the library inside consumer applications. It teaches agents how to install the Go module, serve bundled assets, wire head.Dependencies(), import components, choose a CSS strategy, write a low-interaction surface brief, route the real task into supported application patterns, reject generic design reflexes, and verify the result in the browser. The composition contracts remain App Shell, Operations List, Detail Workspace, and Multi-step Workflow.

Install the skill into a project or agent workspace:

npx skills add araihu/goshtoso --skill using-goshtoso

For Codex:

npx skills add araihu/goshtoso --skill using-goshtoso --agent codex

Use it without installing files:

npx skills use araihu/goshtoso --skill using-goshtoso

The skill is intentionally consumer-focused. It does not cover maintaining Goshtoso itself, editing component internals, or running releases. The public docs site includes an AI Agents page at /docs/agents. The installed skill also ships a design-intelligence reference, an application patterns reference, and a visual acceptance checklist.

For a public organization, product, or publication site, start with the copyable examples/brand-site fixture rather than an application shell. It generates static HTML and makes the product-owned typography, art direction, and content hierarchy explicit. Create a fresh copy with go run github.com/araihu/goshtoso/cmd/goshtoso@latest -init-brand-site=./my-site.

Component Catalog

All components are imported from:

github.com/araihu/goshtoso/components/<name>

Current components:

accordion        actiongroup  alert        appshell     avatar       badge
banner           breadcrumbs  button       card         carousel     chatbubble
checkbox         codeblock    combobox     drawer       dropdown     emptystate
fileinput        form         head         kbd          link         modal
navbar           pageheader   pagination   palette      panel        radio
range            rating       schemaform   search       select       sidebar
skeleton         spinner      steps        structuredinput table     tabs
tagslist         textarea     textinput    toast        toolbar      toggle
tooltip

Run the demo site to explore component options, API tables, HTMX behavior, Alpine.js states, themes, and example apps:

go run ./site/cmd/server

Then open:

The public documentation site is available at https://goshtoso.araihu.com/.

Using Assets

The recommended path is to serve Goshtoso's embedded assets:

mux := http.NewServeMux()
mux.Handle("GET /assets/", assets.Handler())

and let @head.Dependencies() emit the matching stylesheet and script tags. The default loader tries version-pinned CDN URLs for Alpine.js and HTMX, then falls back to the same versions under /assets/js/runtime/. Use head.WithLocalRuntime() when an offline application such as a PWA or native WebView must be fully local.

If you maintain a custom Tailwind build, Goshtoso also ships a CLI that extracts the compiled CSS or theme source:

go run github.com/araihu/goshtoso/cmd/goshtoso@latest -out=css/goshtoso-base.css

See docs/USAGE.md for the full asset strategy. Release maintainers should also use docs/RELEASE_CHECKLIST.md before tagging.

Sprite Icons

components/icon renders accessible SVG <use> references. The bundled components/icon/heroicons package provides typed symbols and a same-origin default sprite URL:

import (
    "github.com/araihu/goshtoso/components/icon"
    "github.com/araihu/goshtoso/components/icon/heroicons"
)

templ SaveIcon() {
    @icon.Icon(icon.Config{
        SpriteURL: heroicons.SpriteURL,
        Symbol:    heroicons.Icon16SolidCheck,
        Label:     "Saved",
    })
}

Use a relative, same-origin sprite URL by default. ModeInline resolves an already-present symbol from the current document; cross-origin external sprites depend on browser support and CORS, and HTTPS pages should not reference an HTTP sprite. A blank label and Decorative: true both produce a decorative icon. See docs/USAGE.md for generator and deployment details.

Repository Layout

goshtoso/
├── cmd/                     # Thin command entry points
├── components/              # Publishable component library
├── assets/                  # Embedded CSS, JS, fonts, and images
├── css/                     # Tailwind source
├── docs/                    # Consumer and project documentation
├── examples/                # Standalone examples
├── internal/                # Generator internals used by cmd/* tools
└── site/                    # Demo site, example app pages, server, E2E tests

The root module is github.com/araihu/goshtoso. The site/ directory is a separate module for the demo website and test harness.

For local development, create a Go workspace once per clone so the site imports your working-tree copy of the library:

go work init . ./site

Development

Useful commands from the repo root:

# Generate *_templ.go files after editing .templ sources
templ generate
# or
just gp-generate

# Rebuild the embedded Tailwind CSS after editing CSS/theme sources
just css

# Run the demo server on :8090
go run ./site/cmd/server
# or
just gp-dev

# Build the demo server
go build -o bin/server ./site/cmd/server

Run tests:

# Library tests
go test ./...

# Site tests
cd site && go test ./...

# Full Playwright E2E suite
go test ./site/tests/e2e/... -count=1 -timeout 15m

Run lint checks per module:

golangci-lint run
cd site && golangci-lint run

Generated files are part of the repo, but should not be edited by hand:

*_templ.go is generated by templ generate
assets/styles.css is generated by just css

Contributing

See CONTRIBUTING.md for contribution guidelines and CODE_OF_CONDUCT.md for community expectations.

When adding or changing components, keep the component source, demo page, E2E coverage, generated templ output, CSS output, and usage reference in sync.

Credits

Goshtoso began as a hard fork of PenguinUI by Salar Houshvand, transformed from static HTML/Alpine.js examples into an importable Go component library.

License

MIT. See LICENSE.

Directories ¶

Path	Synopsis
assets Package assets provides embedded static files and their public runtime contract for Goshtoso components.	Package assets provides embedded static files and their public runtime contract for Goshtoso components.
cmd
goshtoso command Command goshtoso extracts embedded Goshtoso assets and reports versions.	Command goshtoso extracts embedded Goshtoso assets and reports versions.
iconcatalog command Command iconcatalog generates typed sprite bindings from a schema-v1 asset catalog.	Command iconcatalog generates typed sprite bindings from a schema-v1 asset catalog.
jsbuild command
jslint command
skillgen command
themegen command
vendorgen command
components
accordion templ: version: v0.3.1020	templ: version: v0.3.1020
actiongroup templ: version: v0.3.1020	templ: version: v0.3.1020
alert templ: version: v0.3.1020	templ: version: v0.3.1020
appshell templ: version: v0.3.1020	templ: version: v0.3.1020
avatar templ: version: v0.3.1020	templ: version: v0.3.1020
badge templ: version: v0.3.1020	templ: version: v0.3.1020
banner templ: version: v0.3.1020	templ: version: v0.3.1020
breadcrumbs templ: version: v0.3.1020	templ: version: v0.3.1020
button templ: version: v0.3.1020	templ: version: v0.3.1020
card templ: version: v0.3.1020	templ: version: v0.3.1020
carousel templ: version: v0.3.1020	templ: version: v0.3.1020
chatbubble templ: version: v0.3.1020	templ: version: v0.3.1020
checkbox templ: version: v0.3.1020	templ: version: v0.3.1020
codeblock templ: version: v0.3.1020	templ: version: v0.3.1020
combobox templ: version: v0.3.1020	templ: version: v0.3.1020
drawer templ: version: v0.3.1020	templ: version: v0.3.1020
dropdown templ: version: v0.3.1020	templ: version: v0.3.1020
emptystate templ: version: v0.3.1020	templ: version: v0.3.1020
fileinput templ: version: v0.3.1020	templ: version: v0.3.1020
form templ: version: v0.3.1020	templ: version: v0.3.1020
form/validation
head templ: version: v0.3.1020	templ: version: v0.3.1020
icon templ: version: v0.3.1020	templ: version: v0.3.1020
icon/heroicons
kbd templ: version: v0.3.1020	templ: version: v0.3.1020
link templ: version: v0.3.1020	templ: version: v0.3.1020
modal templ: version: v0.3.1020	templ: version: v0.3.1020
navbar templ: version: v0.3.1020	templ: version: v0.3.1020
pageheader templ: version: v0.3.1020	templ: version: v0.3.1020
pagination templ: version: v0.3.1020	templ: version: v0.3.1020
palette templ: version: v0.3.1020	templ: version: v0.3.1020
panel templ: version: v0.3.1020	templ: version: v0.3.1020
radio templ: version: v0.3.1020	templ: version: v0.3.1020
range templ: version: v0.3.1020	templ: version: v0.3.1020
rating templ: version: v0.3.1020	templ: version: v0.3.1020
schemaform templ: version: v0.3.1020	templ: version: v0.3.1020
search templ: version: v0.3.1020	templ: version: v0.3.1020
select templ: version: v0.3.1020	templ: version: v0.3.1020
sidebar templ: version: v0.3.1020	templ: version: v0.3.1020
skeleton templ: version: v0.3.1020	templ: version: v0.3.1020
spinner templ: version: v0.3.1020	templ: version: v0.3.1020
steps templ: version: v0.3.1020	templ: version: v0.3.1020
structuredinput templ: version: v0.3.1020	templ: version: v0.3.1020
table templ: version: v0.3.1020	templ: version: v0.3.1020
tabs templ: version: v0.3.1020	templ: version: v0.3.1020
tagslist templ: version: v0.3.1020	templ: version: v0.3.1020
textarea templ: version: v0.3.1020	templ: version: v0.3.1020
textinput templ: version: v0.3.1020	templ: version: v0.3.1020
toast templ: version: v0.3.1020	templ: version: v0.3.1020
toggle templ: version: v0.3.1020	templ: version: v0.3.1020
toolbar templ: version: v0.3.1020	templ: version: v0.3.1020
tooltip templ: version: v0.3.1020	templ: version: v0.3.1020
internal
iconcatalog Package iconcatalog loads schema-v1 asset catalogs and generates typed sprite bindings for a selected namespace and product.	Package iconcatalog loads schema-v1 asset catalogs and generates typed sprite bindings for a selected namespace and product.
jstooling
skillgen Command skillgen derives the Goshtoso component API reference from source.	Command skillgen derives the Goshtoso component API reference from source.
themegen Command themegen generates assets/goshtoso-theme.css — the self-contained Goshtoso theme source a consumer imports into their own Tailwind v4 build.	Command themegen generates assets/goshtoso-theme.css — the self-contained Goshtoso theme source a consumer imports into their own Tailwind v4 build.
vendorgen Command vendorgen generates assets/vendor_gen.go from the runtime version manifest (assets/js/runtime/versions.json) — the single source of truth for every vendored third-party JS dependency's version, file, and origin.	Command vendorgen generates assets/vendor_gen.go from the runtime version manifest (assets/js/runtime/versions.json) — the single source of truth for every vendored third-party JS dependency's version, file, and origin.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL