Technical Details
A few technical notes to help you use OneScript more effectively.
Runtime
Scripts run in the system WebView, with a Node.js compatibility layer. See Node.js Compatibility for supported APIs, limitations, and per-module notes.
Each run creates an isolated WebView virtual machine. Projects are bundled by esbuild, then executed by the runtime:
| Component | Role |
|---|---|
| WebView | Run user scripts |
| esbuild | Bundle the project to JavaScript |
| pnpm | Dependency management |
Build
Embedded esbuild bundles the project to ESM JavaScript (dist/index.js), which WebView then executes. Node.js builtins are mapped to the compatibility layer. TypeScript, JSX, and static assets such as images, fonts, and Wasm are supported.
Runtime-computed import() cannot be bundled and will fail the build.
pnpm
When installing, adding, or removing dependencies, OneScript runs embedded pnpm with these options:
| Option | Meaning | Reason |
|---|---|---|
--config.ignore-scripts=true | Do not run package lifecycle scripts (such as preinstall / postinstall) | iOS does not allow spawning child processes; pnpm lifecycle scripts rely on child_process and cannot run |
--config.ignore-pnpmfile=true | Do not run .pnpmfile.cjs | It can also execute arbitrary scripts or spawn child processes |
--config.node-linker=isolated | Use pnpm's isolated node_modules layout | Avoids phantom dependencies from a flattened install |
--config.package-import-method=hardlink | Import package contents via hard links | Fits the app sandbox filesystem |
Also: git dependencies are unavailable; native modules (.node / binding.gyp) are unavailable; packages that depend on lifecycle scripts, native executables, or package CLI bins cannot run inside the app.
How is this guide?
Last updated on