Getting Started

Install Klenod

Add the runtime gem to your applications Gemfile. It is the only Klenod gem required when production only loads a prebuilt bundle:

gem "klenod-runtime"

If the application serves generated assets through Rack, add klenod-rack as well:

gem "klenod-rack"

Put the build and development tools in a development/build group. They are needed to collect and write bundles, run tests, and compile optional formats, but they do not need to ship with the production application:

group :development, :build do
  gem "klenod"
  gem "klenod-plugin-css"
  gem "klenod-plugin-javascript"
end

Run bundle install after updating the Gemfile. The klenod meta-gem provides the CLI, build tools, and test support; applications can depend on klenod-build or klenod-test directly when they need only those pieces.

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.