assets

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 14, 2026 License: MIT Imports: 14 Imported by: 2

Documentation

Overview

Package assets holds the asset pipeline, S11.

The pipeline has three tiers. Tier 0 is the default and needs no Node.js: it bundles with esbuild as a Go library, resolves relative paths and vendored paths only, and drives the Tailwind standalone binary. Tier 1 adds a package.json, so esbuild resolves a bare specifier against node_modules. Tier 2 runs an external command that writes the same output.

Every tier writes assets/dist and a manifest with one shape. A page reads the manifest with Asset, and the binary serves the files from an embedded file system. See the SDD, S11 and DX-9.

Index

Constants

View Source
const (
	// ManifestName is the file that every tier writes into the output
	// directory.
	ManifestName = "manifest.json"
	// ManifestSchemaID names the schema that a manifest follows. See
	// assets/schema.json.
	ManifestSchemaID = "https://avero.dev/schema/asset-manifest/v1"
	// DefaultBase is the URL prefix that the handler serves.
	DefaultBase = "/assets/"
)

The names of the manifest.

View Source
const CacheControl = "public, max-age=31536000, immutable"

CacheControl is the header of a hashed asset. The name carries the content hash, so the file never changes and the browser can hold it for one year.

View Source
const HashLength = 12

HashLength is the number of hexadecimal characters of an asset hash. Twelve characters hold 48 bits, so a collision between two files of one application is not credible.

View Source
const IndexFile = "index.html"

IndexFile is the document that a single page application serves for a path that it owns.

Variables

View Source
var ManifestSchema []byte

ManifestSchema holds assets/schema.json. Every tier writes a document that this schema accepts, so a tier 2 command must write the same shape. See AN-3.

Functions

func Handler

func Handler(fsys fs.FS, m *Manifest) http.Handler

Handler serves the built assets of a manifest from a file system.

It serves a file that the manifest names and nothing else, so a file that the output directory happens to hold never reaches the network. The application passes the embedded file system, so the binary carries the assets and needs no directory beside it.

r.Mount("/assets/", assets.Handler(dist, manifest))

func Hash

func Hash(content []byte) string

Hash returns the content hash of an asset. A changed file gives a different hash, so the hashed name breaks the cache of the browser.

func HashedName

func HashedName(name, hash string) string

HashedName puts the hash between the stem and the extension of a name.

HashedName("css/app.css", "a1b2c3d4e5f6") == "css/app.a1b2c3d4e5f6.css"

func Integrity

func Integrity(content []byte) string

Integrity returns the subresource integrity value of an asset.

func NewFault added in v0.5.0

func NewFault(file, message, repair string) error

NewFault returns one fault as an error. The pipeline package builds a fault of the build with it, so both halves of the asset subsystem state one shape.

func SPA added in v0.2.0

func SPA(fsys fs.FS) http.Handler

SPA serves the build of a single page application from a file system.

A request for a file that the build holds answers that file. A hashed name answers with the cache of one year, because the name changes with the content. Any other path answers the index document, so a deep link and a reload reach the front end.

The application embeds the output directory, so one binary holds the server and the front end.

//go:embed all:assets/dist
var dist embed.FS

files, _ := fs.Sub(dist, "assets/dist")
r.Mount("/", assets.SPA(files))

Types

type Entry

type Entry struct {
	// Source is the name that the page asks for, such as app.css.
	Source string `json:"source"`
	// File is the built name with the hash, such as app.a1b2c3.css.
	File string `json:"file"`
	// Hash is the content hash of the file.
	Hash string `json:"hash"`
	// Size is the number of bytes of the file.
	Size int64 `json:"size"`
	// Integrity is the subresource integrity value of the file.
	Integrity string `json:"integrity"`
}

Entry is one built asset.

type Fault

type Fault struct {
	// File is the file that holds the fault. It is empty when no file
	// applies.
	File string `json:"file"`
	// Line is the line that holds the fault. It is zero when no line
	// applies.
	Line int `json:"line"`
	// Column is the column that holds the fault. It is zero when no column
	// applies.
	Column int `json:"column"`
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
}

Fault is one asset fault. It states what went wrong and states the repair in one sentence. It names a file when a file holds the fault. See DX-6 and DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the position, the message and the repair.

type Faults

type Faults struct {
	Faults []*Fault `json:"faults"`
}

Faults holds every fault that one build found. The build reports every fault, not only the first.

func (*Faults) Error

func (l *Faults) Error() string

Error returns a count and one entry for each fault.

func (*Faults) Unwrap

func (l *Faults) Unwrap() []error

Unwrap returns each fault so that errors.As reaches a single one.

type Manifest

type Manifest struct {
	// Base is the URL prefix of every asset, such as /assets/.
	Base string
	// contains filtered or unexported fields
}

Manifest maps the name of an asset to the built file. `avero build` writes it, and the application reads it one time at start.

func LoadManifest

func LoadManifest(fsys fs.FS, name string) (*Manifest, error)

LoadManifest reads the manifest at this path from a file system. The application passes the embedded file system that holds assets/dist.

//go:embed all:assets/dist
var dist embed.FS
m, err := assets.LoadManifest(dist, "assets/dist/manifest.json")

func NewManifest

func NewManifest(base string) *Manifest

NewManifest returns an empty manifest. An empty base becomes /assets/.

func (*Manifest) Asset

func (m *Manifest) Asset(name string) string

Asset returns the URL path of an asset.

A name that the manifest does not hold returns the unhashed path, so a page still renders while a person repairs the build. `avero doctor` reports the absent entry before the process starts. See DX-8.

<link rel="stylesheet" href={ ui.Asset("app.css") }>

func (*Manifest) Entry

func (m *Manifest) Entry(name string) (Entry, bool)

Entry returns the entry of this asset.

func (*Manifest) Has

func (m *Manifest) Has(name string) bool

Has reports whether the manifest holds this asset.

func (*Manifest) Len

func (m *Manifest) Len() int

Len returns the number of assets.

func (*Manifest) MarshalJSON

func (m *Manifest) MarshalJSON() ([]byte, error)

MarshalJSON emits the manifest with a stable schema. See AN-3.

func (*Manifest) Names

func (m *Manifest) Names() []string

Names returns the source name of each asset, in alphabetical order. See AN-4.

func (*Manifest) Set

func (m *Manifest) Set(e Entry)

Set records one entry.

func (*Manifest) UnmarshalJSON

func (m *Manifest) UnmarshalJSON(b []byte) error

UnmarshalJSON reads a manifest that any tier wrote.

Jump to

Keyboard shortcuts

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