Pear Docs
About PearPlatform foundations

Dependencies

Why Pear apps use npm for dependencies even though they run on Bare, and how those dependencies reach users: packaged into the build you stage, not replicated from node_modules.

A question that comes up enough during onboarding: why does Pear use npm at all when applications run on Bare, not Node? The answer is a deliberate trade-off between developer ergonomics and the platform's clean-room ideals.

Looking for what your IP address discloses when you join a swarm? That's covered in Peer-to-peer, demystified.

Why npm for dependencies

npm is a great package manager for JavaScript, and most JavaScript developers already know how to use it. All of Holepunch's modules—Hypercore, Hyperdrive, Hyperbee, the lot—are published there. Reinventing a peer-to-peer package manager would have meant reinventing every developer's habits at the same time, for very little upside.

npm is where your dependency story starts, not where Pear starts. You don't need Node.js or npm to install Pear—the curl and irm installers at install.pears.com fetch a platform binary—and your app's peer-to-peer code runs on Bare, not Node. npm's job is delivering your dependencies while you develop.

How dependencies reach users

Declaring a dependency in package.json still matters, because the build you stage carries it. Pear v3 stages a deployment directory of finished builds, not your project folder, and pear stage no longer runs a JavaScript analysis pass over your source. So each dependency ships inside the build:

  • Desktop apps. Your packaging tool (Electron Forge, in hello-pear-electron) packs the app and its dependencies into each distributable. pear build then assembles those distributables into the deployment directory.
  • Terminal apps. pear make bundles the app and its dependencies from node_modules into one standalone executable.

A few practical implications follow:

  • Audit before you ship. Run pear stage --dry-run on the deployment directory to see what a stage would change without writing it; this is where you'd catch a dependency that ballooned in size or pulled in something unexpected.
  • A dependency update ships a new build. If you update a dependency, you're not merely changing a package-lock.json—you're shipping new code to every running peer once its copy updates over the air through Pear OTA. Ordinary semver discipline applies, but the consequence is more direct than on a server-rendered web app.

Dependency layout for Pear apps

Bare loads modules from node_modules the same way Node does during development. A few layout rules keep builds predictable:

  1. Use node_modules for dependencies—Bare resolves them from there while you develop, and pear make bundles them from there.
  2. Use package.json—your build tooling and Pear OTA read the app's name, version, and upgrade link from it.
  3. Stage the deployment directory, not the project. pear build writes the layout pear stage expects, so your sources and node_modules stay out of the drive. Run it from outside the app folder; see pear stage shows huge size growth.

TypeScript is supported. Not every Holepunch module ships its own typings yet; the community holepunch-types project aggregates coverage. An IDE with TypeScript language service helps even for plain JavaScript projects.

Never load JavaScript over HTTP(S). Loading code from an external source is dangerous—if that source is compromised or malicious, your app can be exploited, and the risk is worse for apps with native API access. Ship dependencies with the app (as above) instead of fetching them at runtime.

See also

Last updated on

Was this helpful?

On this page