feat(typescript): add tutorial for writing policies with typescript/javascript #663

esosaoh · 2025-09-01T04:29:36Z

Description

Fix kubewarden/policy-sdk-js#190

Test

To test this pull request, you can run the following commands:

Additional Information

Tradeoff

Potential improvement

…avascript Signed-off-by: Esosa Ohangbon <[email protected]>

netlify · 2025-09-01T04:29:41Z

✅ Deploy Preview for docs-kubewarden-io ready!

Name	Link
🔨 Latest commit	`5fee132`
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kubewarden-io/deploys/68edc42e777b1900089bfd51
😎 Deploy Preview	https://deploy-preview-663--docs-kubewarden-io.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docs/tutorials/typescript/01-intro-typescript.md

docs/tutorials/typescript/02-scaffold.md

docs/tutorials/typescript/05-e2e-tests.md

docs/tutorials/typescript/02-scaffold.md

docs/tutorials/typescript/01-intro-typescript.md

docs/tutorials/typescript/03-policy-settings.md

docs/tutorials/typescript/04-validation.md

docs/tutorials/typescript/05-e2e-tests.md

docs/tutorials/typescript/01-intro-typescript.md

jhkrug

A minor few suggestions for consideration. From a few sources. I'll have another run through when they have been incorporated. Thank you. Looking good.

docs/tutorials/typescript/02-scaffold.md

docs/tutorials/typescript/05-e2e-tests.md

Co-authored-by: Daria Vladykina <[email protected]> Signed-off-by: Esosa Ohangbon <[email protected]>

esosaoh · 2025-09-18T23:17:28Z

done! @jhkrug

jhkrug

Hi @esosaoh. I think this is the last set of changes. Just all for consistency and taking note of some terminology suggestions from the checkers. Nearly there. Thanks!

docs/tutorials/writing-policies/typescript/01-intro-typescript.md

docs/tutorials/writing-policies/typescript/03-policy-settings.md

docs/tutorials/writing-policies/typescript/04-validation.md

jhkrug

I can't get the tutorial to work at the moment.

docs/tutorials/writing-policies/typescript/01-intro-typescript.md

jhkrug · 2025-09-19T13:28:02Z

docs/tutorials/writing-policies/typescript/02-scaffold.md

+## Testing
+
+Provided the necessary tools are in place, the `make all` command builds the `annotated-policy.wasm` target. The command `make e2e` runs tests using `bats` with `kwctl`.
+


When trying make all I am unsuccessful. Any suggestions?

Using

[~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ‽ node --version v24.0.1 [~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ‽ javy --version javy 6.0.0 [~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ‽ kwctl --version kwctl 1.28.1 Use the `info` command to display system information. [~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ‽ bats --version Bats 1.12.0 [~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ‽

I get:

⸘ git remote -v origin [email protected]:jhkrug/test-js-policy.git (fetch) origin [email protected]:jhkrug/test-js-policy.git (push) [~/projects/suse/kubewarden/testing/test-js-policy][main|u=] ⸘ make clean npm cache clean --force npm warn using --force Recommended protections disabled. rm -f policy.wasm annotated-policy.wasm rm -rf dist dist-ts node_modules package-lock.json [~/projects/suse/kubewarden/testing/test-js-policy][main *|u=] ‽ make all npm install npm warn deprecated [email protected]: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful. npm warn deprecated [email protected]: Glob versions prior to v9 are no longer supported added 399 packages, and audited 400 packages in 14s 59 packages are looking for funding run `npm fund` for details found 0 vulnerabilities npm run build > [email protected] build > npx webpack --config webpack.config.cjs asset bundled.js 5.52 KiB [emitted] [minimized] (name: main) asset types.d.ts 430 bytes [emitted] asset index.d.ts 11 bytes [emitted] ./src/index.ts 3.84 KiB [built] [code generated] ./node_modules/kubewarden-policy-sdk/dist/bundle.js 3.85 KiB [built] [code generated] webpack 5.101.3 compiled successfully in 1530 ms npm install added 1 package, and audited 401 packages in 996ms 59 packages are looking for funding run `npm fund` for details found 0 vulnerabilities javy build dist/bundled.js -C plugin=node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm -o policy.wasm Error: Could not process plugin: Using unsupported legacy plugin API make: *** [Makefile:16: policy.wasm] Error 1 [~/projects/suse/kubewarden/testing/test-js-policy][main|u=]

@esosaoh can you please check and list the needed changes for this to work?

The Javy team has provided documentation with a steps to migrate to v2.0.0 of the javy-plugin-api: https://crates.io/crates/javy-plugin-api

Everything is going to be sorted out once:

update javy plugin policy-sdk-js#234 is merged

a new version of kwctl is tagged to include some fixes

@flavio we need to tag a new version of the sdk when kwctl 1.30 is released

Co-authored-by: John Krug <[email protected]> Signed-off-by: Esosa Ohangbon <[email protected]>

flavio

LGTM, I've left some minor comments.

I think we have to wait for kwctl 1.30 to be out before publishing this doc

flavio · 2025-10-07T09:41:24Z

docs/tutorials/writing-policies/typescript/01-intro-typescript.md

+- **No Node.js APIs**: Standard Node.js modules like `fs`, `http`, or `crypto` aren't available.
+- **Limited standard library**: Only core JavaScript features and explicitly enabled APIs are accessible.
+- **Single-threaded execution**: No support for Web Workers or multi-threading.
+- **STDOUT restrictions**: Writing to STDOUT breaks policies - use STDERR for logging instead.


This is not really a Javy limitation, but rather something that we impose to all our WASI policies. Let's see if we can mention that somewhere else, to avoid confusion

flavio · 2025-10-07T09:42:29Z

docs/tutorials/writing-policies/typescript/01-intro-typescript.md

+
+Writing Kubewarden policies requires:
+
+- **Node.js**: Version 18 or higher.


This unordered list is structured in this way: <name of the dep> - <why do we need it>.

Can we sort that out also for this outlier? The version remark is already provided below, inside of the warning box.

flavio · 2025-10-07T09:46:00Z

docs/tutorials/writing-policies/typescript/02-scaffold.md

+## Testing
+
+Provided the necessary tools are in place, the `make all` command builds the `annotated-policy.wasm` target. The command `make e2e` runs tests using `bats` with `kwctl`.
+


Everything is going to be sorted out once:

update javy plugin policy-sdk-js#234 is merged

a new version of kwctl is tagged to include some fixes

docs/tutorials/writing-policies/typescript/04-validation.md

flavio · 2025-10-07T09:53:26Z

docs/tutorials/writing-policies/typescript/05-e2e-tests.md

+Recall, you need these tools on your development machine:
+
+- **`bats`**: Used to write the tests and automate their execution.
+- **`kwctl`**: CLI tool provided by Kubewarden to run its policies outside of Kubernetes, among other actions. It's covered in [the testing policies section](../../testing-policies/index.md) of the documentation.


reminder: here we will have to tell the user they have to use kwctl 1.30 or later

flavio · 2025-10-07T09:53:47Z

docs/tutorials/writing-policies/typescript/01-intro-typescript.md

+
+- **Node.js**: Version 18 or higher with npm for dependency management.
+- [**`bats`**](https://github.com/bats-core/bats-core): Used to write the tests and automate their execution.
+- [**`kwctl`**](https://github.com/kubewarden/kwctl/releases): CLI tool provided by Kubewarden to run its policies outside of Kubernetes, among other actions. It's covered in [the testing policies section](../../testing-policies/index.md) of the documentation.


reminder: here we will have to tell the user they have to use kwctl 1.30 or later

Co-authored-by: Flavio Castelli <[email protected]> Signed-off-by: Esosa Ohangbon <[email protected]>

jhkrug · 2025-10-15T12:08:13Z

Noting that the documented examples do not work, presumably as using kwctl 1.29 and waiting for 1.30. Or something else?:

[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘ pwd
/home/jhk/tmp/kw-ts-test/js-policy-template
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘ npm install kubewarden-policy-sdk

up to date, audited 400 packages in 983ms

58 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘ ls -l node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm
-rw-r--r-- 1 jhk jhk 1146510 Oct 15 13:59 node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘ cat package.json
{
	"name": "kubewarden-js-policy-template",
	"version": "0.1.0",
	"description": "jhk docs test",
	"main": "src/index.js",
	"scripts": {
		"build": "npx webpack --config webpack.config.cjs",
		"test": "bats e2e.bats",
		"format": "prettier --write .",
		"format:check": "prettier --check ."
	},
	"devDependencies": {
		"@types/jest": "^30.0.0",
		"@types/node": "^24.2.0",
		"jest": "^30.0.5",
		"kubernetes-types": "^1.30.0",
		"prettier": "^3.6.2",
		"ts-jest": "^29.4.1",
		"ts-loader": "^9.5.2",
		"typescript": "^5.8.3",
		"webpack": "^5.x.x",
		"webpack-cli": "^5.1.4"
	},
	"keywords": [
		"kubewarden",
		"policy",
		"kubernetes",
		"wasm",
		"javascript"
	],
	"author": "Kubewarden",
	"repository": {
		"type": "git",
		"url": "https://github.com/jhkrug/js-policy-template.git"
	},
	"bugs": {
		"url": "https://github.com/jhkrug/js-policy-template/issues"
	},
	"dependencies": {
		"kubewarden-policy-sdk": "^0.1.1"
	}
}
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
‽ make all
npm install

up to date, audited 400 packages in 833ms

58 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
npm run build

> [email protected] build
> npx webpack --config webpack.config.cjs

asset bundled.js 5.52 KiB [compared for emit] [minimized] (name: main)
asset types.d.ts 430 bytes [compared for emit]
asset index.d.ts 11 bytes [compared for emit]
./src/index.ts 3.84 KiB [built] [code generated]
./node_modules/kubewarden-policy-sdk/dist/bundle.js 3.85 KiB [built] [code generated]
webpack 5.101.3 compiled successfully in 1420 ms
npm install

up to date, audited 400 packages in 979ms

58 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
javy build dist/bundled.js -C plugin=node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm -o policy.wasm
Error: Could not process plugin: Using unsupported legacy plugin API
make: *** [Makefile:16: policy.wasm] Error 1
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘ make e2e
npm install

up to date, audited 400 packages in 840ms

58 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
npm run build

> [email protected] build
> npx webpack --config webpack.config.cjs

asset bundled.js 5.52 KiB [compared for emit] [minimized] (name: main)
asset types.d.ts 430 bytes [compared for emit]
asset index.d.ts 11 bytes [compared for emit]
./src/index.ts 3.84 KiB [built] [code generated]
./node_modules/kubewarden-policy-sdk/dist/bundle.js 3.85 KiB [built] [code generated]
webpack 5.101.3 compiled successfully in 1361 ms
javy build dist/bundled.js -C plugin=node_modules/kubewarden-policy-sdk/plugin/javy-plugin-kubewarden.wasm -o policy.wasm
Error: Could not process plugin: Using unsupported legacy plugin API
make: *** [Makefile:16: policy.wasm] Error 1
[~/tmp/kw-ts-test/js-policy-template][main *|u=]
⸘

jhkrug · 2025-10-16T13:23:56Z

A bit more. I tried this with kwctl 1.30.0-beta2 and javy 7.0.1

Still have the error from javy:

Error: Could not process plugin: Using unsupported legacy plugin API

I don't think the make command is getting as far as using kwctl

feat(typescript): add tutorial for writing policies with typescript/j…

75e6d6e

…avascript Signed-off-by: Esosa Ohangbon <[email protected]>

esosaoh requested a review from a team as a code owner September 1, 2025 04:29

github-project-automation bot added this to Kubewarden Sep 1, 2025

github-project-automation bot moved this to Pending review in Kubewarden Sep 1, 2025

viccuad assigned esosaoh Sep 1, 2025