Dependencies

A package can use the code of other packages in the library, its dependencies. That's how you share helpers between your own packages, or build on a package someone published.

How dependencies work

• A package declares its dependencies in the dependencies field of its manifest.
• The key of each dependency is the exact name your code imports.
• An import gives you what the dependency's index.js exports, and nothing else.
• Each dependency is locked to one exact version, and that version has to be in the library when the script starts. Starting a script never downloads anything.
• A dependency's code runs in the same script as your package, on the same bot. Its settings and actions show on the bot's page next to yours: see Settings in dependencies.
• The modules of your dependencies count toward the module limits of your script. See Limits.

Depend on a package from your library

1. Make sure the package you need is in your library, at the version you want: install it from the marketplace, as Install from the marketplace shows, or create it yourself.
2. Open your own package's page: click its name in Library Manager.
3. In the Manifest card, open Add an installed package and pick the package, such as chat-tools@1.0.0. A row appears with its name and version.
4. Click Save manifest. A toast says Manifest saved.

Your manifest now holds:

{
  "dependencies": {
    "chat-tools": {
      "version": "1.0.0"
    }
  }
}

And your code can import it by that name:

import { formatChat } from "chat-tools";

Settings in dependencies has a complete example of both packages. When you save, Asterobot checks that a dependency without a URL is installed at that exact version, and refuses the manifest otherwise.

Make it installable for others

When someone installs your package from the marketplace, Asterobot also installs its dependencies, but only those with a URL. A dependency without a URL has to be in their library already, at exactly that version, or the installation fails. So every dependency of a package you publish needs a URL, which means it has to be published too.

1. If the dependency is one of your own packages, publish it first: see Publish on asterobot.net.
2. Install it from the marketplace on your own Asterobot. It gets a marketplace name, shown as Will install as before you install, such as @alice:chat-tools@1.2.0.
3. In your package's Manifest card, add it with Add an installed package, then paste the address of its file page in the third box of that row, the one that reads asterobot.net file URL (optional). If a row with its local name remains, remove it.
4. Change your imports to the marketplace name: import { formatChat } from "@alice:chat-tools";.
5. Click Save manifest, then start your package on a bot to check that it still works.

About the URL:

• It's the address of the file's page on asterobot.net, such as https://asterobot.net/files/file/12-chat-tools/. The file's ID alone, 12, works too.
• The name of the dependency has to match the file. The part before the : must be the publisher Asterobot derives from the file: its author's name, or asterobot for an official file. When they don't match, the installation of your package fails. So a dependency with a local name, such as chat-tools, can't be fetched from a URL.
• Asterobot only uses the URL when your package is installed or updated from the marketplace. Starting your package, importing it from a .zip or installing it with library install never downloads its dependencies.

Choose the version

Once Asterobot has chosen a version during an installation, it writes that exact version in the installed copy's manifest. The package keeps using it from then on, even when the dependency publishes a newer version. A dependency without a URL always needs an exact version.

A range or latest in your own package's manifest stops it from starting on your Asterobot, because Asterobot only loads exact versions. The start fails with a reason starting with resolve package <name>@<version>: dependency "<name>" locked to version "^1.2.0": read package, which Package settings on the bot's Settings tab shows. So use exact versions. Your package then runs for you exactly as it will for the people who install it, and you choose when to move to a newer dependency, by publishing an update of your package.

A version in the name

A dependency's name can end with @ and an exact version, such as chat-tools@1.0.0. That's how one package uses two versions of the same package at once:

{
  "dependencies": {
    "chat-tools@1.0.0": {
      "version": "1.0.0"
    },
    "chat-tools@2.0.0": {
      "version": "2.0.0"
    }
  }
}

import { formatChat as formatChatV1 } from "chat-tools@1.0.0";
import { formatChat } from "chat-tools@2.0.0";

Write the same version in Version as in the name. Asterobot loads the version written in Version: a dependency whose version is only in its name doesn't start. A version in the name that differs from Version is refused when you save, and so is one that isn't an exact version.

Both versions read the same settings, since settings are saved under the package's name. An import can also pick a version with a range, such as chat-tools@^1.0.0, among the versions the script already loads: see Modules and imports.

Dependencies of dependencies

• A dependency declares its own dependencies in its own manifest. They're loaded the same way, and installed with it from the marketplace.
• A package needed by several packages at the same version is loaded once, and its top-level code runs once.
• Different versions of the same package can be loaded side by side, each locked by the package that declared it.
• Every package loaded is checked: an incompatible compatibility range or a checksum that no longer matches, in any dependency, stops the whole script from starting.

When something's wrong

Library Manager lets you remove a package other packages depend on, after a warning listing them. Those packages then fail to start until the version they lock is installed again. Error messages lists the other texts.

Reuse a connection package

Every package that runs on a Full socket bot has to identify the bot on the game server, as Identify and run shows. You can already put that part in a package of your own and depend on it from your other packages.

Next, Compatibility.