shou2017.com
JP

Setting up a Sass Environment and Simplifying HTML Common Parts as Easily as Possible

Thu Dec 5, 2019
Sat Aug 10, 2024

When creating a serverless application without a framework, my biggest challenges were setting up Sass and standardizing HTML components.

There are various convenient front-end tools like webpack and gulp.js, but they have issues such as lack of maintenance or being overly complex. I could just read the documentation, but that’s troublesome.

My first requirement was something simpler than a framework, allowing for easy Sass setup while not being at the mercy of tool updates. In terms of scale, I was implementing a serverless solution with fewer than 50 pages and simple functionality. To minimize maintenance, I decided against using frameworks. The goal was to keep everything as simple as possible.

Initially, I considered using webpack or gulp.js, but decided against them for the following reasons:

  • gulp.js → Not well-maintained; requires learning gulp.js specifications for more complex tasks
  • Grunt → Abandoned for the same reasons as gulp.js
  • webpack → Likely to become the mainstream choice, but too feature-rich and has a steep learning curve. If I were to choose one, it would probably be this, as many frameworks adopt it
  • parcel → The simplest among these options, but I didn’t want to be dependent on a tool
  • Implementing scripts myself by copying trendy front-end engineers → I figured if I was going to go that far, I might as well use a static generator like nuxt.js

Tools Used

  • pug → For standardizing HTML
  • node-sass → For compiling Sass
  • npm scripts → For automating Sass compilation
  • bash → For semi-automating pug builds
  • Live Server → VS Code extension that auto-reloads when HTML or CSS changes

Installing pug

You’ll need node, so install it if you haven’t already.

Installation instructions are available on the official site.

Installing pug:

$ npm install -D pug

In my case, I prefer not to install globally, so I install locally.

$ npm install -D pug-cli

Verify that it’s installed correctly:

$ npx pug --help

Creating Common Layouts

For parts you want to make into partial templates, include _ in the name. For basic setup, it might look something like this:

Creating Common Layouts in HTML

Common parts like head and meta are described in _baseof.pug within the _layout folder.

I put footer and header in the _partials folder.

Since footer and header will be included in baseof.pug, let’s build baseof.pug:

//- Page settings
block pagedata

doctype html
html(lang="ja")
    head
        meta(charset="utf-8")
        meta(http-equiv="X-UA-Compatible" content="IE=edge")
        meta(name="viewport" content="width=device-width, initial-scale=1.0")
        link(href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet")
        title #{pageTitle} | Sample Homepage

        block pagecss

    body.page
        div.container
            include ./_partials/_nav
            div.main-box
                include ./_partials/_header
                block main
            include ./_partials/_footer
    block pagejs

With this, the common layout part is complete.

Creating Individual Pages

You can create individual pages anywhere, but for this test, I’ll create a sample folder directly under the directory and create index.pug inside it, including the baseof.pug we just created.

//- Load template
extend ../_layout/_baseof

//- Page-specific settings
append pagedata
    - var pageTitle= "Top Page";

//- Page-specific CSS
append pagecss
    link(rel="stylesheet" href="../assets/css/style.css")

//- Page-specific JS
append pagejs
    script(src="../assets/js/index.js")

//- Page content
block main
    div.content
        div.page-item
            h1 Top Page Content

As you can see from the code, it’s simply including baseof.pug and then writing individual content, js, and css.

Building

When built, pug files output plain HTML. However, it’s tedious to run the build command for each file, so I’ll create a sh file to build them all at once. Here, I’ll create build_pug.sh:

#!/bin/sh
#
# Sample
#
npx pug sample/index.pug --pretty --out public/sample

In my case, since I haven’t installed pug cli locally, I’m using the npx command. This command builds the index.pug in the sample folder and outputs it to the sample folder in the public folder. Note that you should create the public and sample folders beforehand.

Once created, build it:

$ sh build_pug.sh

When built, it will output something like this to public/sample:

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
    <title>Top Page | Sample Homepage</title>
    <link rel="stylesheet" href="../assets/css/style.css">
  </head>
  <body class="page">
    <div class="container">
      <nav class="nav"><span>This is nav</span></nav>
      <div class="main-box">
        <header class="header"><span>This is header</span></header>
        <div class="content">
          <div class="page-item">
            <h1>Top Page Content</h1>
          </div>
        </div>
      </div>
      <footer class="footer"><span>This is footer</span></footer>
    </div>
  </body>
  <script src="../assets/js/index.js"></script>
</html>

Creating .gitignore file

Make sure not to include node_modules and files that change with each build in git:

/node_modules/ 
/public/top/

Compiling Sass using node-sass

Install node-sass for automatic Sass compilation:

$ npm i node-sass -D

You can organize your folders however you want, but in my case, I’ve organized them as follows. The compiled sass is stored in the assets/css folder within the public folder.

Setting up Sass Environment

Let’s try running the node-sass command. Execute the following command in the terminal:

$ npx node-sass sass/_src/style.scss --output public/assets/css/ --output-style compressed

You should now have compressed CSS compiled from Sass stored in the public/assets/css/ directory.

Now let’s use npm scripts to automatically compile Sass whenever it’s changed.

Add the previous command to the scripts in your package.json:

{
    "scripts": {
        "sass": "npx node-sass sass/_src/style.scss --output public/assets/css/ --output-style compressed"
    }
}

While this works well for production compilation, it’s a bit cumbersome for development, so let’s add a development version called sass-dev:

{
    "scripts": {
        "sass-dev": "npx node-sass sass/_src/style.scss --output public/assets/css/ --output-style compressed --watch --source-map true",
        "sass": "npx node-sass sass/_src/style.scss --output public/assets/css/ --output-style compressed"
    }
}

We’re using watch to detect Sass changes and source-map to make CSS debugging easier. Now let’s run the command. Execute the following in the terminal:

$ npm run sass-dev

You should see that it properly detects and compiles Sass when changes are made.

I recommend using sass-dev during development and sass when deploying to production.

Summary

While it’s a bit tedious to build HTML multiple times, this isn’t a major issue for serverless projects where js implementation tends to be more prevalent than HTML. You could also automate compilation with bash if you’re motivated.

If you have more HTML-heavy pages, you might want to consider using a static site generator. For a small number of pages, typically managed by one person, it’s convenient to create templates without unnecessary tools and manage them with git for reuse whenever needed.

Web制作者のためのSassの教科書 改訂2版

See Also