assets

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 22 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 (
	// SourceDir holds the source of the assets.
	SourceDir = "assets"
	// OutDir holds the built assets and the manifest.
	OutDir = "assets/dist"
	// VendorDir holds the modules that `avero js pin` fetched.
	VendorDir = "assets/js/vendor"
)

The directories of the pipeline, relative to the application root.

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 (
	// BinDir holds the pinned binaries of one application.
	BinDir = ".avero/bin"
	// TailwindVersion is the version that a scaffolded application pins.
	TailwindVersion = "4.1.11"
	// TailwindRelease is the address of one standalone binary. The version,
	// the operating system and the architecture fill it.
	TailwindRelease = "https://github.com/tailwindlabs/tailwindcss/releases/download/v%s/tailwindcss-%s-%s"
)

The names of the Tailwind pipeline.

View Source
const CDN = "https://esm.sh"

CDN is the address that resolves the name of a package to a bundled ES module. `avero js pin <package>` reads it, so a person names the package and no address.

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.

View Source
const LockName = "avero.lock"

LockName is the file that records every pinned URL and its hash.

View Source
const MaxDownload = 512 << 20

MaxDownload is the largest body that the fetcher reads. The Tailwind standalone binary holds about 80 megabytes, so the limit gives it room and still stops a body that never ends.

View Source
const PackageName = "package.json"

PackageName is the file that tier 1 adds. esbuild then resolves a bare specifier against node_modules.

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 Init

func Init(dir, name string) (bool, error)

Init writes the package.json of tier 1. `avero assets init` calls it.

It reports whether it wrote the file. A file that already exists stays as it is, so the command is idempotent and never loses a dependency that a person added. The build command stays `avero build`.

func Integrity

func Integrity(content []byte) string

Integrity returns the subresource integrity value of an asset.

func PinJS

func PinJS(ctx context.Context, cfg PinConfig, name, url string) error

PinJS fetches a bundled ES module, writes it into the vendor directory, and records the URL and the hash in the lock.

The command is idempotent: a pin that the lock already holds, with a vendor file that matches the hash, fetches nothing. An empty url reads the URL of the lock, so `avero js pin nanostores` repairs an absent file.

The command fails when the bytes of a locked URL give another hash, because that means the content of the URL changed. See S11.

func Resolve added in v0.2.0

func Resolve(ctx context.Context, fetch Fetcher, spec string) (string, error)

Resolve returns the address of the bundled module of one package.

It asks the CDN for the package, and the answer names the file that holds the bundle with its resolved version. The pin records that address, so a second machine reads the same bytes.

Resolve(ctx, f, "zustand")               the newest version
Resolve(ctx, f, "zustand@5.0.15")        one version
Resolve(ctx, f, "react-dom/client")      one subpath

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 Config

type Config struct {
	// Dir is the root of the application. An empty value is the working
	// directory.
	Dir string
	// Entries names each entry point, relative to the source directory,
	// such as js/app.js and css/app.css.
	Entries []string
	// Source is the source directory. An empty value is assets.
	Source string
	// Out is the output directory. An empty value is assets/dist.
	Out string
	// Base is the URL prefix of an asset. An empty value is /assets/.
	Base string
	// Tier states how the pipeline resolves an import.
	Tier Tier
	// Command runs the build of TierExternal. The first element is the
	// program and the rest are its arguments.
	Command []string
	// CommandDir is the directory of the command, relative to Dir. An empty
	// value runs it in Dir.
	CommandDir string
	// NoManifest states a command that writes its own index document and no
	// manifest of Avero, such as Vite. The build then reads no manifest, and
	// the application serves the output with SPA.
	NoManifest bool
	// Minify shrinks the output. A release build sets it.
	Minify bool
	// Tailwind compiles the stylesheet with the standalone binary. A nil
	// value leaves the stylesheet to esbuild.
	Tailwind *Tailwind
}

Config states one build.

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 Fetcher

type Fetcher interface {
	// Fetch returns the bytes of the URL.
	Fetch(ctx context.Context, url string) ([]byte, error)
}

Fetcher reads a URL. The pipeline takes it as a field, so a test needs no network. See design rule 3.

func HTTPFetcher

func HTTPFetcher(client *http.Client) Fetcher

HTTPFetcher returns the fetcher that a command uses. A nil client gives a client with a timeout of one minute.

type Lock

type Lock struct {
	// contains filtered or unexported fields
}

Lock is avero.lock. It records the URL and the hash of every file that a command fetched, so a second machine gets the same bytes.

func LoadLock

func LoadLock(dir string) (*Lock, error)

LoadLock reads the lock of this application. An absent file gives an empty lock, so the first pin needs no file.

func (*Lock) Bin

func (l *Lock) Bin(name string) (Pin, bool)

Bin returns the pin of a binary.

func (*Lock) JS

func (l *Lock) JS(name string) (Pin, bool)

JS returns the pin of a module.

func (*Lock) Names

func (l *Lock) Names() []string

Names returns the name of each pinned module, in alphabetical order.

func (*Lock) Save

func (l *Lock) Save() error

Save writes the lock. The document sorts its keys, so two runs give the same file. See AN-4.

func (*Lock) SetBin

func (l *Lock) SetBin(name string, pin Pin)

SetBin records the pin of a binary.

func (*Lock) SetJS

func (l *Lock) SetJS(name string, pin Pin)

SetJS records the pin of a module.

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 Build

func Build(ctx context.Context, cfg Config) (*Manifest, error)

Build bundles the entry points and writes the output directory and the manifest. It returns the manifest that the application reads.

Every tier writes one shape, so a page reads the same manifest whichever tier built it.

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.

type Pin

type Pin struct {
	// URL is the address that the file came from.
	URL string `json:"url"`
	// SHA256 is the hash of the file in the vendor directory, in
	// hexadecimal. It is the hash of the bytes after the rewrite of the
	// imports, which is deterministic.
	SHA256 string `json:"sha256"`
	// SourceSHA256 is the hash of the bytes that the address answered. It
	// proves the origin of a module that the pin rewrote.
	SourceSHA256 string `json:"source_sha256,omitempty"`
	// Version is the version of a binary. A module leaves it empty.
	Version string `json:"version,omitempty"`
}

Pin records one fetched file.

type PinConfig

type PinConfig struct {
	// Dir is the root of the application. An empty value is the working
	// directory.
	Dir string
	// Fetch reads the URL. A nil value reads over HTTP.
	Fetch Fetcher
}

PinConfig states one pin.

type Tailwind

type Tailwind struct {
	// Version is the release to pin, such as 4.1.11.
	Version string
	// Dir is the root of the application.
	Dir string
	// Input is the stylesheet that Tailwind reads, relative to Dir.
	Input string
	// Asset is the name that the manifest records for the output. An empty
	// value is css/app.css.
	Asset string
	// Minify shrinks the stylesheet. A release build sets it.
	Minify bool
	// Fetch downloads the binary. A nil value downloads over HTTP.
	Fetch Fetcher
}

Tailwind drives the Tailwind standalone binary. The binary needs no Node.js, so tier 0 styles an application with Go, Docker and avero alone. See DX-9.

func (*Tailwind) Compile

func (t *Tailwind) Compile(ctx context.Context) ([]byte, error)

Compile runs the binary and returns the stylesheet. The build hashes the bytes and writes them into the output directory, so the CSS reaches the manifest like every other asset.

func (*Tailwind) Ensure

func (t *Tailwind) Ensure(ctx context.Context) (string, error)

Ensure returns the path of the binary. It downloads the binary one time and records the URL and the hash in the lock, so a second machine gets the same bytes. A binary that the lock already holds is verified, not downloaded.

func (*Tailwind) Name

func (t *Tailwind) Name() string

Name returns the file name of the pinned binary.

func (*Tailwind) URL

func (t *Tailwind) URL() string

URL returns the address of the binary for this machine.

type Tier

type Tier int

Tier states how the pipeline resolves an import.

const (
	// TierBundled is the default. It needs no Node.js. It resolves a
	// relative path and a vendored package only. See DX-9.
	TierBundled Tier = iota
	// TierNode adds a package.json, so esbuild resolves a bare specifier
	// against node_modules. `avero assets init` writes the file.
	TierNode
	// TierExternal runs a command of the application. The command must
	// write the output directory and a manifest with the same shape.
	TierExternal
)

Jump to

Keyboard shortcuts

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