Adding npm packages

Guide on how to add existing npm packages to your site.

Introduction

Hinode uses npm packages and mounted folders to create a flexible, automated build system. This guide shows how to add an npm package to your site. It installs Leaflet as an example. Leaflet is an open-source JavaScript library to add mobile-friendly interactive maps to your site. This guide assumes you have a working site already. Check the introduction on how to set up a site with Hinode.

Step 1 - Setting up leaflet

As first step we will install the Leaflet package with npm. Next, we will mount the JavaScript library. Lastly, we will import Leaflet’s stylesheet.

Installing Leaflet as development dependency

Run the following command from within your project folder to add Leaflet as a development dependency. npm will download the package and save the files in your local node_modules folder. The dependency is also added to package.json in your repository root.

npm i -D leaflet

Mounting the library to the assets folder

Using Hugo’s module mounts, Hinode bundles all JavaScript files found in the assets/js folder into a single file. Add a link to Leaflet’s core JavaScript file to include it in your project’s JavaScript bundle. Add the below configuration to config/_default/hugo.toml to mount the file leaflet.js.

  [[module.mounts]]
    source = "node_modules/leaflet/dist"
    target = "assets/js/vendor/leaflet"
    includeFiles = "leaflet.js"

The default marker from Leaflet requires several images. Mount these images to static/css/images for them to become available.

  [[module.mounts]]
    source = "node_modules/leaflet/dist/images"
    target = "static/css/images"
    includeFiles = "*.png"

Importing the css file

Leaflet requires the presence of several style elements. Similarly to the JavaScript bundle, add an import statement to assets/scss/app.scss to include Leaflet’s CSS file in your main style. You can copy the basic file from the Hinode repository and add the statement to the bottom of the file. Please note that the file extension .css should be omitted.

[...]

// Import Leaflet
@import "leaflet/dist/leaflet";

Step 2 - Adjusting the Content Security Policy

Leaflet requires access to OpenStreetMap and requires the data: attribute for image sources. Adjust the Content Security Policy in config/_default/server.toml to enable access to the remote images. You might need to adjust the settings of your hosting provider too (see netlify.toml in the repository root).

img-src 'self' data: https://i.vimeocdn.com https://i.ytimg.com https://tile.openstreetmap.org; \

Step 3 - Adding the image map

Add a map placeholder to your (Markdown) content file. The following placeholder uses a 16x9 ratio and stretches across the main body.

<div id="map" class="ratio ratio-16x9 w-100"></div>

Next, initialize the map placeholder with the OpenStreetMap content. The following code uses the city of London as an example. The mapID refers to the ID of the placeholder. The code tests if an element with the map ID is present and initializes the placeholder accordingly. It adds a marker with a default icon next. You can place the code in assets/js/leaflet.js, where Hinode will pick it up automatically.

const mapID = 'map'

if (document.getElementById(mapID) !== null) {
  const map = L.map(mapID).setView([51.505, -0.09], 13)

  L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
  }).addTo(map);
  
  L.marker([51.5, -0.09]).addTo(map)
      .bindPopup('A pretty CSS popup.<br> Easily customizable.')
      .openPopup();
}

Step 4 - Testing the map

From here on you should have a working map on your site. Run the following command to start a local development server.

npm run start

You can now modify the placeholder and map initialization as needed.

Conclusion

We have now added an existing npm package and integrated it with Hinode. The advanced setttings in the documentation provides more background about Hinode’s build system.