Dependencies

Use another package's code from yours: declare the dependency, choose its version, make it installable for others, import it, and fix what Asterobot reports.

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.
• @asterobot:base is the exception: your package always loads the newest version of base in the library that the running Asterobot can run, whatever version it locked, and Asterobot keeps that version up to date by itself. See Base is always the newest.
• 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, except base: see Base is always the newest. 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.

Base is always the newest

Asterobot installs @asterobot:base by itself and keeps it up to date: at startup, every hour, after the person signs in to asterobot.net and after base is removed, it downloads base's current version when the library doesn't have it. So every package plays the same base, its newest:

• A dependency named @asterobot:base loads the newest version of base in the library whose compatibleVersion accepts the running Asterobot, whatever version the manifest locks. The locked version only counts when no version of base can run, and the start then fails with its reason.
• A bot set to play @asterobot:base itself plays that same version, whatever version it was set to, and its settings are that version's. The Studio's palette shows that version's blocks too.
• Installing a package from the marketplace, or saving a manifest, accepts whatever version of base the library has: an older locked version is never downloaded, and is never required to be installed.
• A dependency whose name carries its own version, such as @asterobot:base@0.0.3, loads exactly that version, as described below.
• Still declare base in your dependencies, with an exact version and base's URL, https://asterobot.net/files/file/5-base/: that's what makes your code import it.
• A script loads its packages when it starts, so a running script keeps the base it started with until it's stopped and played again.
• After each check, Asterobot deletes the versions of base older than the one that runs, except a version a package imports by its exact version (see below). A newer version this Asterobot can't run stays, for the update that will run it.

Base keeps the exports it has, so a package written against an older version runs on the newer one.

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.