Dependencies

Render compiled theme CSS plus an ordered CDN-first loader with exact-version local fallback for Alpine.js, HTMX, and component runtime helpers.

Default Rendered example

Full runtime helper

@head.Dependencies()

CDN: pinned Alpine + HTMX
Fallback: /assets/js/runtime/*
Loader: /assets/js/dependency-loader.js

Usage Example

<head>
    @head.Dependencies()
</head>

Emit route-specific title, description, canonical, Open Graph, and X/Twitter Card tags in the initial HTML response.

Social Metadata Rendered example

One route config, complete social contract

Metadata defaults to website plus a large-image card and rejects incomplete or non-HTTPS configurations before writing tags.

Social Metadata

<head>
    @head.Metadata(head.MetadataConfig{
        Title:        "Product documentation",
        Description:  "Learn how to use the product.",
        CanonicalURL: "https://example.com/docs",
        SiteName:     "Example",
        Locale:       "en_US",
        Image: head.SocialImage{
            URL: "https://example.com/social/docs-v1.jpg",
            MIMEType: "image/jpeg", Width: 1280, Height: 640,
            Alt: "Example product documentation",
        },
    })
    @head.Dependencies()
</head>

Minimal Runtime

Use DependenciesMinimal when the page does not need the Alpine collapse, focus, or mask plugins.

Minimal Runtime Rendered example

DependenciesMinimal

CSS, the combined first-party bundle, Alpine core, and HTMX. Optional manifest entries still follow their IncludeInMinimal setting.

Minimal Runtime

<head>
    @head.DependenciesMinimal()
</head>

Asset Mount Contract

Both helpers require the embedded asset handler at /assets/ for CSS, the loader, first-party helpers, and local fallback.

Asset Mount Contract Rendered example

Serve bundled assets

mux.Handle("GET /assets/", assets.Handler())

Asset Mount Contract

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

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

Local-only and custom sources

Use functional options to make the runtime fully local, replace one dependency's CDN/fallback pair, omit an application-owned dependency, or disable fallback.

Local-only and custom sources Rendered example

Strong defaults, explicit escape hatches

The default falls back to embedded assets with SHA-384 integrity. Local-only mode supports offline PWAs and WebViews; per-dependency options keep version ownership visible.

Custom URLs configure loading only. Goshtoso guarantees compatibility for its pinned, tested dependency combination—not arbitrary versions.

Local-only and custom sources

// Choose one mode for the page:
@head.Dependencies(head.WithLocalRuntime())

// Or customize the resilient mode:
@head.Dependencies(
    head.WithDependencyCDNURL(head.DependencyHTMX, "https://cdn.example.com/htmx-2.0.8.min.js"),
    head.WithDependencyLocalURL(head.DependencyHTMX, "/static/htmx-2.0.8.min.js"),
    head.WithDependencyIntegrity(head.DependencyHTMX, "sha384-..."),
)

Typed manifest ownership

Start from the pinned public manifest when the application must enable optional runtimes, add a script, omit a dependency, or declare another safe order.

Typed manifest ownership Rendered example

One typed, ordered baseline

WithRuntimeManifest snapshots caller data and validates roles, URLs, loader availability, known runtime order, and first-party conflicts before writing HTML.

Typed manifest ownership

runtime := assets.DefaultRuntimeManifest()
// Enable or edit entries by RuntimeAssetRole, then add application-owned code.
runtime.Dependencies = append(runtime.Dependencies, assets.RuntimeAsset{
    Role: "application-runtime", Kind: assets.RuntimeAssetScript,
    PrimaryURL: "/static/application-runtime.js",
    LocalURL: "/static/application-runtime.js",
    Enabled: true,
})

@head.Dependencies(head.WithRuntimeManifest(runtime))

Go API

v0.2.7

The examples above cover behavior and composition. pkg.go.dev is the canonical reference for exported types, functions, methods, and Go documentation.

github.com/araihu/goshtoso/components/head

Open v0.2.7 API

Code Block Icon