Assets

Asset Identity

Klenod assets have two stable identifiers:

• logical_name: the source-root-relative file path without import query parameters, such as images/hero.png.
• output_path: the canonical root-relative asset path, such as /hero.640w.abcd1234.png.
• url: the build-time browser URL, such as https://cdn.example.test/hero.640w.abcd1234.png.

Query parameters configure an import without changing the logical name, so overlapping generated variants can be reused. Asset content is content-hashed, so production servers can cache emitted browser paths aggressively.

Asset Base URLs

Set Klenods base build option to choose the browser-visible asset prefix. It accepts an origin-relative path or an HTTP(S) CDN URL, and normalizes a missing trailing slash:

base "https://cdn.klenod.dev/"

The example web app uses /.assets/ in development and https://cdn.klenod.dev/ in builds. Emitted files live directly in dist/public; configure the CDN origin or upload mapping to serve that directory at the chosen base. Every emitted asset has a build-time url for rendering directly. Generated CSS, JavaScript, image, SVG, and font URLs already use the configured base.

Lookup APIs

The build graph and runtime bundle expose the same lookup shape.

context.asset("/home.abc123.css")
context.assets_for("styles/home.css")
context.assets_for_module("entrypoint.rb", type: :css)

bundle.asset("/home.abc123.css")
bundle.assets_for_module("entrypoint.rb", type: :css)

assets_for_module is recursive by default. Pass recursive: false for only assets directly emitted by the root module. asset_references_for_module also includes a graph traversal index, which is useful for route-scoped CSS ordering.

Serving Assets With Rack

Add klenod-rack when a Rack application serves assets emitted by a production bundle. Klenod::Rack::AssetApp looks up browser paths in the loaded bundle and reads their bytes from the emitted assets directory:

# config.ru
require "klenod/runtime"
require "klenod/rack"

bundle = Klenod::Runtime.load_bundle("dist/klenod.bundle")
entrypoint = bundle.exports("entrypoint")
application = ->(env) { entrypoint.call(env, bundle) }

run Klenod::Rack::AssetApp.new(
  bundle,
  assets_dir: "dist/public",
  base: bundle.base,
  path_prefix: "/.assets/",
  app: application
)

The asset app maps public paths under /.assets/ to root-relative files in assets_dir, with immutable cache headers, and delegates every other request to app, which calls the bundle entrypoint. When matching .br files are present in assets_dir, the asset app also serves Brotli responses to clients that accept them. This lets the CDN forward https://cdn.klenod.dev/<asset> to https://klenod.dev/.assets/<asset>. Configure the CDN to return Access-Control-Allow-Origin: https://klenod.dev so browsers can load CDN fonts. The document head and its Link headers preconnect to external asset origins; development assets are local, so they do not add a preconnect hint.

CSS, SVG, And Images

CSS imports from Ruby or Haml return class-name maps. CSS imports from CSS become stylesheet dependencies, and CSS url(...) references become asset dependencies.

SVG imports emit the SVG file as a browser asset and export an immutable SvgMetadata value with src, width, height, content_type, and aspect_ratio.

Raster image imports support .avif, .gif, .jpeg, .jpg, .png, and .webp. Import query options can request widths, formats, and quality:

Hero = import("hero.jpg?width=320,640&format=webp,jpeg&quality=82")

Ruby image imports return an immutable ImageMetadata value with src, dimensions, content_type, aspect_ratio, variants, srcset, and sizes. Its immutable ImageVariant values expose the same base metadata plus format, descriptor, and quality. If format or quality is requested, the default src can also be a generated asset. Generated variants are deduplicated by source path, source hash, width, format, and quality.

Google Fonts

GoogleFontsPlugin resolves Google Fonts CSS imports, downloads or reuses cached raw CSS, rewrites fonts.gstatic.com URLs to local emitted font assets, and emits the rewritten stylesheet as a normal CSS asset. It also emits Capsize-powered metric-adjusted fallback faces by default. Font files are lazy IO-generated assets so downloads can overlap with CPU-bound image generation without becoming unbounded.