From bef0e89e91d1725e2bdaa8408f533aab0a4f3053 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Thu, 23 May 2024 01:28:22 +0200
Subject: [PATCH 1/2] docs: updates to source code doc

ensure style guide compliance
rewrites for clarity & readability
add admonitions
---
 .../actor_definition/source_code.md           | 25 +++++++++++++------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/sources/platform/actors/development/actor_definition/source_code.md b/sources/platform/actors/development/actor_definition/source_code.md
index c8182ebb43..c62bf76548 100644
--- a/sources/platform/actors/development/actor_definition/source_code.md
+++ b/sources/platform/actors/development/actor_definition/source_code.md
@@ -9,13 +9,15 @@ sidebar_position: 4
 
 ---
 
-The Apify Actor's source code placement is defined by its [Dockerfile](./dockerfile.md). If you have created the Actor from one of Apify's [templates](https://apify.com/templates) then it's by convention placed in the `/src` directory.
+The structure and placement of an Apify Actor's source code is defined by its [`Dockerfile`](./dockerfile.md). If you create the Actor from one of Apify's [templates](https://apify.com/templates), the source code by default is placed in the `/src`.
 
-It's completely up to you what language and technologies, including various binaries (Chrome browser, Selenium, Cypress, or any other dependency of your choice) you use in your project. The only requirement is that you have to define the Dockerfile that will build the image for your Actor, including all the dependencies and your source code.
+You have the flexibility to choose any programming language, technologies, and dependencies (such as Chrome browser, Selenium, Cypress, or others) for your projects. The only requirement is to define a Dockerfile that builds the image for your Actor, including all dependencies and your source code.
 
 ## Example setup
 
-Let's take a look at the example JavaScript Actor's source code. The following Dockerfile
+Let's look at the example JavaScript Actor's source code structure.
+
+The following `Dockerfile`:
 
 ```dockerfile
 FROM apify/actor-node:16
@@ -37,11 +39,20 @@ COPY . ./
 CMD npm start --silent
 ```
 
-will build the Actor from the `apify/actor-node:16` image, copy the `package.json` and `package-lock.json` files to the image.
+1. Builds the Actor from the `apify/actor-node:16` base image.
+2. Copies the `package.json` and `package-lock.json` files to the image.
+3. Installs the `npm` packages specified in `packages.json`, omitting development and optional dependencies.
+4. Copies the rest of the source code to the image
+5. Runs the `npm start` command defined in `package.json`
+
+:::note Optimized build cache
+
+By copying the `package.json` and `package-lock.json` files and installing dependencies before the rest of the source code, you can take advantage of Docker's caching mechanism. This approach ensures that dependencies are only reinstalled when the `package.json` or `package-lock.json` files change, significantly reducing build times. Since the installation of dependencies is often the most time-consuming part of the build process, this optimization can lead to substantial performance improvements, especially for larger projects with many dependencies.
+
 
-> We first copy the `package.json`, `package-lock.json` , and install the dependencies before copying the rest of the source code. This way, we can take advantage of Docker's caching mechanism and only install the dependencies when the `package.json` or `package-lock.json` files change. This way, the build process is much faster.
+:::
 
-Then it will install the NPM packages and copy the rest of the source code to the image. Finally, it will run the `npm start` command, which is defined in the `package.json` file:
+The `package.json` file defines the `npm start` command:
 
 ```json
 {
@@ -62,4 +73,4 @@ Then it will install the NPM packages and copy the rest of the source code to th
 }
 ```
 
-So once the Actor starts, the `src/main.js` gets executed.
+When the Actor starts, the `src/main.js` file is executed.

From 95dc84f7f6c7fcc06f8bcf348a73a39a92793af8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Tue, 28 May 2024 22:29:45 +0200
Subject: [PATCH 2/2] restructure & break up code examples

restructured the document adding new headings and ToC elements
broke up the code examples for dockerfile and added explanations
---
 .../actor_definition/source_code.md           | 48 +++++++++++++++++--
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/sources/platform/actors/development/actor_definition/source_code.md b/sources/platform/actors/development/actor_definition/source_code.md
index c62bf76548..17c236171e 100644
--- a/sources/platform/actors/development/actor_definition/source_code.md
+++ b/sources/platform/actors/development/actor_definition/source_code.md
@@ -15,12 +15,14 @@ You have the flexibility to choose any programming language, technologies, and d
 
 ## Example setup
 
-Let's look at the example JavaScript Actor's source code structure.
+To better understand how to structure your Actor's source code, let's take a look at an example for a JavaScript Actor.
 
-The following `Dockerfile`:
+### `Dockerfile`
+
+Here's the complete `Dockerfile`
 
 ```dockerfile
-FROM apify/actor-node:16
+FROM apify/actor-node:20
 
 COPY package*.json ./
 
@@ -39,12 +41,46 @@ COPY . ./
 CMD npm start --silent
 ```
 
-1. Builds the Actor from the `apify/actor-node:16` base image.
+This `Dockerfile` does the following tasks:
+
+1. Builds the Actor from the `apify/actor-node:20` base image.
+
+    ```dockerfile
+    FROM apify/actor-node:20
+    ```
+
 2. Copies the `package.json` and `package-lock.json` files to the image.
-3. Installs the `npm` packages specified in `packages.json`, omitting development and optional dependencies.
+
+    ```dockerfile
+    COPY package*.json ./
+    ```
+
+3. Installs the npm packages specified in package.json, omitting development and optional dependencies.
+
+    ```dockerfile
+    RUN npm --quiet set progress=false \
+        && npm install --omit=dev --omit=optional \
+        && echo "Installed NPM packages:" \
+        && (npm list --omit=dev --all || true) \
+        && echo "Node.js version:" \
+        && node --version \
+        && echo "NPM version:" \
+        && npm --version \
+        && rm -r ~/.npm
+    ```
+
 4. Copies the rest of the source code to the image
+
+    ```dockerfile
+    COPY . ./
+    ```
+
 5. Runs the `npm start` command defined in `package.json`
 
+    ```dockerfile
+    CMD npm start --silent
+    ```
+
 :::note Optimized build cache
 
 By copying the `package.json` and `package-lock.json` files and installing dependencies before the rest of the source code, you can take advantage of Docker's caching mechanism. This approach ensures that dependencies are only reinstalled when the `package.json` or `package-lock.json` files change, significantly reducing build times. Since the installation of dependencies is often the most time-consuming part of the build process, this optimization can lead to substantial performance improvements, especially for larger projects with many dependencies.
@@ -52,6 +88,8 @@ By copying the `package.json` and `package-lock.json` files and installing depen
 
 :::
 
+### `package.json`
+
 The `package.json` file defines the `npm start` command:
 
 ```json