└── README.md


/README.md:
--------------------------------------------------------------------------------
  1 | # ssb-npm 101
  2 | 
  3 | status: draft
  4 | 
  5 | ## what is ssb-npm?
  6 | 
  7 | it's like npm, except the registry of packages (package metadata + tarballs)
  8 | lives entirely on secure scuttlebutt
  9 | 
 10 | this means there is no central authority controlling packages!
 11 | 
 12 | ## prerequisites
 13 | 
 14 | 1. have npm 5 or newer (relies on `package-lock.json`; won't work with earlier
 15 |    npm versions); can do `npm install -g npm@latest`
 16 | 2. have [scuttlebot](https://github.com/ssbc/ssb-server) installed, with
 17 |    `ssb-server start` running successfully on your machine
 18 | 
 19 | ## workaround: big blobs
 20 | 
 21 | ssb-npm-registry depends on `sodium-native` which is larger than `ssb-server`'s
 22 | default maximum blob size. To get around this, you can either
 23 | 
 24 | 1. edit your ssb config (usually `~/.ssb/config`) to include `{"blobs":{"max":10000000}}`, or
 25 | 2. run `ssb-server` as `ssb-server start --blobs.max 10000000`
 26 | 
 27 | to be able to get the blob for `sodium-native`.
 28 | 
 29 | ## ssb-npm-registry
 30 | 
 31 | ssb-npm-registry is an npm registry, not unlike the one running on npmjs.org,
 32 | except this registry uses secure scuttlebutt to find packages that were
 33 | published to it, and installs them from there!
 34 | 
 35 | ssb-npm-registry itself is actually published to ssb, but without a locally
 36 | running registry we'll have to install it manually. once we do that, we can use
 37 | the `ssb-npm` command just like the regular `npm` command to install packages.
 38 | 
 39 | first, we'll pull down the blob for the latest version of `ssb-npm-registry`.
 40 | you can find out what the latest blob is by searching `npm-packages` packages
 41 | with `ssb-server`:
 42 | 
 43 | ```
 44 | $ ssb-server messagesByType npm-packages | grep -C 1 ssb-npm-registry
 45 | ```
 46 | 
 47 | you'll see something like this near the bottom of the output:
 48 | 
 49 | ```
 50 |   "name": "npm:ssb-npm-registry:1.7.0:latest",
 51 |   "link": "&2afFvk14JEObC047kYmBLioDgMfHe2Eg5/gndSjPQ1Q=.sha256",
 52 | ```
 53 | 
 54 | you can now use `ssb-server` to WANT and then GET that blob, which is the npm
 55 | tarball of the package:
 56 | 
 57 | ```
 58 | $ ssb-server blobs.want '&2afFvk14JEObC047kYmBLioDgMfHe2Eg5/gndSjPQ1Q=.sha256'
 59 | $ ssb-server blobs.get '&2afFvk14JEObC047kYmBLioDgMfHe2Eg5/gndSjPQ1Q=.sha256' >
 60 | ssb-npm-registry.tar.gz
 61 | 
 62 | $ tar xvzf ssb-npm-registry.tar.gz
 63 | 
 64 | $ mv package ~/.ssb/node_modules/ssb-npm-registry
 65 | ```
 66 | 
 67 | you'll need to add the entry to your `"plugins"` section of your `~/.ssb/config`
 68 | file:
 69 | 
 70 | ```
 71 |   "ssb-npm-registry": true
 72 | ```
 73 | 
 74 | now you can restart `ssb-server start`.
 75 | 
 76 | ## ssb-npm
 77 | 
 78 | now we can install the `ssb-npm` command. what's nice is that since the registry
 79 | is installed locally, we can actually use the vanilla `npm` command to do so:
 80 | 
 81 | ```
 82 | $ npm install ssb-npm --global --registry=http://localhost:8043/
 83 | ```
 84 | 
 85 | woo, now you can use `ssb-npm install ...` to install packages by name, just
 86 | like the regular `npm` command!
 87 | 
 88 | ## publishing packages
 89 | 
 90 | let's publish one of your own npm packages to ssb-npm:
 91 | 
 92 | in that module's root directory, run
 93 | 
 94 | ```
 95 | $ ssb-npm publish
 96 | ```
 97 | 
 98 | you'll see your module published. :tada:
 99 | 
100 | what about your dependencies though? unless all of your module's dependencies
101 | are already on ssb-npm (this is unlikely depending on what you're working on;
102 | the ssb registry is still very young), you'll need to publish those as well. you
103 | can publish all of your module's dependencies that aren't already on ssb using
104 | `ssb-npm-migrate`:
105 | 
106 | ```
107 | $ ssb-npm-migrate
108 | ```
109 | 
110 | and then republish:
111 | 
112 | ```
113 | $ ssb-npm publish
114 | ```
115 | 
116 | and you're done. now anyone that is connected to your friend graph can run
117 | `ssb-npm install pkg` to install your package, all without touching any oldweb
118 | services like npm!
119 | 
120 | ## license
121 | 
122 | CC0
123 | 
124 | 


--------------------------------------------------------------------------------