git hosted npm packages - 04-17-19

How to install npm packages directly from a gitlab, (or any other git host)

The problem

With so many Javascript/Purescript/Elms side projects going, all with diverse build/bundling setups, getting them somewhere presentable like my personal site is a challenge. I’ve iterated over several solutions over the past few years and today I’m excited to share a new one, node modules! This solution builds on what I learned in previous attempts and continues to streamline my personal site continuous integration and deployment.

The basic structure is side projects go to in separate repositories (ex. ascii-forest) and my personal site also into a public repo. The personal is a statically generated Hugo site that builds and deploys via gitlab-ci and the side projects arch very widely but can be understood as visual browser experiments. A good example of how things previously made their way to my personal site is my generative code experiment series. When I first integrated them it was via a Bash script executed during the gitlab-ci build step. The script cloned the experiments repo built the js files copied them into a place Hugo would statically serve them. This worked great at first but soon became a mess as I moved on to other projects and the structure of the experiments changed and eventually stop building. My second solution was to build the experiments once locally manually push the built files to S3 where the build script could just download, untar, and copy into correct location but even this did not solve everything. The setup was still fragile and relied on manual processes. Taking that into account I shifted to npm.

The Solution

Create a node module for each side project then simply let npm handle the dependencies. To show this I’ll go through a side project called ascii-forest which is responsible for the ascii art, at the time of writing, to the right of this article on desktop.

ascii-forest example

ascii-forest example

  1. Make sure the side projects package.json is in the root dir of it’s repo

  2. Add the required fields to the side projects package.json

  3. Commit and push

  4. Tag repo with semantic version

    • $ git tag -a v0.2.0 -m ‘version 0.2.0: Add built files to module’
  5. Push tags to remote

    • $ git push origin –tags

Install this new package into the main project, in my case personal site

  1. Add the side project module to main package.json

  2. Install package with

    • $ npm install
  3. Use the module where needed

    • 
      import Forest from ‘ascii-forest’;
      // ascii forest
      document.querySelector(‘.ascii-forest pre’).textContent = Forest.generateForest(30, 300);
      

Some notes

  • I tried using the ssh url, “git@gitlab.com:BTBTravis…“, which worked locally. However the network the CI build step runs in did not allow for this type of connection so I used the https repo endpoint instead.
  • The version tagging is really slick and makes the side project completly independent.

Resources