Troubleshooting for installing Node.js and npm, local previewing, and deployment through Netlify

[hongtaoh]

I encountered some difficulties when I used Victoria's amazing hugo-theme-sam. I documented these problems and associated solutions to them, in the hope of helping others with the same issues.

There are several things you need to prepare to preview locally and deploy a Hugo site which uses the Sam theme.

Install Node.js, npm, postcss-cli, and autoprefixer

Victoria recommends installing Node.js and npm this way. However, after the installation, when running npm install -g postcss-cli and npm install -g autoprefixer to install postcss-cli and autoprefixer, a permission error might occur:

Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

This thread documented this problem. To solve it, simply follow this answer.

The idea is, instead of installing npm through a Node installer, you can install it using nvm.

1. Install nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash

You can run the above line of code no matter what directory you are at.

2. Install Node.js and npm via nvm.

nvm install stable

Then, you can install postcss-cli and autoprefixer.

The following codes come from this answer on this thread:

sudo npm i -g postcss-cli

and

sudo npm i -g autoprefixer 

You will be asked to input your passwords. If you are using a Mac, your input will be invisible. However, it will be processed anyway. So don't worry. Just input your passwords and press Enter.

Locally preview the project

When previewing the website, Hugo might give this error:

TOCSS: failed to transform "css/main.tmp.css" (text/x-sass): resource "sass/sass/style.sass_7642ba43b3212fd7d7ba324df3b88b0c" not found in file cache

To solve this problem, simply copy the /exampleSite/resources and paste it into the root directory of your hugo project.

Deploy through Netlify

If you are deploying your project via Netlify:

First, don't use the netlify.toml within hugo-theme-sam. Instead, use the netlify.toml here. Be sure to edit the HUGO_VERSION accordingly. Put this netlify.toml file at the root directory of your Hugo project.

 [build]
 publish = "public"
 command = "hugo --gc --minify"

 [context.production.environment]
 HUGO_VERSION = "0.75.1"
 HUGO_ENV = "production"
 HUGO_ENABLEGITINFO = "true"

 [context.split1]
 command = "hugo --gc --minify --enableGitInfo"

 [context.split1.environment]
 HUGO_VERSION = "0.75.1"
 HUGO_ENV = "production"

 [context.deploy-preview]
 command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"

 [context.deploy-preview.environment]
 HUGO_VERSION = "0.75.1"

 [context.branch-deploy]
 command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"

 [context.branch-deploy.environment]
 HUGO_VERSION = "0.75.1"

 [context.next.environment]
 HUGO_ENABLEGITINFO = "true"

The deployment might fail and give you this error:

Building sites … ERROR 2020/09/16 20:06:07 Transformation failed: POSTCSS: failed to transform "css/main.css" (text/css): PostCSS not found; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/

This problem can be solved by this answer. Simply add a package.json file at the root directory of your Hugo project. The package.json is to tell Netlify what packages are needed to deploy our Hugo projects: postcss-cli and autoprefixer. Although you have installed the two packages locally, Netlify doesn't know you will need them until you let it know.

The package.json should be like this, as mike-foucault suggested:

{
  "name": "netlify-deps",
  "version": "0.1.0",
  "dependencies": {
    "postcss-cli": "7.1.1",
    "autoprefixer": "9.8.4"
  }
}

Example

If you have trouble understanding the above parts, you can refer to this example.