From d56d86aab47843a631737c0021600c6318d89a89 Mon Sep 17 00:00:00 2001 From: szaganek Date: Tue, 11 Aug 2026 13:04:22 +0200 Subject: [PATCH 1/3] docs: Rewrite quickstart on local development --- .../actors/development/quick-start/index.mdx | 8 +- .../actors/development/quick-start/locally.md | 152 ------------------ .../development/quick-start/locally.mdx | 122 ++++++++++++++ src/utils/quick-start-prompt.js | 14 +- 4 files changed, 133 insertions(+), 163 deletions(-) delete mode 100644 sources/platform/actors/development/quick-start/locally.md create mode 100644 sources/platform/actors/development/quick-start/locally.mdx diff --git a/sources/platform/actors/development/quick-start/index.mdx b/sources/platform/actors/development/quick-start/index.mdx index 6e4b4d5c5d..409eda77c8 100644 --- a/sources/platform/actors/development/quick-start/index.mdx +++ b/sources/platform/actors/development/quick-start/index.mdx @@ -15,13 +15,13 @@ There's more than one way to build an Actor. Pick the path that fits how you wor - -## What you'll learn - -This guide walks you through the full lifecycle of an Actor. You'll start by creating and running it locally with the Apify CLI, then learn to configure its input and data storage. Finally, you will deploy the Actor to the Apify platform, making it ready to run in the cloud. - -### Prerequisites - -- [Node.js](https://nodejs.org/en/) version 16 or higher with `npm` installed on your computer. -- The [Apify CLI](/cli/docs/installation) installed. -- Optional: To deploy your Actor, [sign in](https://console.apify.com/sign-in). - -### Step 1: Create your Actor - -Use the Apify CLI to create a new Actor: - -```bash -apify create -``` - -The CLI will ask you to: - -1. Name your Actor (e.g., `your-actor-name`) -2. Choose a programming language (`JavaScript`, `TypeScript`, or `Python`) -3. Select a development template - :::info Explore Actor templates - - Browse the [full list of templates](https://apify.com/templates) to find the best fit for your Actor. - - ::: - -The CLI will: - -- Create a `your-actor-name` directory with boilerplate code -- Install all project dependencies - -Now, you can navigate to your new Actor directory: - -```bash -cd `your-actor-name` -``` - -### Step 2: Run your Actor - -Run your Actor with: - -```bash -apify run -``` - -You'll see output similar to this in your terminal: - -```bash -INFO System info {"apifyVersion":"3.4.3","apifyClientVersion":"2.12.6","crawleeVersion":"3.13.10","osType":"Darwin","nodeVersion":"v22.17.0"} -Extracted heading { level: 'h1', text: 'Your full‑stack platform for webΒ scraping' } -Extracted heading { level: 'h3', text: 'TikTok Scraper' } -Extracted heading { level: 'h3', text: 'Google Maps Scraper' } -Extracted heading { level: 'h3', text: 'Instagram Scraper' } -``` - -As you can see in the logs, the Actor extracts text from a web page. The main logic lives in `src/main.js`. Depending on your template, this file may be `src/main.ts` (TypeScript) or `src/main.py` (Python). - -In the next step, we’ll explore the results in more detail. - -### Step 3: Explore the Actor - -Let's explore the Actor structure. - -#### The `.actor` folder - -The `.actor` folder contains the Actor configuration. The `actor.json` file defines the Actor's name, description, and other settings. Find more info in the [actor.json](https://docs.apify.com/actors/development/actor-definition/actor-json) definition. - - -#### Actor's `input` - -Each Actor accepts an `input object` that tells it what to do. The object uses JSON format and lives in `storage/key_value_stores/default/INPUT.json`. - -:::info Edit the schema to change input - -To change the `INPUT.json`, edit the `input_schema.json` in the `.actor` folder first. - -This JSON Schema validates input automatically (no error handling needed), powers the Actor's user interface, generates API docs, and enables smart integration with tools like Zapier or Make by auto-linking input fields. - -::: - -Find more info in the [Input schema](/actors/development/actor-definition/input-schema) documentation. - -#### Actor's `storage` - -The Actor system provides two storage types for files and results: [key-value](/storage/key-value-store) store and [dataset](/storage/dataset). - -##### Key-value store - -The key-value store saves and reads files or data records. Key-value stores work well for screenshots, PDFs, or persisting Actor state as JSON files. - -##### Dataset - -The dataset stores a series of data objects from web scraping, crawling, or data processing jobs. You can export datasets to JSON, CSV, XML, RSS, Excel, or HTML formats. - -#### Actor's `output` - -You define the Actor output using the Output schema files: - -- [Dataset Schema Specification](/storage/dataset-schema) -- [Key-value Store Schema Specification](/storage/key-value-store-schema) - -The system uses this to generate an immutable JSON file that tells users where to find the Actor's results. - -### Step 4: Deploy your Actor - -Let's now deploy your Actor to the Apify platform, where you can run the Actor on a scheduled basis, or you can make the Actor public for other users. - -1. Login first: - - ```bash - apify login - ``` - - :::info Your Apify token location - - After you successfully login, your Apify token is stored in `~/.apify/auth.json`, or `C:\Users\\.apify` based on your system. - - ::: - -2. Push your Actor to the Apify platform: - - ```bash - apify push - ``` - -### Step 5: It's time to iterate! - -Good job! πŸŽ‰ You're ready to develop your Actor. You can make changes to your Actor and implement your use case. - -## Next steps - -- Visit the [Apify Academy](/academy) to access a comprehensive collection of tutorials, documentation, and learning resources. -- To understand Actors in detail, read the [Actor Whitepaper](https://whitepaper.actor/). -- Check [Continuous integration](/actors/development/deployment/continuous-integration) documentation to automate your Actor development process. -- After you finish building your first Actor, you can [share it with other users and even monetize it](/actors/publishing). diff --git a/sources/platform/actors/development/quick-start/locally.mdx b/sources/platform/actors/development/quick-start/locally.mdx new file mode 100644 index 0000000000..a9e169a1ba --- /dev/null +++ b/sources/platform/actors/development/quick-start/locally.mdx @@ -0,0 +1,122 @@ +--- +title: Develop Actors locally +sidebar_label: Develop locally +sidebar_position: 1 +description: Create your first Actor locally using the Apify CLI, configure its input and storage, then deploy it to the Apify platform to run in the cloud. +slug: /actors/development/quick-start/locally +pagination_next: null +pagination_prev: null +--- + +import PromptButton from "@site/src/components/PromptButton"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + + +To develop Actors locally, use the [Apify CLI](/cli/docs). You can use your own code editor and version control system. The CLI simulates the Apify environment so you can test the Actor before you deploy it. + +## Before you start + +- [Install the Apify CLI](/cli/docs/installation). +- [Create an Apify account](https://console.apify.com/sign-in). + +## Create and run an Actor + +To create and run your new Actor locally, use the following commands: + +```bash +apify create my-actor-name +cd my-actor-name +apify run +``` + +For a detailed tutorial, see the [Apify CLI quick start](/cli/docs/quick-start). + +--- + + + +## Explore the Actor + +The `apify create` command creates a directory with boilerplate code. The exact structure and contents of the directory depend on the template that you choose. + + + + ```text + my-actor/ + β”œβ”€β”€ .actor/ + β”‚ β”œβ”€β”€ actor.json # Actor configuration + β”‚ β”œβ”€β”€ input_schema.json + β”‚ β”œβ”€β”€ output_schema.json + β”‚ └── dataset_schema.json + β”œβ”€β”€ src/ + β”‚ └── main.js # Main logic of the Actor + β”œβ”€β”€ storage/ # Local storage + β”œβ”€β”€ Dockerfile # Container image definition + β”œβ”€β”€ README.md + β”œβ”€β”€ AGENTS.md # Instructions for coding agents + └── package.json + ``` + + + ```text + my-actor/ + β”œβ”€β”€ .actor/ + β”‚ β”œβ”€β”€ actor.json # Actor configuration + β”‚ β”œβ”€β”€ input_schema.json + β”‚ β”œβ”€β”€ output_schema.json + β”‚ └── dataset_schema.json + β”œβ”€β”€ my_actor/ + β”‚ └── main.py # Main logic of the Actor + β”œβ”€β”€ storage/ # Local storage + β”œβ”€β”€ Dockerfile # Container image definition + β”œβ”€β”€ README.md + β”œβ”€β”€ AGENTS.md # Instructions for coding agents + └── requirements.txt + ``` + + + +### `.actor` directory + +The `.actor` directory contains the Actor configuration: + +- The [`actor.json`](/actors/development/actor-definition/actor-json) file defines the Actor's name, description, version, and other settings. It links your local development project to an Actor on the Apify platform. +- The [`input_schema.json`](/actors/development/actor-definition/input-schema) file defines the input parameters for an Actor. +- The [`output_schema.json`](/actors/development/actor-definition/output-schema) file specifies where an Actor stores its output and defines templates for accessing that output. +- The [`dataset_schema.json`](/storage/dataset-schema) file defines the structure and presentation of data produced by an Actor. + +### Actor's input + +Each Actor accepts an `input` object that tells it what to do. The object uses JSON format and lives in `storage/key_value_stores/default/INPUT.json`. + +Local input comes from `INPUT.json` that you can edit manually. On the platform, input comes from the form generated by [`input_schema.json`](/actors/development/actor-definition/input-schema). Change the schema first, then update `INPUT.json` to match. Otherwise, the Actor works locally but fails validation on the platform. + +### Actor's output + +The [`output_schema.json`](/actors/development/actor-definition/output-schema) file defines where the Actor stores its results and how to access them. It builds on the [dataset schema](/storage/dataset-schema) and the [key-value store schema](/storage/key-value-store-schema). + +### Actor's storage + +The `storage` directory holds the data your Actor reads and writes when it runs locally. It mirrors the three storage types the Apify platform creates for every run: + +| Path | Platform equivalent | Contents | +| --- | --- | --- | +| `storage/datasets/default/` | The run's default [dataset](/storage/dataset) | Structured results, one JSON file per item. | +| `storage/key_value_stores/default/` | The run's default [key-value store](/storage/key-value-store) | Files and data records. Works well for screenshots, PDFs, or persisting Actor state as JSON files. | +| `storage/request_queues/default/` | The run's default [request queue](/storage/request-queue) | Requests the Actor enqueued. | + +Local storage persists between runs. To clear the default storages, run `apify run --purge`. + +## Deploy to the Apify platform + +There are two ways to deploy your Actor code to the Apify platform: + +- Run the `apify push` command. It uploads the directory and starts a build. To control to which version the build belongs, use `--version` and `--build-tag` flags. +- Host your Actor's source code in a [Git repository](/actors/development/deployment/source-types#git-repository). Then, to rebuild the Actor on every push, add a webhook. For details, see [GitHub integration](/integrations/github#build-automatically-on-every-push). + +## Next steps + +- For a full list of commands, see the [Apify CLI command reference](/cli/docs/reference). +- For Actor configuration details, see [Actor definition](/actors/development/actor-definition). +- To automate your Actor development process, see [Continuous integration](/actors/development/deployment/continuous-integration). diff --git a/src/utils/quick-start-prompt.js b/src/utils/quick-start-prompt.js index 3bd0f01914..e62631d242 100644 --- a/src/utils/quick-start-prompt.js +++ b/src/utils/quick-start-prompt.js @@ -1,11 +1,11 @@ export const QUICK_START_PROMPT = `Follow this step-by-step workflow:: -**Step 1: Verify Prerequisites** +**Step 1: Verify prerequisites** First, verify the user's environment by running these commands: \`\`\`bash -node --version # Requires Node.js 16 or higher +node --version # Requires Node.js 20 or higher npm --version apify --version # Check if Apify CLI is already installed \`\`\` @@ -17,9 +17,9 @@ If any prerequisites are missing, guide the user through installation before pro npm install -g apify-cli \`\`\` -**Step 3: Create a New Actor** +**Step 3: Create a new Actor** -**Note for AI Tools**: If you're an AI assistant that cannot run interactive commands (like the Gemini CLI), inform the user that the \`apify create\` command requires interactive input and cannot be executed automatically. Suggest they run this workflow in tools that support interactive commands like Cursor, or GitHub Copilot. +**Note for AI tools**: If you're an AI assistant that cannot run interactive commands (like the Gemini CLI), inform the user that the \`apify create\` command requires interactive input and cannot be executed automatically. Suggest they run this workflow in tools that support interactive commands like Cursor, or GitHub Copilot. Explain that this will prompt for actor name and template selection. @@ -29,13 +29,13 @@ apify create Direct users to explore templates at https://apify.com/templates. -**Step 4: Navigate to the Actor Directory** +**Step 4: Navigate to the Actor directory** \`\`\`bash cd [actor-name] # Use the actual name they chose in step 3 \`\`\` -**Step 5: Run the Actor Locally** +**Step 5: Run the Actor locally** Explain that this will run the actor locally. @@ -43,7 +43,7 @@ Explain that this will run the actor locally. apify run \`\`\` -**Step 6: Next Steps** +**Step 6: Next steps** Explain that the user can deploy the actor to Apify, but they first need to log in to Apify: From 693849c8758949d8dd0f17a22bd91be6847f7452 Mon Sep 17 00:00:00 2001 From: szaganek Date: Tue, 11 Aug 2026 13:06:22 +0200 Subject: [PATCH 2/3] update description --- sources/platform/actors/development/quick-start/locally.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/quick-start/locally.mdx b/sources/platform/actors/development/quick-start/locally.mdx index a9e169a1ba..761e5edc95 100644 --- a/sources/platform/actors/development/quick-start/locally.mdx +++ b/sources/platform/actors/development/quick-start/locally.mdx @@ -2,7 +2,7 @@ title: Develop Actors locally sidebar_label: Develop locally sidebar_position: 1 -description: Create your first Actor locally using the Apify CLI, configure its input and storage, then deploy it to the Apify platform to run in the cloud. +description: Get started with the Apify CLI to develop Actors locally. slug: /actors/development/quick-start/locally pagination_next: null pagination_prev: null From 7aec6c7746fa6449ef28e55516e8ef5823be84bd Mon Sep 17 00:00:00 2001 From: szaganek Date: Mon, 17 Aug 2026 13:24:54 +0200 Subject: [PATCH 3/3] Hide prompt --- sources/platform/actors/development/quick-start/locally.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sources/platform/actors/development/quick-start/locally.mdx b/sources/platform/actors/development/quick-start/locally.mdx index 761e5edc95..731cbe2367 100644 --- a/sources/platform/actors/development/quick-start/locally.mdx +++ b/sources/platform/actors/development/quick-start/locally.mdx @@ -32,10 +32,6 @@ apify run For a detailed tutorial, see the [Apify CLI quick start](/cli/docs/quick-start). ---- - - - ## Explore the Actor The `apify create` command creates a directory with boilerplate code. The exact structure and contents of the directory depend on the template that you choose.