Examples

Examples

The examples/ directory of the 3va repository holds 13 small projects. Each one shows a different facet of the runtime: what it does, how to run it, what you should see, and what to watch out for.

Everything here was run against 3va 2.9.0 on Linux, non-interactively (no TTY). See the docs site Examples section for the full walkthrough of each project with real output.

git clone https://github.com/OdinoCano/3va
cd 3va/examples/01-hello-world
3va run app.js

---

Index

#	Example	What it shows	Command
01	Hello World	The simplest script, zero permissions	3va run app.js
02	HTTP Server	Node http + --allow-net	3va run server.js --allow-net=localhost
03	File Operations	Scoped --allow-read / --allow-write	3va run app.js --allow-read=./data.json --allow-write=./data.json
04	TypeScript	Running .ts with no build step	3va run math.ts
05	npm Packages	3va install + package.json grants	3va install --allow-net=registry.npmjs.org
06	Dev Server	On-demand ESM serving + full-page HMR	3va dev --port 3000
07	Test Runner	Jest-compatible tests and snapshots	3va test
08	Bundler	Multi-file → one self-contained file	3va bundle src/index.js -o dist/bundle.js --minify
09	Process Manager	Background daemon + auto-restart	3va start server.js --name demo-api
10	Permissions	Deny-by-default, grant by grant	3va run demo.js
11	React Native	Run and test the shared TS logic of an RN app	3va test
12	Expo	Expo helpers and tooling scripts	3va run src/index.ts --allow-read=./src
13	Tauri	3va as the frontend toolchain of a Tauri app	3va dev / 3va bundle / 3va test
14 †	Native addon	A real .node addon (bcrypt) through Node-API and --allow-ffi	3va run app.js --allow-ffi ...

† Example 14 needs 2.12.1 or newer: on 2.12.0 the asynchronous call never prints its result and addons that define classes can crash on load.

Suggested order

1. 01 hello world → 03 files → 02 HTTP server (the two most common capabilities)
2. 04 if you write TypeScript
3. 07 tests, 05 dependencies
4. 06 develop with HMR, 08 ship a bundle, 09 run it as a daemon
5. 10 to understand why everything above needs the flags it needs
6. 11 · 12 · 13 if you work with a native app framework

---

Things that apply to every example

These came up again and again while running the examples, so they are collected here once:

• Importing your own files needs --allow-read. The entry file is always readable, but every module it imports is a file read. A single-file script (01, 04) needs no flags; a script that imports ./todos.ts fails with Permission denied: --allow-read=…/src/todos.ts is required until you pass --allow-read=./src. The same goes for require() of packages in node_modules (05).
• Denials look different depending on the API. A synchronous fs call throws (EACCES, or an uncaught Permission denied: --allow-… is required that exits with code 1). process.env quietly looks empty. An async network call reports an EACCES error event, and if nothing listens for it, the script exits with code 0 (02). 3va lists every refusal when the run ends (env vars included, when read by name), with the flag to add, and --trace-denials shows each one as it happens.
• No TTY, no prompt. In a terminal, 3va asks before granting a missing capability. In CI, pipes, or redirected output it denies silently. "no-prompt": true in package.json makes that behavior explicit.
• 3va permissions learn <script> runs the script with everything allowed and prints the exact flags it used. Add --write to merge them into package.json. It is the quickest way to find the minimum set. 3va permissions suggest only reads the source and produces broad "." scopes.
• ⚠ Dependencies may be out of date is printed whenever a folder has a package.json but no installed node_modules (examples 09 and 13). It is harmless for these examples, which have no dependencies.

See Permissions for the full model and CLI Reference for every command used above.