package.json
Nish reads the same package.json npm and Node read. It looks at a handful of fields, and ignores the rest. Some are Node's own fields that Nish reads in a narrower way: exports, engines and version. One is Nish's own: nish, which only the root package's manifest may carry. This page lists every field Nish reads, what it does with each one, and the error each mistake gets.
Two kinds of package.json matter, and they are read differently:
- The root package's is the
package.jsonnearest above the entry file you compile. Itsnishfield grants capabilities, adds a no-panic scope and names host modules. When nopackage.jsonis above the entry, there is no root manifest, and nothing on this page applies to your own code. - A dependency's is the
package.jsonof a package undernode_modules. Nish reads itsexports,enginesandversion: which file to compile, which compiler version the package needs, and the version to name in an error. Anishfield in a dependency's manifest is ignored. A package cannot grant itself anything.
Every other field (name, scripts, dependencies, type, bin and the rest) is npm's and Node's business, and Nish leaves it alone. Install packages with npm as usual. Nish resolves imports from node_modules the way Node does.
The nish field is read strictly. JSON Schema cannot express two of the rules below, and the compiler holds to them anyway: a key written twice is refused, and so is a package.json that stops being JSON. A key is decoded as JSON.parse decodes it, so "ni\u0073h" is "nish". Each refusal is an error reported where the manifest writes the mistake, so a typo never quietly widens a policy or drops a module from a scope.
This page is generated from schemas/package.schema.json, which an editor can use to check a package.json and complete its nish field. In VS Code, add it beside the package.json schema the editor already applies, rather than in place of it, with a json.schemas entry in your settings:
{
"json.schemas": [
{
"fileMatch": ["package.json"],
"url": "https://raw.githubusercontent.com/amritk/nish/main/schemas/package.schema.json"
}
]
}
A "$schema" key in the package.json itself would also work, but it replaces the editor's own schema for npm's fields.
The nish field
Settings for the program you compile, read from the root package's manifest only.
Nish's own settings: one object, written once, whose keys are noPanic, capabilities and host, each written once.
Any other key is refused, a misspelt capabilites included. So is a second nish field, a nish that is not an object, and a package.json that mentions nish but is not well-formed JSON. All of these are NL3036. A field the compiler cannot read in full would leave part of what the package says about itself unread, so it is refused rather than half applied.
Only the root package's manifest is read for this field. A dependency's nish field is ignored.
{
"nish": {
"noPanic": [
"src/parser.ts"
],
"capabilities": {
"deny": [
"net"
],
"dependencies": {
"@amritk/vector": [
"fs.read",
"fs.write",
"process.spawn",
"net",
"unsafe"
]
}
}
}
}
capabilities
Type: object
What the program may reach: a capability policy for your own code (allow and deny), and the grants each dependency under node_modules needs (dependencies).
A capability is a kind of effect a program can have on the world. Every builtin carries one, or a deliberate none, and the compiler works out which capabilities every function reaches, through any chain of calls and across packages. Run nish run --capabilities main.ts to see what a program reaches.
| Capability | What reaches it |
|---|---|
clock |
Date.now, monotonicNanos, wallClockNanos, statMtimeSync |
entropy |
crypto.getRandomValues, Math.random |
env |
getenv, geteuid |
exit |
process.exit, and exit from nish:process |
ffi |
any call to a declare function, which is C code or a host import |
fs.read |
readFileSync, readdirSync, fileOpen and the rest of the file readers |
fs.write |
writeFileSync, appendFileSync, mkdirSync, renameSync, unlinkSync and the rest of the file writers |
net |
every nish:net export |
process.spawn |
spawnSync, spawnPiped, spawn, kill, waitPid and the process-priority calls |
signal |
signalFd, readSignal |
tty |
every nish:term export |
unsafe |
the eight nish:unsafe exports, such as uncheckedGet |
The language specification lists every builtin under its capability. A name that is no capability is NL3033.
Without a policy, the capabilities a program reaches are a report: nish run --capabilities prints them and nothing is refused. With one, a program whose entry reaches a capability the policy does not grant is refused at compile time, with the chain of calls that reaches it. Dependency grants are different: a dependency that reaches fs.read, fs.write, net, process.spawn, ffi or unsafe is refused unless dependencies grants it, policy or none.
A policy changes no byte of the compiled program. A program inside it compiles and runs as it would with none. To hold a running program to its capabilities as well, build it with --sandbox (see the sandbox guide).
A capabilities that is not an object, a key other than allow, deny and dependencies, an allow or deny that is not an array, and a key written twice are NL3032.
dependencies
Type: Record<string, string[]>
The capabilities each dependency is granted, keyed by the package's name: the name you import it by, @scope/name for a scoped package.
A dependency reaches the gated capabilities, ffi, fs.read, fs.write, net, process.spawn and unsafe, only when this object grants them to it. It reaches every other capability without a grant. A dependency that reaches a gated capability it is not granted is refused, in the dependency's own source, naming the package, the capability, the function that reaches it and the chain of calls (NL2576):
node_modules/pkg_http/src/index.ts:6:10: error: the dependency `pkg_http` reaches `net` through `dial`, which the root package does not grant it; grant it with "nish": { "capabilities": { "dependencies": { "pkg_http": ["net"] } } } — the chain that reaches it: node_modules/pkg_http/src/index.ts:6:10 calls netAddress
How a dependency's capabilities are counted:
- Every function counts, exported or not, called or not. A package's capabilities are the union over every function its modules define.
- What it reaches through another dependency is its own. If
pkg_acallspkg_b, which dials, both neednet. - A callback counts where it is instantiated. Your function passed to a dependency's generic function makes that instantiation the dependency's, so the dependency needs a grant for what your function reaches.
- The standard library is never refused, and what decides is where a module was resolved from, not its package's name. A dependency that calls itself
nishis judged like any other.
Only this object grants. --allow on the command line does not, and neither does the dependency's own package.json. A grant never widens the root's own policy: a capability your deny lists is refused whoever is granted it. A grant to a package the program does not load is no error.
The value is not an object, a package is named twice, a grant is not an array, or an entry is not a string: NL3041.
Once the grants are right, --update-capability-lock records what every dependency reaches in nish-capabilities.lock.json, so an upgrade that reaches something new stops the build.
Examples: {"pkg_tool": ["fs.read=./data", "process.spawn=git", "net=127.0.0.1"]}
{
"nish": {
"capabilities": {
"dependencies": {
"pkg_http": [
"net"
],
"@amritk/vector": [
"fs.read",
"fs.write",
"process.spawn",
"net",
"unsafe"
]
}
}
}
}
allow
Type: ("clock" | "entropy" | "env" | "exit" | "ffi" | "fs.read" | "fs.write" | "net" | "process.spawn" | "signal" | "tty")[]
An allowlist for your own code. Writing allow at all makes the policy an allowlist: a capability the program reaches that allow does not list is refused, exit and signal included. An empty list allows nothing, and no list allows everything.
The program is refused with NL2459, one error per capability, at the first call of the chain that reaches it:
main.ts:6:36: error: `main` reaches `net`, which the capability policy does not grant (the root package's `allow`); the chain that reaches it: main.ts:6:36 calls dial, client.ts:5:10 calls netAddress
What is judged is every function outside code can call. That is main alone under nish run or a closed --link build. A library build (-o alone, a sidecar, wasm) also judges every exported function of every module, or every function under --no-strict-exports.
unsafe cannot be allowed, because importing nish:unsafe is already the opt-in. An allowlist never refuses it, and listing it here is NL3034. Use deny to refuse it. A capability in both allow and deny is NL3035.
--allow on the command line can only narrow this list: the two allowlists intersect. Capabilities here are whole: a directory scope such as fs.read=./data is only for --allow with --sandbox, or for a dependency's grant.
{
"nish": {
"capabilities": {
"allow": [
"fs.read",
"clock"
]
}
}
}
deny
Type: ("clock" | "entropy" | "env" | "exit" | "ffi" | "fs.read" | "fs.write" | "net" | "process.spawn" | "signal" | "tty" | "unsafe")[]
Capabilities your own code may not reach. A program whose entry reaches one is refused with NL2459, with the chain of calls that reaches it, in source order and one error per capability.
unsafe may be denied. "deny": ["unsafe"] refuses a program that reaches a nish:unsafe export anywhere in its closure, dependencies included, so every unchecked index in the program is visible to the policy.
--deny on the command line adds to this list. A denial here also beats a dependency's grant: a capability denied here is refused in a dependency granted it.
{
"nish": {
"capabilities": {
"deny": [
"net",
"process.spawn",
"unsafe"
]
}
}
}
noPanic
Type: string[]
Modules that may have no panic site left. A panic site is a place a compiled program can stop with exit 1 besides a panic call: a bounds check, an integer division or a range entry the compiler could not prove safe, an r.expect, a readFileSync of a missing file. Each entry is a module's path, relative to this package.json.
In a listed module, every unproven site is an error, NL2457. Where a guard would let the compiler prove the site, the error says which guard. A call from a listed module into a function outside the scope that may panic, in the standard library or a dependency, is refused at the call (NL2458). A module the list does not name keeps its checks and compiles as before.
--deny-panics puts every module of the program's own package in the scope. With both, the scope is the union.
An entry that names no module of the program is NL3031, so a typo cannot leave the module it meant outside the scope without a word. A noPanic that is not an array is NL3036.
uncheckedGet and uncheckedSet imported from nish:unsafe are allowed in the scope, because the import is the module's own statement that its indexes are in range. The language specification lists every kind of panic site.
{
"nish": {
"noPanic": [
"src/parser.ts",
"src/lexer.ts"
]
}
}
host
Type: string[]
Host modules: TypeScript files the web page owns, whose exported functions a wasm module calls back into. An import from a listed file becomes a wasm import from module host. An import from any other file is an ordinary Nish import. --host <file.ts> on the command line adds to the list.
Nish reads only a host module's exported signatures and skips each function body, so a body may use the DOM, closures, classes and promises. The interop guide shows a whole page.
Each entry is a path relative to this package.json, naming a file inside the package that exists:
- a value that is not a list of strings is NL2694;
- an empty entry, an absolute path (one that starts with
/,\or a drive letter), or one that climbs out of the package with..is NL2695. A..that only cancels a directory before it, as inweb/../host.ts, stays inside and is fine; - an entry that names no file is NL2696.
An entry naming the program's own entry file changes nothing: the entry is compiled as Nish all the same.
{
"nish": {
"host": [
"web/host.ts"
]
}
}
Fields shared with Node
Node's own fields, which Nish reads in every package under node_modules. Each one keeps the meaning npm and Node give it. The descriptions below say how much of that meaning Nish reads.
exports
Type: string | object
Node's exports map, which says which file a package offers for each import path. Nish reads it in every package under node_modules to find the source to compile, under its own conditions:
| Condition | Read when |
|---|---|
nish-i32 |
the program compiles in the default --number-mode i32 |
nish-f64 |
the program compiles with --number-mode f64 |
nish |
either mode, when the mode's own condition is not there |
The mode's own condition wins wherever the package declares it, which is the one place Nish answers differently from Node's first-match order. A package that is correct in one number mode only says so with that mode's condition. Its source then fails at the import in the other mode, rather than giving a wrong answer at run time.
The value is a TypeScript file, not built JavaScript, so the package is checked and optimised as your own code is. Every other condition (import, require, default, types, node) is skipped, so one exports map can serve Node and Nish side by side. Nish reads a narrower shape than Node does:
- A subpath is an exact key,
.or./name. The./*pattern form is not read. - A target is a string beginning with
./, with no..segment and no backslash escape. A nested condition object or an array of targets counts as no target. - A bare condition map for
.,{ "nish": "./src/index.ts" }, is read as the map for.. A bare string,"./index.js", is JavaScript and offers Nish nothing.
Each way to find no file is its own error at the import. A package with no Nish condition for that entry, an ordinary npm package, is NL3020. A package that offers only the other mode's condition is NL3017. A manifest that is not well-formed JSON is NL3021. No exports, no key for the subpath, or a shape Nish does not follow is NL3014.
The modules guide walks through writing a package.
{
"exports": {
".": {
"nish": "./src/index.ts",
"import": "./dist/index.js"
},
"./blake3": {
"nish": "./src/blake3.ts"
}
}
}
engines
Type: object
Node's engines map. Nish reads one key, engines.nish: the lowest compiler version a package needs. It is checked in every package under node_modules the program imports, whether or not the package's entry point resolves. Other engines, such as node, are left to npm.
nish
Type: string
The lowest compiler version the package needs, as a floor: >=X.Y.Z or >=X.Y, with blanks allowed around the version.
An older compiler refuses the package and says which version it asked for (NL3018):
Package `pkg_future` needs a newer compiler: its `engines.nish` asks for `>=999.0.0` and this is nish 0.8.0
Any other shape is refused rather than taken as met, because a floor the compiler cannot read is one it cannot claim to meet (NL3019). That includes a caret, a tilde, an upper bound, a bare version, and a value that is not a string.
Constraints: pattern: ^\s*>=\s*[0-9]{1,9}\.[0-9]{1,9}(\.[0-9]{1,9})?\s*$
{
"engines": {
"nish": ">=0.18.0"
}
}
version
Type: string
The package's version, as npm writes it. Nish does not check it against anything. It is named in an error, so you know which copy of a package an error is in:
- An error inside a dependency's own source carries a note naming the package and its version,
this is in the dependency pkg_broken 0.3.1, not in this program's own source. Under--jsonthe diagnostic also carries the package's name inpackage. - When one package name is installed at two directories, NL3029 names both directories and both versions. Nish compiles one copy of each package per program. A copy whose manifest has no
versionis said to haveno version.
{
"version": "1.0.0"
}

