Skip to Content
ExamplesOverview

Examples

The examples/ directory of the 3va repository holds 14 small projects. Each page in this section walks through one of them: what it does, how to run it, what you should see, how it works, and what to watch out for.

Everything here was run against 3va 2.9.0 on Linux, non-interactively (no TTY). The output blocks are real output from those runs, with only absolute paths shortened.

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

Index

#ExampleWhat it showsCommand
01Hello WorldThe simplest script, zero permissions3va run app.js
02HTTP ServerNode http + --allow-net3va run server.js --allow-net=localhost
03File OperationsScoped --allow-read / --allow-write3va run app.js --allow-read=./data.json --allow-write=./data.json
04TypeScriptRunning .ts with no build step3va run math.ts
05npm Packages3va install + package.json grants3va install --allow-net=registry.npmjs.org
06Dev ServerOn-demand ESM serving + full-page HMR3va dev --port 3000
07Test RunnerJest-compatible tests and snapshots3va test
08BundlerMulti-file → one self-contained file3va bundle src/index.js -o dist/bundle.js --minify
09Process ManagerBackground daemon + auto-restart3va start server.js --name demo-api
10PermissionsDeny-by-default, grant by grant3va run demo.js
11React NativeRun and test the shared TS logic of an RN app3va test
12ExpoExpo helpers and tooling scripts3va run src/index.ts --allow-read=./src
13Tauri3va as the frontend toolchain of a Tauri app3va dev / 3va bundle / 3va test
14Native addonA real .node addon (bcrypt) through Node-API and --allow-ffi3va run app.js --allow-ffi ...

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
  7. 14 if a dependency ships a compiled .node addon

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). In every case, 3va lists what it refused when the run ends, with the flag to add (env vars included, when they are read by name). --trace-denials shows each refusal 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. Example 14 does have one (bcrypt): run 3va install first.

See Permissions for the full model.

HTTP Performance01 · Hello World