Remote Imports
Remote imports let a v2 script reuse small JavaScript helper files or render a template file stored outside Kicklet. Use them for shared helpers that are easier to version in GitHub, Gist, or Pastebin than in every command.
Remote template files use Kicklet's v2 template source syntax. See Template Syntax Reference for expressions, script blocks, conditions, loops, and reusable blocks.
importScript(...) and importTemplate(...) are only available in engine v2 script code. Engine v1 cannot load remote JavaScript or remote template files.
Remote imports execute code that is fetched during template execution, so they are available for premium accounts only.
Kicklet only loads from known raw-code hosts. GitHub URLs should use raw.githubusercontent.com, Gist URLs should use gist.githubusercontent.com, and Pastebin URLs should use pastebin.com/raw/.... A URL without a hash follows whatever that URL returns at runtime. For stable production commands, use a commit-pinned URL and pass the expected SHA-256 hash.
Import a JavaScript file
Use importScript(url, options) to load and run a remote JavaScript file in the current v2 script. The imported file can define functions that the rest of the script calls.
The example repository contains src/scripts/greeting.js. It defines sendRemoteGreeting(name), which sends a chat message.
This example follows the current main branch. It is convenient while developing, but the executed code can change when the branch changes.
importScript(
"https://raw.githubusercontent.com/kicklet-app/code-examples/main/src/scripts/greeting.js",
);
sendRemoteGreeting(sender.username);
This version pins the URL to commit 7b78b4a76771f180e8be57bde171ad76a01b5938 and verifies the downloaded file against its SHA-256 hash. If the content does not match, execution stops.
importScript(
"https://raw.githubusercontent.com/kicklet-app/code-examples/7b78b4a76771f180e8be57bde171ad76a01b5938/src/scripts/greeting.js",
{
commit: "7b78b4a76771f180e8be57bde171ad76a01b5938",
sha256: "3f5e5e2753329921058955958423e1de466f8a6ae897aa731813e9e54b9dd675",
},
);
sendRemoteGreeting(sender.username);
Import a template file
Use importTemplate(url, data, options) from a v2 script when the remote file is a template, not JavaScript. The function renders the remote template with the provided data object and returns the rendered text. The remote file itself uses the syntax described in Template Syntax Reference.
The second argument is the data object for that one imported template render. Inside the remote template, those values are available below data. For example, passing {name: sender.username, item: "VIP Highlight"} lets the template read {{data.name}} and {{data.item}}.
The imported template still runs in the normal Kicklet context. It can use the passed data values and helpers like points, channel, stats, or random in the same render.
The example repository contains src/templates/greeting.tmpl:
Hello {{data.name}}!
You currently have {{points.get(data.name)}} {{points.currency()}}.
It expects data.name from the caller and reads the viewer's points through the normal points API.
This example renders the template from the current main branch, then sends the rendered text as a chat message.
const text = importTemplate(
"https://raw.githubusercontent.com/kicklet-app/code-examples/main/src/templates/greeting.tmpl",
{ name: sender.username },
);
async.messages.send(text);
You can pass any JSON-like data the template needs. Keep data explicit so the remote template does not have to guess which command, shop item, or viewer it is rendering for.
const templateData = {
name: sender.username,
commandName: command.name,
currency: points.currency(),
};
const text = importTemplate(
"https://raw.githubusercontent.com/kicklet-app/code-examples/main/src/templates/greeting.tmpl",
templateData,
);
async.messages.send(text);
This version pins the template URL to commit 7b78b4a76771f180e8be57bde171ad76a01b5938 and verifies the exact downloaded bytes with SHA-256 before rendering.
const text = importTemplate(
"https://raw.githubusercontent.com/kicklet-app/code-examples/7b78b4a76771f180e8be57bde171ad76a01b5938/src/templates/greeting.tmpl",
{ name: sender.username },
{
commit: "7b78b4a76771f180e8be57bde171ad76a01b5938",
sha256: "dcd6d6bb69c10862ff8dbc755c59527cfd4ed25602013300bbb931cc1abf3db3",
},
);
async.messages.send(text);
Options
sha256 is optional, but recommended for commands that should not silently run changed remote code. The value can be passed either as a plain hex digest or as sha256:<digest>.
commit is optional and currently used as a safety check for GitHub raw URLs. When it is passed, the URL must contain the same commit. This avoids accidentally combining a trusted hash option with a moving branch URL.
Remote files are intentionally small. Kicklet refuses responses above the configured remote-code size limit before compiling or executing them.
Caching and execution time
Docs examples and editor/tester executions do not write remote-import bytecode to the shared cache. Their execution time therefore includes fetching and compiling the remote file every time.
In live Kick chat, the first execution of a command also has to fetch, verify, and compile the remote script or template. After that, Kicklet caches the compiled code for the same URL and options. The default cache TTL is 1 hour, and entries may be evicted earlier when cache memory is needed.
URLs that point to a moving branch like main can keep using the previously cached compiled code until the cache entry expires or is evicted, even if the file changed in GitHub. The response size limit is checked when Kicklet fetches the remote file, but a cache hit does not fetch the file again.
Use a commit-pinned URL with sha256 when a command should run one exact file version. To roll out a new version, update the command to the new commit URL and matching hash.