diff --git a/README.md b/README.md
index bbb878f..36f3ddd 100644
--- a/README.md
+++ b/README.md
@@ -195,6 +195,9 @@ config:
 ## Dynaimc package scripts
 Packages can be dynamically produced within a component using a dynamic package script named `BUILD.js`. This ECMAScript 5.1 file is executed using [Goja](https://github.com/dop251/goja) and produces a `packages` array which contains the package struct much like they'd exist within the `BUILD.yaml`. For example:
 
+Leeway interacts with the script using global variables, specifically:
+- `args` [input] a JavaScript object containing the build arguments which have explicitely been passed to leeway.
+- `packages` [output] where the script produces an array of package structures akin to those found in a `BUILD.yaml` file.
 
 <table>
 <tr>
@@ -214,7 +217,7 @@ for(let i = 0; i < 5; i++) {
     type: "generic",
     config: {
       commands: [
-        ["echo", "hello from "+i]
+        ["echo", args.msg + ": hello from "+i]
       ]
     }
   });
@@ -244,17 +247,17 @@ pacakages:
   type: generic
   config:
     commands:
-      - ["echo", "hello from 1"]
+      - ["echo", "${msg}: hello from 1"]
 - name: hello-2
   type: generic
   config:
     commands:
-      - ["echo", "hello from 2"]
+      - ["echo", "${msg}: hello from 2"]
 - name: hello-3
   type: generic
   config:
     commands:
-      - ["echo", "hello from 3"]
+      - ["echo", "${msg}: hello from 3"]
 ...
 ```
 
diff --git a/fixtures/pkgs/generic/BUILD.js b/fixtures/pkgs/generic/BUILD.js
index 5298d73..e9592ff 100644
--- a/fixtures/pkgs/generic/BUILD.js
+++ b/fixtures/pkgs/generic/BUILD.js
@@ -9,7 +9,7 @@ for(let i = 0; i < 10; i++) {
     type: "generic",
     config: {
       commands: [
-        ["echo", "hello from "+i]
+        ["echo", args.msg + " hello from "+i]
       ]
     }
   });
diff --git a/pkg/leeway/workspace.go b/pkg/leeway/workspace.go
index 4f0aafc..219f3c0 100644
--- a/pkg/leeway/workspace.go
+++ b/pkg/leeway/workspace.go
@@ -659,7 +659,7 @@ func loadComponent(ctx context.Context, workspace *Workspace, path string, args
 
 	builderFN := strings.TrimSuffix(path, ".yaml") + ".js"
 	if _, err := os.Stat(builderFN); err == nil {
-		addFC, err := runPackageBuilder(builderFN)
+		addFC, err := runPackageBuilder(builderFN, args)
 		if err != nil {
 			return Component{}, err
 		}
@@ -896,7 +896,7 @@ func mergeEnv(pkg *Package, src []string) error {
 	return nil
 }
 
-func runPackageBuilder(fn string) (fc []map[string]interface{}, err error) {
+func runPackageBuilder(fn string, args Arguments) (fc []map[string]interface{}, err error) {
 	defer func() {
 		if err != nil {
 			err = fmt.Errorf("failed to run package builder script at %s: %w", fn, err)
@@ -909,6 +909,10 @@ func runPackageBuilder(fn string) (fc []map[string]interface{}, err error) {
 	}
 
 	vm := goja.New()
+	err = vm.Set("args", args)
+	if err != nil {
+		return nil, err
+	}
 	_, err = vm.RunString(string(prog))
 	if err != nil {
 		return nil, err