Package layout

A package is a small set of JavaScript files with a fixed starting point, index.js, and not every file in it runs when a bot starts the package.

What a package contains

A package with a few files looks like this:

index.js
asterobot.json
lib/chat.js
lib/format.mjs

Asterobot reads nothing else. A JSON data file, an image or a README placed in a package is left out: it's not part of the script, and no script can read it. .js and .mjs files are handled the same way, as ES modules.

A package you create in Library Manager starts with index.js alone. Create a package shows how to add files in the editor.

index.js

index.js is always the entry module, at the root of the package. It can't be renamed, and the editor shows no trash icon for it.

Asterobot looks for three exports in it. The default export is the function called when a bot starts the package, described in The entry function. export const parameters and export const actions declare the settings and the buttons shown on the bot's Settings tab: see Declare settings and Declare actions.

When your package is a dependency of another package, its index.js is also what that package receives when it imports yours. Modules and imports explains how.

Only what index.js reaches runs

When a bot starts the package, Asterobot begins with index.js, follows its import statements, then the imports of those modules, and so on. A file that isn't reached this way is never loaded: its code doesn't run, and a mistake in it doesn't stop the script.

The module limits count the same files, dependencies included:

Past any of them the script doesn't start. Limits lists every limit a script runs under.

Module paths

A module's path is its place inside the package, such as lib/chat.js. Every file you add in the editor follows these rules:

The Add a file dialog checks the path while you type:

The dialog doesn't check the last rule of the first table. A file added as ./lib/chat.js or lib//chat.js appears in the Files list, but Save then fails with Couldn't save. Remove that file and add it again as lib/chat.js.

Zip files and the command line describes how the files of an imported .zip are laid out.

How error messages name your files

Error messages refer to a module by where its package sits in your library: library/, the package name, the version, then the path. The file lib/chat.js of my-first-script 1.0.0 appears as library/my-first-script/1.0.0/lib/chat.js.

A package installed from the marketplace has its name split at the colon: index.js of @alice:mining 1.4.2 is library/@alice/mining/1.4.2/index.js. An inline script, loaded with Inline script, isn't in the library, so its name starts with local/ instead.

asterobot.json

asterobot.json is optional. A new package doesn't have one, and Asterobot only writes the file once there's something to put in it. You don't edit it in the code editor: open the package's own page and use its Manifest card.

The manifest describes every field, and Dependencies shows how to declare one.

Next, The entry function.