Getting Started

Create A Context

A build context starts with a source directory and a plugin list. By default it includes the core file plugins, but framework-style apps usually configure Haml, Markdown, routing, CSS, and assets explicitly.

context = Klenod::Build::Context.new(
  source_dir: "src",
  plugins: Klenod::Build::Context.default_plugins
)

entry = context.entry("entrypoint")

exports = entry.exports
status, headers, body = entry.call(request, context)

context.entry(...) collects the requested module and returns a reusable handle without evaluating app code. Use entry.exports or entry.call(...) when you want the module to evaluate.

Import Files

Ruby modules can import other modules with literal import("...") calls. Relative imports resolve from the importer. In normal app files, leading slash imports resolve from the configured source root.

Shared = import("../shared")
ClassNames = import("/styles/home.css")
Hero = import("./hero.png?width=320,640&format=webp")
Article = import("./article.md")

Configure Builds

The CLI finds the nearest klenod.config.rb, loads it from that directory, then builds from the configs base directory.

source_dir "src"
entrypoint "entrypoint"
output "dist/klenod.bundle"
assets_dir "dist/public"
mode :development

bundle exec klenod build

Load Runtime Bundles

Production code that only loads a prebuilt bundle should depend on klenod-runtime. It does not need build-only dependencies such as Haml, CSS, or image transformers.

require "klenod/runtime"

bundle = Klenod::Runtime.load_bundle("dist/klenod.bundle")
server = bundle.exports("entrypoint")

Runtime evaluation is lazy by default. Servers that prefer startup validation can call bundle.preload_entrypoints after loading.