└── 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 | --------------------------------------------------------------------------------