
Henk Verlinde is the founder and CEO of [Ventizo](https://ventizo.com/), a digital products company headquartered in the Netherlands. He's interested in digital business building, startups, and the Jamstack.

<a class="text-dark" href="/about">More about Henk<i><svg xmlns="http://www.w3.org/2000/svg" class="icon icon-tabler icon-tabler-arrow-up-right" width="20" height="20" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none"></path><line x1="17" y1="7" x2="7" y2="17"></line><polyline points="8 7 17 7 17 16"></polyline></svg></i></a>


Henk Verlinde


This is the <em>third</em> post of the three piece series <em>Using npm with Hugo</em>.

<aside>
<p>The <em>Using npm with Hugo</em> series:</p>
<ol>
<li><a href="/blog/introduction-to-npm">Introduction to npm</a></li>
<li><a href="/blog/managing-dependencies">How to manage dependencies</a></li>
<li><a href="/blog/customizing-build-scripts">How to customize build scripts</a></li>
</ol>
</aside>

In the [second post](/blog/managing-dependencies) of the series, I showed you that Hugo itself can be seen as a dependency of your project, and that a starter theme provides you with full control over your dependencies and gives you the possibility to customize build scripts.

We also extended our basic example with a local Hugo install, a Hugo project structure, and a starter theme structure.

Let's continue.

## Customizing scripts

Now we’re ready to talk about how to customize build scripts. In stead of using `npx` to run a script from a local npm package, we're going to add a number of custom [scripts](https://docs.npmjs.com/cli/v7/using-npm/scripts) to our `package.json`:

```json
{
  ..
  "scripts": {
    "prestart": "npm run clean",
    "start": "hugo server --disableFastRender",
    "prebuild": "npm run clean",
    "build": "hugo --minify",
    "clean": "shx rm -rf public resources",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ..
}
```

Note the _pre_ scripts `prestart` and `prebuild`. The `prestart` script e.g. executes _before_ the `start` script. Similarly, you can use _post_ scripts. A `poststart` script e.g. would execute _after_ the `start` script.

### Listing scripts

The `npm run` command lists the scripts available in your `package.json`:

```bash
$ npm run
Lifecycle scripts included in npm-hugo:
  prestart
    npm run clean
  start
    hugo server --disableFastRender
  test
    echo "Error: no test specified" && exit 1

available via `npm run-script`:
  prebuild
    npm run clean
  build
    hugo --gc --minify
  clean
    shx rm -rf public resources
```

### Running scripts

The `npm run start` command e.g. will:

1. delete the temporary build directories, and next
2. start the hugo server with the `--disableFastRender` flag enabled.

## Bootstrap

We can use dependencies to pull in resources for our project. Let's import the Bootstrap SCSS we added previously, into our starter theme:

```bash
shx mkdir assets && shx echo '@import \"bootstrap/scss/bootstrap\";' > ./assets/app.scss
```

And process the SCSS with Hugo in `./layouts/partials/head.html`:

```html
<head>
	{{ $options := (dict "targetPath" "main.css" "includePaths" (slice "node_modules")) -}} {{ $css :=
	resources.Get "app.scss" | resources.ToCSS $options -}}
	<link rel="stylesheet" href="{{ $css.Permalink }}" />
</head>
```

Let's add some Bootstrap styling to `./layouts/index.html`:

```html
{{ define "main" }}
<div class="container-fluid">
	<div class="row vh-100 align-items-center justify-content-center">
		<div class="col-md-7">
			<h1 class="text-center">{{ .Title }} 🎉</h1>
		</div>
	</div>
</div>
{{ end }}
```

Add the `resources` and `public` folders to `.gitignore`, and check the result with `npm run start`.

### Removing unused CSS

We can also use dependencies to pull in tooling for our build process. Let's make our project production ready by stripping out unnecessary CSS:

> [PurgeCSS](https://purgecss.com/) analyzes your content and your CSS files. Then it matches the selectors used in your files with the one in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files.

We will also be installing [Autoprefixer](https://github.com/postcss/autoprefixer), a [PostCSS](https://github.com/postcss/postcss) plugin to parse CSS and add vendor prefixes to CSS rules using values from [Can I Use](https://caniuse.com/):

```bash
npm i -D @fullhuman/postcss-purgecss postcss-cli autoprefixer
```

Add `./postcss.config.js`:

```js
const autoprefixer = require('autoprefixer');
const purgecss = require('@fullhuman/postcss-purgecss');

module.exports = {
	plugins: [
		autoprefixer(),
		purgecss({
			content: ['./layouts/**/*.html']
		})
	]
};
```

Update `./layouts/partials/head.html`:

```html
<head>
	{{ $options := (dict "targetPath" "main.css" "includePaths" (slice "node_modules")) -}} {{ $css :=
	resources.Get "app.scss" | resources.ToCSS $options -}} {{ if hugo.IsProduction -}} {{ $css = $css
	| minify | fingerprint | resources.PostCSS | resources.PostProcess -}} {{ end -}}
	<link rel="stylesheet" href="{{ $css.Permalink }}" />
</head>
```

Update `./config.toml`:

```toml
baseURL = "/"
..
```

Add to `package.json`:

```json
{
  ..
  "browserslist": [
    "defaults"
  ],
  ..
}
```

- [http-server](https://github.com/http-party/http-server) is a simple, zero-configuration command-line http server — handy for viewing a local production build.
- [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/) is a set of web developer tools built directly into the Google Chrome browser.

Run `npm run build` and check the result. That's it. We've brought down the file size of our CSS file from 185.76 KB to — yes that's right — 2.63 KB.

## Plugins

We could also use dependencies to pull in extra functionality into our starter theme. Think of e.g. SEO, performance, and security.

## Wrapping up

You're now familiar with customizing build scripts. We also extended our example with Bootstrap, and optimized it for use in production. You're now also aware that you can use dependencies to pull in extra functionality.

You can find the full example in the [npm-hugo](https://github.com/h-enk/npm-hugo) repo I've set up.

In case you’re curious, the idea for this series was taken from a similar post written about [WordPress](https://roots.io/using-composer-with-wordpress/).

<aside>
<p>Take a look at <a href="https://gethyas.com/">Hyas</a> for a modern Hugo starter using npm to manage dependencies and run customized build scripts.</p>
</aside>


This is the third post of the series Using npm with Hugo. In a series of three posts I will introduce you to npm, show you how to manage dependencies, and show you how to customize build scripts.

How to customize scripts with npm — for Hugo


This is the <em>second</em> post of the three piece series <em>Using npm with Hugo</em>.

<aside>
<p>The <em>Using npm with Hugo</em> series:</p>
<ol>
<li><a href="/blog/introduction-to-npm">Introduction to npm</a></li>
<li><a href="/blog/managing-dependencies">How to manage dependencies</a></li>
<li><a href="/blog/customizing-build-scripts">How to customize build scripts</a></li>
</ol>
</aside>

In the [first post](/blog/introduction-to-npm) of the series, I introduced to the basic concepts of npm. We also went through the most basic example of installing a single dependency to an empty project.

Let's continue.

## Integrating with Hugo

Now we're ready to talk about how you could use npm with Hugo. When you think about a typical Hugo site, the easiest example of dependencies are themes. But there’s something more fundamental to realize: **Hugo itself is a dependency**.

If you think about it, you’re creating a site, or application, that _depends_ on Hugo. The Hugo binary is a 3rd party library that is required for your application to work. This is difficult to understand at first due to that Hugo is usually installed in a global location.

If we could install Hugo locally as a dependency, we would have full control over the Hugo version used in our project. And best of all, all our project users would use the same version.

### How to

We have an issue. Hugo is a binary. It doesn’t have a package.json file, so it’s not an npm package.

### The solution

The solution is to use a binary wrapper for Hugo with a `package.json` file already added. [hugo-bin](https://github.com/fenneclab/hugo-bin) is currently the most popular/accepted package.

There"s been some [discussion](https://github.com/fenneclab/hugo-bin/issues/32) about migrating this package to Hugo, but it hasn’t happened yet and isn’t likely to anytime soon.

<aside>
<p>Unlike hugo-bin, <a href="https://github.com/dominique-mueller/hugo-installer">hugo-installer</a> verifies the checksum & runs a health check when installing. Recommended to use. [<em>Update Jun 26 2021</em>]</p>
</aside>

### Installing

We need the extended version of Hugo for [Sass/SCSS](https://sass-lang.com/) processing. Add a local `.npmrc` configuration file to the project root:

```ini
hugo_bin_build_tags = "extended"
```

Now we can get to installing:

```bash
npm install hugo-bin --save-dev
```

Your `package.json` will now look like:

```json
{
	"name": "npm-hugo",
	"version": "1.0.0",
	"description": "",
	"main": "index.js",
	"scripts": {
		"test": "echo \"Error: no test specified\" && exit 1"
	},
	"keywords": [],
	"author": "",
	"license": "ISC",
	"devDependencies": {
		"bootstrap": "^5.0.0-beta1",
		"hugo-bin": "^0.68.0"
	}
}
```

<aside>
<p>In this series we also use the <code>npx</code> command. <a href="https://docs.npmjs.com/cli/v7/commands/npx">npx</a> (included with npm) runs a command from a local or remote npm package.</p>
</aside>

Let"s check the locally installed Hugo version:

```bash
npx hugo version
```

It should output something like this:

```bash
Hugo Static Site Generator v0.80.0/extended windows/amd64 BuildDate: unknown
```

That’s it. We now have the extended version of Hugo locally installed.

## Setting up a Hugo project

Let"s set up our Hugo project:

```bash
npx hugo new site . --force
```

And list out our project folder:

```bash
$ ls

    Directory: .\npm-hugo

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           1/26/2021 12:28 PM                archetypes
d----           1/26/2021 12:28 PM                content
d----           1/26/2021 12:28 PM                data
d----           1/26/2021 12:28 PM                layouts
d----           1/26/2021 11:20 AM                node_modules
d----           1/26/2021 12:36 PM                resources
d----           1/26/2021 12:28 PM                static
d----           1/26/2021  1:18 PM                themes
-a---           1/21/2021  1:26 PM             12 .gitignore
-a---           1/26/2021 11:13 AM             32 .npmrc
-a---           1/26/2021  1:21 PM            100 config.toml
-a---           1/26/2021 11:20 AM         124376 package-lock.json
-a---           1/26/2021 12:04 PM            333 package.json
-a---           1/21/2021  1:28 PM             12 README.md
```

We now have a project structure, but no content or theme yet.

### Adding a theme

You could now pick up Hugo"s Quick Start at [Step 3: Add a Theme](https://gohugo.io/getting-started/quick-start/#step-3-add-a-theme). That will add a theme as a Git submodule. Since you’re reading an article about npm, you’ve probably realized that [Git submodules aren’t the proper way to deal with dependencies](https://www.philosophicalhacker.com/post/using-git-submodules-effectively/).

Hugo also offers the possibility to [add a theme as a Hugo module](https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme). That will require you to install Go, is also fairly complex, but looks like [a better alternative than Git submodules](https://www.hugofordevelopers.com/articles/master-hugo-modules-managing-themes-as-modules/).

Installing themes as a npm dependency looks like where we want to go. However, most themes are set up without a `package.json` file and any form of dependency management itself.

That"s why we will use a starter theme with a `package.json` file. This will provide us with full control over our dependencies and give us the possibility to customize build scripts.

#### Adding starter theme files

Let"s create a new blank theme to help us get started:

```bash
npx hugo new theme blank-theme
```

We now have a theme structure living in the `themes/blank-theme` folder.

However, our theme will be a starter that lives in the project root.

<aside>
<p>In this series we also use the <code>shx</code> command. <a href="https://github.com/shelljs/shx">shx</a> runs simple Unix-like, cross-platform commands from npm package scripts and the command line.</p>
</aside>

Let"s install shx first:

```bash
npm install shx --save-dev
```

Now we can easily copy the blank theme files to the root of our project:

```bash
shx cp -rf themes/blank-theme/* .
```

And remove the themes folder:

```bash
shx rm -rf themes
```

We"re almost there. Let"s add some content to the homepage:

```bash
shx echo "{{ define \"main\" }}<h1>{{ .Title }}</h1>{{ end }}" > ./layouts/index.html
```

That"s it. We’re now ready to run Hugo:

```bash
npx hugo server
```

## Updating

I recommend regularly updating the local packages your project depends on to improve your website"s code as improvements to its dependencies are made. It will keep your website stable, usable, and secure.

### Checking for outdated packages

The [`npm outdated`](https://docs.npmjs.com/cli/v7/commands/npm-outdated) command will check the registry to see if any (or, specific) installed packages are currently outdated:

```bash
npm outdated [[<@scope>/]<pkg> ...]
```

### Updating a package

The [`npm update`](https://docs.npmjs.com/cli/v7/commands/npm-update) command will update all the packages listed to the latest version (specified by the tag config), respecting semver:

```bash
npm update [<pkg>...]
```

## Wrapping up

You"re now aware that Hugo itself can be seen as a dependency of your project, and that a starter theme provides you with full control over your dependencies and gives you the possibility to customize build scripts.

We also extended our basic example with a local Hugo install, a Hugo project structure, and a starter theme structure. You can find the example in the [npm-hugo](https://github.com/h-enk/npm-hugo) repo I"ve set up.

In the [next post](/blog/customizing-build-scripts) we’re going to talk about how to customize build scripts.

<aside>
<p>Take a look at <a href="https://gethyas.com/">Hyas</a> for a modern Hugo starter using npm to manage dependencies and run customized build scripts.</p>
</aside>


This is the second post of the series Using npm with Hugo. In a series of three posts I will introduce you to npm, show you how to manage dependencies, and show you how to customize build scripts.

How to manage dependencies with npm — for Hugo


This is the <em>first</em> post of the three piece series <em>Using npm with Hugo</em>.

<aside>
	<ol>
	<li><a href="/blog/introduction-to-npm">Introduction to npm</a></li>
	<li><a href="/blog/managing-dependencies">How to manage dependencies</a></li>
	<li><a href="/blog/customizing-build-scripts">How to customize build scripts</a></li>
	</ol>
</aside>

Let's get started 😀

## npm

[npm](https://www.npmjs.com/) is the default dependency manager for [Node.js](https://nodejs.org/) used by millions of developers. Your first question is most likely _"what is a dependency manager and why do I need one?"_.

Almost any code you write probably ends up depending on 3rd party libraries. All of these libraries (projects, frameworks, files, etc) become _dependencies_ of your project. npm lets you declare the dependencies for a project and it will install and manage them.

If you’ve used [Composer](http://getcomposer.org/) for PHP, [Bundler](http://bundler.io/) for Ruby, or [pip](http://www.pip-installer.org/en/latest/) for Python, then you’ve already used a dependency manager.

All these tools deal with _packages_. Every dependency is also a package. What constitutes a package? It can be a local file, local folder, remote zip, local Git repository, remote Git repository, GitHub repository, etc.

Most dependency managers also include a global registry of available packages. For npm, this is the [npm Registry](https://www.npmjs.com/). To get an idea of what kind of packages are available, just browse through the [most depended upon packages](https://www.npmjs.com/browse/depended).

I’ll do my best to explain some npm concepts throughout the series, but the official [npm Docs](https://docs.npmjs.com/packages-and-modules) are quite accessible as well. It’s recommended to read them to get a full understanding of npm.

### Installation

Installing npm is pretty simple. Download and install [Node.js](https://nodejs.org/) (it includes npm) for your platform. I recommend installing the current release.

### Usage

Seeing npm in action usually solves most of the confusion you might have after reading about dependencies and packages. Let’s go through the most basic example of installing a single dependency to an empty project.

In this case our project is just an empty folder to start with:

```bash
mkdir npm-hugo && cd npm-hugo
```

For npm, you declare your dependencies in a `package.json` file. Create one without having npm ask any questions:

```bash
npm init -y
```

For this example we're only installing one dependency: [Bootstrap](https://getbootstrap.com/), the popular HTML, CSS, and JS library:

```bash
npm install bootstrap@next --save-dev
```

You’ll then get the following output:

```bash
added 2 packages, and audited 2 packages in 2s

2 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
```

And your `package.json` will look like:

```json
{
	"name": "npm-hugo",
	"version": "1.0.0",
	"description": "",
	"main": "index.js",
	"scripts": {
		"test": "echo \"Error: no test specified\" && exit 1"
	},
	"keywords": [],
	"author": "",
	"license": "ISC",
	"devDependencies": {
		"bootstrap": "^5.0.0-beta1"
	}
}
```

Let’s list out some folders to see what actually happened:

```bash
$ ls

    Directory: .\npm-hugo

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           1/14/2021  7:44 PM                node_modules
-a---           1/14/2021  7:44 PM           1693 package-lock.json
-a---           1/14/2021  7:44 PM            281 package.json
```

```bash
$ ls node_modules

    Directory: .\npm-hugo\node_modules

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----           1/14/2021  7:44 PM                @popperjs
d----           1/14/2021  7:44 PM                bootstrap
-a---           1/14/2021  7:44 PM            977 .package-lock.json
```

We can see that npm created a `node_modules` directory that contains the `bootstrap` and `@popperjs` packages.

You might be wondering about the new `package-lock.json` file that was generated. The [npm Docs](https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json) explain it nicely:

> `package-lock.json` is automatically generated for any operations where npm modifies either the `node_modules` tree, or `package.json`. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

## Advantages

You might still be wondering what’s the point in using npm and going through all the work above. npm (and any dependency manager for that matter) has many advantages:

- your dependencies are explicitly declared in a single place
- installing and updating is handled by the tool
- your project is locked onto specific versions
- you don’t need to include the actual 3rd party code in your version control repository

The last one is huge. Without a dependency manager, you’re stuck doing one of two things:

- adding the entirety of a 3rd party library into your VCS repo
- using something like Git submodules

This means that when you’re using npm, you check the following files into your repository:

- `package.json`
- `package-lock.json`

That’s it. Add `node_modules` to your `.gitignore` and let npm handle it. Now whoever wants to setup your project, they just run the standard `git clone` followed by `npm install`.

## Wrapping up

You're now familiar with the basic concepts of npm. We also went through the most basic example of installing a single dependency to an empty project. You can find the example in the [npm-hugo](https://github.com/h-enk/npm-hugo) repo I've set up.

<aside>
<p>Take a look at <a href="https://gethyas.com/">Hyas</a> for a modern Hugo starter using npm to manage dependencies and run customized build scripts.</p>
</aside>

In the [next post](/blog/managing-dependencies) we're going to talk about how to manage dependencies.


This is the first post of the series Using npm with Hugo. In a series of three posts I will introduce you to npm, show you how to manage dependencies, and show you how to customize build scripts.

Npm

How to customize scripts with npm — for Hugo

How to manage dependencies with npm — for Hugo

Three reasons why you should use npm with Hugo