From 380d9c3179211a7e0ccaca15f6a2b1e5e359cbf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Hanu=C5=A1?= Date: Thu, 2 Jul 2026 00:25:19 +0200 Subject: [PATCH] docs(dockerfile): warn about the npm omit=dev + tsc build trap in TypeScript Actors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The canonical Node.js Dockerfile on this page uses `npm install --omit=dev`, which drops `devDependencies` and thus removes `typescript` from the image. Any TypeScript Actor whose `build` script invokes `tsc` will fail inside the Docker build with `tsc: not found`. This is a recurring pitfall — agents and users both hit it once per new TS Actor, and each retry burns a remote build cycle. Add a `:::warning` callout under the sample Dockerfile with two concrete fixes (multi-stage build, or single-stage with devDeps kept in) and the failure signature so it can be recognized from logs. Co-Authored-By: Claude Opus 4.7 --- .../actor_definition/source_code.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/sources/platform/actors/development/actor_definition/source_code.md b/sources/platform/actors/development/actor_definition/source_code.md index 5e7e73b2a9..092fb8e7de 100644 --- a/sources/platform/actors/development/actor_definition/source_code.md +++ b/sources/platform/actors/development/actor_definition/source_code.md @@ -79,6 +79,32 @@ By copying the `package.json` and `package-lock.json` files and installing depen ::: +:::warning TypeScript Actors and `npm install --omit=dev` + +If your Actor is written in TypeScript and its `package.json` `build` script invokes `tsc` (the TypeScript compiler), the JavaScript template's Dockerfile above will break the build inside the Docker image. `--omit=dev` drops `devDependencies` — including `typescript` — so `tsc` is not on `PATH` when the build script runs, and the whole image build fails with `sh: tsc: not found`. + +For TypeScript projects, either: + +1. Run the build **before** the production install (recommended — smaller final image): + + ```dockerfile + FROM apify/actor-node:24 AS build + COPY --chown=myuser:myuser package*.json ./ + RUN npm ci --include=dev + COPY --chown=myuser:myuser . ./ + RUN npm run build + RUN npm prune --omit=dev + + FROM apify/actor-node:24 + COPY --from=build --chown=myuser:myuser /home/myuser ./ + ``` + +2. Or drop `--omit=dev` from the single-stage install and rely on `npm run build` succeeding because devDependencies are present. + +Symptoms of this trap: the remote build fails during the `RUN npm run build` step with `tsc: not found` (or `Cannot find module 'typescript'`) even though the code compiles locally. Every retry burns a build cycle, so it's worth catching in the Dockerfile itself. + +::: + ### `package.json` The `package.json` file defines the `npm start` command: