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 buildthen assembles those distributables into the deployment directory. - Terminal apps.
pear makebundles the app and its dependencies fromnode_modulesinto one standalone executable.
A few practical implications follow:
- Audit before you ship. Run
pear stage --dry-runon 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:
- Use
node_modulesfor dependencies—Bare resolves them from there while you develop, andpear makebundles them from there. - Use
package.json—your build tooling and Pear OTA read the app's name, version, andupgradelink from it. - Stage the deployment directory, not the project.
pear buildwrites the layoutpear stageexpects, so your sources andnode_modulesstay out of the drive. Run it from outside the app folder; seepear stageshows 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
- Peer-to-peer, demystified—conceptual overview of HyperDHT and Hyperswarm, including what your IP discloses on a swarm.
- Storage and distribution—what actually crosses the wire when peers replicate.
- Deploy your application—make, build, stage, and provision a release.
Last updated on