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
- Variables
- func Handler(fsys fs.FS, m *Manifest) http.Handler
- func Hash(content []byte) string
- func HashedName(name, hash string) string
- func Init(dir, name string) (bool, error)
- func Integrity(content []byte) string
- func PinJS(ctx context.Context, cfg PinConfig, name, url string) error
- type Config
- type Entry
- type Fault
- type Faults
- type Fetcher
- type Lock
- type Manifest
- func (m *Manifest) Asset(name string) string
- func (m *Manifest) Entry(name string) (Entry, bool)
- func (m *Manifest) Has(name string) bool
- func (m *Manifest) Len() int
- func (m *Manifest) MarshalJSON() ([]byte, error)
- func (m *Manifest) Names() []string
- func (m *Manifest) Set(e Entry)
- func (m *Manifest) UnmarshalJSON(b []byte) error
- type Pin
- type PinConfig
- type Tailwind
- type Tier
Constants ¶
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.
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.
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.
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.
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.
const LockName = "avero.lock"
LockName is the file that records every pinned URL and its hash.
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.
const PackageName = "package.json"
PackageName is the file that tier 1 adds. esbuild then resolves a bare specifier against node_modules.
Variables ¶
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 ¶
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 ¶
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 ¶
HashedName puts the hash between the stem and the extension of a name.
HashedName("css/app.css", "a1b2c3d4e5f6") == "css/app.a1b2c3d4e5f6.css"
func Init ¶
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 PinJS ¶
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.
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. It runs in Dir.
Command []string
// 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.
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.
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 ¶
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 ¶
LoadLock reads the lock of this application. An absent file gives an empty lock, so the first pin needs no file.
func (*Lock) Save ¶
Save writes the lock. The document sorts its keys, so two runs give the same file. See AN-4.
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 ¶
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 ¶
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 ¶
NewManifest returns an empty manifest. An empty base becomes /assets/.
func (*Manifest) Asset ¶
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) MarshalJSON ¶
MarshalJSON emits the manifest with a stable schema. See AN-3.
func (*Manifest) Names ¶
Names returns the source name of each asset, in alphabetical order. See AN-4.
func (*Manifest) UnmarshalJSON ¶
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 bytes, in hexadecimal.
SHA256 string `json:"sha256"`
// 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 ¶
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 ¶
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.
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 )