Script directives

📘

Before reading this guide

If you don't know how to create and manage custom scripts on Phantombuster, you might find our article on how to manage your custom scripts useful.

Script directives

All Phantombuster scripts must start with a few lines called script directives. They let you configure the environment in which the script will run.

Here is a typical example:

// Phantombuster configuration {
"phantombuster dependencies: lib-Foo.js"
"phantombuster flags: save-folder"
// }

Each line is a directive and will be explained below. Their order is of no importance.

Images ("phantom image")

The phantom image is one of the most important script directives. It allows you to select which NPM modules and binaries are bundled with your agent's script. It is mandatory to specify an image.

"phantom image: web-node:v1"

We listed available packages & modules in the next tutorial.

Writing your own modules ("phantombuster dependencies")

Sometimes your custom script becomes big and the size of its source code makes it difficult to understand and maintain.

That's the time when you need to split your code into multiple files. Phantombuster allows you to create modules that you can require() into your agent's code.

📘

How to create a new module

To create a new module, log in, go to your developer page, click "Create script" and enter the desired name of your module (module names should be prefixed with lib-).

Example of a simple module:

module.exports = {
  foo: () => {
  	console.log("bar");
  }
}

Example of an agent script using the module shown above:

"phantom image: web-node:v1"
"phantombuster dependencies: lib-Foo.js, lib-OtherModule.js"

require("./lib-Foo").foo() // outputs "bar"

As you can see, you must indicate on which modules your agent's script is dependent before being able to require() them.

When calling require(), do not forget to add ./ in front of the name of your module. If your agent's script has multiple dependencies, specify a list of module names separated by commas.

The dependency list is case sensitive and must contain the exact modules names including their extension.

Flags ("phantombuster flags")

The phantombuster flags directive allows you to enable miscellaneous features of the Phantombuster platform.

For now there is only one flag named save-folder which makes sure the files you have downloaded to your agent's disk get saved to your account's cloud storage before the script terminates.

"phantombuster flags: save-folder"

This lets you write your scripts without bothering to remember to call buster.saveFolder() at the end.

In what environment do my scripts run?

Your scripts are executed in Linux containers (they are similar to very light virtual machines).

Available to you are a few gigabytes of RAM, a few gigabytes of hard disk space and a fast internet connection. These are temporary resources that are freed right after your agent finishes its job.

What's important to know is that files written on your agent's disk will be lost when it exits. To keep files, save them to your persistent storage using our BusterJS library or by adding the line "phantombuster flags: save-folder" at the top of your script.

More technical details (for the nerds):

• The container engine is Docker
• Containers are running Debian
• Agents always start in /home/phantom/agent which is empty
• Agents run under the user phantom

📘

TypeScript

We wrote a complete guide on how to code a custom script using TypeScript!