victorb / gx-js

Immutable Package management for the JavaScript ecosystem using IPFS

gx-js (WIP)

Fetch and publish JavaScript modules from/to IPFS

JavaScript version of https://github.com/whyrusleeping/gx-go

Background

Instead of fetching modules to a third-party, you can actually really simple host your own modules or ask other nodes to help rehost your modules.

Fetching the modules from IPFS rather than a centralized registry brings many benefits to the ecosystem.

• Low cost hosting
• Easy replication and easy to setup private mirrors
• Everyone can host packages
• Caching can happen locally, in the local network or in a private network, because of the P2P nature of IPFS.

For more information about GX itself, please check out the readme in https://github.com/whyrusleeping/gx

Requirements

• NodeJS (5.11.1 or later)
• npm (3.10.3 or later)
• IPFS (0.4.2 or later) (https://ipfs.io)
• gx (0.8.0 or later) (https://github.com/whyrusleeping/gx)

Installation

npm install -g gx-js

Installing modules

• First, setup your project to use gx-js with gx
  • gx init --lang js
• Import the package you want to use, we'll use a test library called "gx-lib-a"
  • gx import Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2
• Now you should have a node_modules/ directory with two directories inside it. It should look something like this:

node_modules
├── gx
│   └── ipfs
│       └── Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2
│           └── gx-lib-a
│               ├── index.js
│               └── package.json
└── gx-lib-a -> /home/user/projects/victorbjelkholm/gx-root-package/node_modules/gx/ipfs/Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2/gx-lib-a

5 directories, 2 files

Now you can import from two paths, the first being much more secure but much more tearse. If you're dealing with multiple versions of the same library, you probably want to use the first way as well.

1. Require from gx/ipfs, using the full path

const libAFromGX = require('gx/ipfs/Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2/gx-lib-a')
console.log(libAFromGX)

2. Require by using the module name only (might not work if multiple packages use the same name)

const libA = require('gx-lib-a')
console.log(libA)

Publishing modules

To publish modules, you will need to run a IPFS node locally, then you can just run gx publish and you get a hash that you can import in other projects.

Discovering modules

Currently, there is no handy mechanism for discovering modules. If you're a module publisher, you could include the version hash in the git tag or Github Release.

License

MIT 2016 (Victor Bjelkholm)

gx-js's Issues

post-import

called after a new package is imported and its info written to package.json.
takes the hash of the newly imported package as an argument.

Handle duplicate dependencies with same/different version in post-install

Currently, we just symlink the package from the node_modules/gx/:hash directory, but what if we have duplicate dependencies that are using different versions? Then we'll use a random one, which is not good enough

post-publish

called during gx publish after the package has been added to ipfs.
takes the hash of the newly published package as an argument

pre-publish

called during gx publish before the package is bundled up and added to ipfs.
currently takes no arguments

Install packages into global directory, then symlink into `node_modules`

Rather than ending up with

node_modules
├── gx
│   └── ipfs
│       └── Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2
│           └── gx-lib-a
│               ├── index.js
│               └── package.json
└── gx-lib-a -> /home/user/projects/victorbjelkholm/gx-root-package/node_modules/gx/ipfs/Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2/gx-lib-a

5 directories, 2 files

We can install packages into a global directory under $HOME/.cache, and then symlink them, saving space.

Would just end up with the following then:

node_modules
└── gx-lib-a -> /home/user/projects/victorbjelkholm/gx-root-package/node_modules/gx/ipfs/Qmd4bNLqHGxRgZhp6jrkisNCffDU3SwSd3XWj7ukendco2/gx-lib-a

1 directory, 1 file

install-path

called during package installs and imports.
sets the location for gx to install packages to

Implement all gx hooks

Available hooks: (not all of them have been implemented yet)

• post-import
• post-init
• pre-publish
• post-publish
• post-update
• post-install
• install-path

Support local/global installs of packages, default to global

https://github.com/whyrusleeping/gx#package-directories

Self-host

Instead of using npm, we should store the packages in IPFS and pin them somewhere. Not sure how feasible it is, since fs-extra has bunch of dependencies.

http://npm.anvaka.com/#/view/2d/fs-extra

post-init

called after a new package is initialized.
takes an optional argument of the directory of the newly init'ed package.

post-update

called during gx update after a dependency has been updated.
takes the old package ref and the new hash as arguments

post-install

called after a new package is downloaded, during install and import.
takes the path to the new package as an argument