Skip to content

feat: deprecate pkg binary, require Node.js >= 20 as prerequisite #1578

@Mossaka

Description

@Mossaka

Context

Depends on #1577 (esbuild bundle distribution).

Once the esbuild bundle has been validated in production for 2-3 releases, we should deprecate and eventually remove the pkg binary path.

Motivation

  • pkg is unmaintained — last release was 2023, no path to Node 20+ targets
  • Node 18 EOL — pkg binaries ship a runtime that's been EOL since April 2025
  • Narrow use case — the only scenario where the pkg binary matters is a machine with Docker + iptables but without Node.js >= 20, which is increasingly rare
  • Maintenance burden — carrying two distribution formats, testing both paths, documenting both

Proposal

Make AWF's runtime requirements: Docker + iptables + Node.js >= 20 (no bundled runtime).

Phased approach

Phase 1 (immediate, after #1577 ships):

  • Add deprecation warning to install.sh when the pkg binary fallback is used
  • Add deprecation notice to release notes
  • Monitor: are any users hitting the pkg fallback path?

Phase 2 (after 2-3 releases):

  • Remove pkg from package.json and devDependencies
  • Remove pkg binary build steps from release.yml
  • Simplify install.sh to only download the bundle (fail with clear error if Node.js not found)
  • Update docs to list Node.js >= 20 as a prerequisite alongside Docker

Changes (Phase 2)

  • package.json — Remove pkg config block (lines 83-95), remove pkg dependency
  • .github/workflows/release.yml — Remove pkg binary build steps, keep only esbuild bundle
  • install.sh — Remove platform-specific binary logic, download only awf-bundle.js, error if no Node.js
  • scripts/ci/smoke-test-binary.ts — Remove or convert to bundle-only smoke test
  • README.md / docs/ — Update prerequisites to include Node.js >= 20

Risks

  • Self-hosted runners without Node.js would need to add it (one apt install nodejs or setup-node action step)
  • The deprecation period (2-3 releases) gives time to surface any users relying on the standalone binary

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions