pipeline

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Sep 15, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package pipeline builds the assets of an application: it bundles the entry points with esbuild, compiles the stylesheet with Tailwind, pins a module or a component library, and writes the manifest that the application serves.

The pipeline runs at build time only. `avero build` and `avero dev` call it. An application imports the assets package, which holds the manifest and the two handlers, and it therefore compiles no bundler. See the SDD, S11.

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 (
	// 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 BasecoatVersion = "1.0.2"

BasecoatVersion is the release of Basecoat that `avero ui add basecoat` fetches. See the SDD, S11.

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 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 PackageDir = "assets/vendor"

PackageDir holds the tree of each library that `avero ui add` fetched, relative to the application root.

View Source
const PackageName = "package.json"

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

Variables

This section is empty.

Functions

func Build

func Build(ctx context.Context, cfg Config) (*assets.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 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 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 PinPackage

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

PinPackage fetches the released package of a library, writes its dist directory into the vendor directory, and records the address, the hash and the file list in the lock.

One tarball carries the stylesheets and the scripts of a library, so one pin covers both and the build needs no network. See the SDD, S11.

The command is idempotent: a name that the lock holds, whose files all exist and whose tarball gives the recorded hash, fetches nothing.

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

func Resolve

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

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 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) Package

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

Package returns the pin of a library that arrived as a package.

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.

func (*Lock) SetPackage

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

SetPackage records the pin of a library that arrived as a package.

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"`
	// Files names each file that a package pin wrote, as a slash path under
	// the vendor directory of the package. The list sorts, so two runs give
	// one lock. A module pin and a binary pin leave it empty.
	Files []string `json:"files,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