Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Loadkit allows you to load arbitrary files within the Lua package path.


$ luarocks install loadkit


etlua is a library that lets you create embedded Lua templates. The result of the template is a function that when called returns the compiled template. Normally you need to load the template and compile the it manually. Let's make it so require is aware of .elua files and returns the compiled template.

Here's an example directory structure:

|-- example.lua
`-- templates
    |-- hello.elua
    `-- my_template.elua

And then we can run:

-- example.lua
local etlua = require "etlua"
local loadkit = require "loadkit"

-- register a handler for .elua files
loadkit.register("elua", function(file)
	return assert(etlua.compile(file:read("*a")))

template = require "templates.my_template"

The functionality of require is unchanged, if the template's module name is required again it would return the cached value, avoiding any additional searching.

What's the point?

A project like MoonScript uses a technique like this to let you load compiled MoonScript as you would load Lua making the integration seamless.

Alternatively, if you've ever wanted to bundle different kinds of file assets inside of a Lua module but were unsure about how to resolve the correct path to open the file you can use this module:

local js_loader = loadkit.make_loader("js")

-- find the actual path of your resource
local fname = js_loader("mymodule.some_script")


The module can be loaded by doing:

local loadkit = require "loadkit"


loadkit.register(ext, handler)

Registers a new loader for the extension ext. The handler is a function that is responsible for creating the module after a matching file has been found.

The handler takes three arguments: file, module_name, file_path.

The file is a freshly opened Lua file object ready for reading. Loadkit will automatically close the file after executing the handler if you don't close it.

module_name is the name of the module that was passed to require. file_path is the path of the file that was opened when searching through the search path.

The return value of the handler determines if the module is loaded. If nil is returned no module is loaded. Any other value returned is used as the value of the module.

success = loadkit.unregister(ext)

Removes a handler that has already been registered. Returns true if found handler to remove.

bool = loadkit.is_registered(ext)

Returns true if a loader has already been registered for the extension ext.

loader = loadkit.make_loader(ext, [handler, package_path])

Makes a loader without manipulating Lua's module loaders. The return value is a function that takes a module name and returns the path of the file that matches that module name if it could be found.

Handler is an optional function that works the same as in register from above. If a handler is specified then its return value is returned by the loader.

package_path defaults to the Lua install's package.path variable.


1.1.0 -- Sun Dec 6 17:50:53 PST 2015

  • make_loader can operate on a custom package path
  • Support lua 5.2 and above (fix unpack reference)


MIT, Copyright (C) 2014 by Leaf Corcoran


Loadkit allows you to load arbitrary files within the Lua package path






No packages published