Configuration

Config File

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

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

source_dir is where imports are resolved from. entrypoint names modules to collect into the bundle. output is the runtime bundle path. assets_dir is where emitted browser assets are written during builds.

Plugin Order

Plugins run in order for resolving, loading, transforming, and import value hooks. Put special-purpose plugins before broad ones when they need first chance at a specifier.

A framework-style app usually configures specialized plugins first, followed by Ruby/Haml/Markdown/CSS/assets/data plugins:

plugins [
  Klenod::Build::Plugins::RouterPlugin.new(
    route_base_class: "Example::Route"
  ),
  Klenod::Build::Plugins::RubyPlugin.new,
  Klenod::Build::Plugins::IntlPlugin.new,
  Klenod::Build::Plugins::HamlPlugin.new(
    component_base_class: "Example::Component",
    factory: "Example::H",
    i18n_class: "Example::I18n"
  )
]

Context.default_plugins is useful for small examples. Framework-style apps usually spell out plugin configuration so Haml, Markdown, images, routes, and external CSS use the right application classes and options.

Template Factories

Haml and Markdown plugins need a component superclass and a factory for generated element calls.

Klenod::Build::Plugins::HamlPlugin.new(
  component_base_class: "Example::Component",
  factory: "Example::H",
  i18n_class: "Example::I18n"
)

Klenod::Build::Plugins::MarkdownPlugin.new(
  component_base_class: "Example::Component",
  factory: "Example::H"
)

A compatible factory accepts a tag or component class, children, and keyword props:

Example::H[tag, *children, **props]

Asset Options

Image defaults can be configured once and overridden by import query strings.

Klenod::Build::Plugins::ImagePlugin.new(
  widths: [320, 640, 960]
)

Google Fonts can use a cache directory for raw Google CSS responses. That avoids fetching CSS again when the exact Google Fonts URL has already been cached.

Klenod::Build::Plugins::GoogleFontsPlugin.new(
  cache_path: "tmp/cache/google_fonts",
  refresh_cache: false,
  adjust_font_fallback: true
)

Build Commands

Build the configured runtime bundle:

bundle exec klenod build

Build an executable bundle:

bundle exec klenod build --executable

Export Graphviz DOT for the built bundle:

bundle exec klenod graph dist/klenod.bundle > graph.dot