Single JavaScript file actors are being deprecated

Josef Válek
Josef Válek
Table of Contents

We will automatically convert single-file actors to multi-file and keep them working. If you are using Apify API to update the code of your single-file actors or create new ones, then you will have to update your API integration following the instructions below.

We've decided to say goodbye to single-file JavaScript actors, but don't worry, we will automatically convert them to multi-file.

TL;DR: We will automatically convert single-file actors to multi-file and keep them working. If you are using the Apify API to update the code of your single-file actors or create new ones, then you will have to update your API integration by following the instructions below.

Why deprecate single-file JavaScript actors?

Because they brought only pain and frustration to developers 😫

The main problem with single-file actors is the lack of package.json and package-lock.json files so that the versions of your dependencies can (and do) vary in-between builds.

Single-file actors were built in such a way that they used:

  • apify and apify-client packages in the version baked into the base docker image
  • all other packages required  in source code in the latest version

When you rebuild the actor and a new version of the package you were using contained some backward-compatibility breaks, your actor would break even if you did not change a single line in the source code.

There was no way around this.

Say goodbye to single-file JavaScript actors and hello to multi-file actors
Say goodbye to single-file JavaScript actors and hello to multi-file actors

What will happen to existing single-file actors?

They will be converted to their multi-file equivalents. The multi-file version will contain the following files:

  • Dockerfile - based on the original base docker image
  • main.js - the original source code
  • package.json - containing apify and apify-client in latest version (or a specific version if you use a base docker image that is deprecated) and all other required packages in latest version.
Source of actor before and after conversion to multi-file
Source of actor before and after conversion to multi-file

This means that if your actor breaks due to some package version incompatibility, you can now pin its version in package.json.

What should I do with my existing actors?

You can convert the existing single-file actors manually in Apify Console, in the source tab of your actor. The conversion does not influence existing builds in any way, the converted files are only used for new builds.

You will see a message in Apify Console warning you to convert your single-file actors
You will see a message in Apify Console warning you to convert your single-file actors

We'll convert all the remaining actors by June 1, 2022.

What should I do when using API to create or update single-file actors?

Switch to multi-file actors before June 1, 2022. After that, it will no longer be possible to create single-file actors.

Instead of a single-file version with sourceType set to SOURCE_CODE, some sourceCode and baseDockerImage, use version with sourceType set to SOURCE_FILES and add array sourceFiles, which should contain Dockerfile, package.json (if needed) and main.js described above.

You can either create those files on your own or convert existing single-file actors manually in UI, read the converted version via API and then use sourceFiles when creating similar new actors - just change the content of main.js (and package.json if you need to add some packages).

Minimal example

When you create single-file actors via API, you make a POST request to https://api.apify.com/v2/acts with payload such as this:

{
  "name": "my-single-file-actor-001",
  "versions": [
    {
      "versionNumber": "0.0",
      "sourceType": "SOURCE_CODE",
      "buildTag": "latest",
      "baseDockerImage": "apify/actor-node",
      "sourceCode": "console.log('Hello world!');"
    }
  ]
}

For multi-file actors, you have to list all the files that make up your actor in the payload:

{
  "name": "my-multi-file-actor-001",
  "versions": [
    {
      "versionNumber": "0.0",
      "sourceType": "SOURCE_FILES",
      "buildTag": "latest",
      "sourceFiles": [
        {
          "name": "Dockerfile",
          "format": "TEXT",
          "content": "FROM apify/actor-node\nCOPY . .\n"
        },
        {
          "name": "main.js",
          "format": "TEXT",
          "content": "console.log('Hello world!');"
        }
      ]
    }
  ]
}

If you need to install some additional packages, don't forget to add package.json and RUN npm install in the Dockerfile.

See the version object documentation for details.

If you have any problems or questions about the conversion, contact our support on chat in Apify Console.



Great! Next, complete checkout for full access to Apify
Welcome back! You've successfully signed in
You've successfully subscribed to Apify
Success! Your account is fully activated, you now have access to all content
Success! Your billing info has been updated
Your billing was not updated