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
- func Resolve(ctx context.Context, fetch Fetcher, spec string) (string, error)
- func SPA(fsys fs.FS) http.Handler
- 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 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.
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 IndexFile = "index.html"
IndexFile is the document that a single page application serves for a path that it owns.
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.
func Resolve ¶ added in v0.2.0
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
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.
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 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 ¶
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 )