Skip to content


There are many shards that bundle files into Crystal apps, however Rucksack is a bit unique. It doesn't load them in memory but instead "attaches" them on the binary, allowing you to attach huge files and access them on demand. This, however, requires an extra build step.

Rucksack needs to generate a "pack" that contains all the files you want to bundle. For the sake of automating the process, I wrote a tiny script that recursively goes through a folder (./data by default) and adds all files that match a set of regex checks to the pack:

require "rucksack"


module RucksackHelper
  extend self

  def get_paths(path : String | Path) : Array(Path)
    result = [] of Path do |child|
      child_path = Path[path, child]
        result += get_paths(child_path)
      next unless EXCLUDE.all? { |regex| (regex =~ child_path.expand.to_s).nil? }
      raise "#{child_path} is not a file" unless File.file?(child_path)
      result << child_path

RucksackHelper.get_paths("data/").each do |child|
    rucksack("./" + child.to_s)

Rucksack has a set of env vars that determine its runtime behavior from 0 to 2, 0 being forgiving and 2 being paranoid.

We want to set it to 1 during release builds and leave it as 0 during development. We can achieve it with macros:

{% if !flag?(:debug) || flag?(:release) %}
  ENV["RUCKSACK_MODE"] ||= "1"
{% end %}

We can also run the script with macros so it generates it every time it compiles:


To read a file, all you have to do is pass an IO to rucksack:

css_data =

As mentioned previously, there's an additional step. You need to append the rucksack pack to the binary:

cat .rucksack >> ./my-app"

Keep in mind that it has to be at the end of the binary. When packaging, additional debug info might be appended to the binary and prevent rucksack from working. You can avoid that on flatpak by passing the following build-options:

"build-options": {
	"strip": false,
	"no-debuginfo": true

Rucksack provides additional methods, exceptions and more, please read its README.

Released under a Creative Commons Zero v1.0 Universal License