It is easy to understand the need for custom styling in webapps. There are many different language tools that make styling in CSS easier, from Less to Sass. Manifold is built to use plain CSS and Sass (which uses the file extension .scss). This page is meant to be a guide on how to properly add stylistic changes to Manifold so your changes are not overwritten.

What is Sass?

Sass is a CSS extension language. As this page is not a guide on how to program in Sass, you can check out their homepage. Needless to say, Sass provides some functionality that Manifold developers may find useful, and as such all Manifold developers need to understand how using sass affects the development workflow.

Manifold Styling Workflow

Normally, all styling would be put in the public folder in a file called "style.css", or if that file gets too large, it can be split up into different .css files and linked in the index.html document. This linking tells the browser to retrieve the css files from the server as the webpage is being loaded, and is often cached in the browser itself. This may cause problems when developing because changes in a css file may not be seen in your browser simply because the browser has a cached version and never retrieves the newer, modified version. Different web browsers, like Chrome, offer ways to get around this by disabling caching while the inspector/DevTools window is open.

Ultimately, there are two ways to add styling to Manifold.

1. Pure CSS
2. Using Sass

Pure Css

To use pure CSS, you can put all of your CSS classes in the "manifoldStyle.css" file. This file is already included in the index.html file and will be retrieved by the browser automatically. No fancy setup is necessary to do this. If you want to create a new .css file to keep things from getting confusing, or to decompose the project, you may do so freely, just remember to edit the index.html file and follow the other examples to link your new css file to the html file.

If you want to keep your css files that are specific to your components in the same folder, you can import it in your component file like this:

import React, { Component } from 'react';
import './Button.css'; // Tell Webpack that Button.js uses these styles

class Button extends Component {
  render() {
    // You can use them as regular CSS styles
    return <div className="Button" />;
  }
}

Webpack automatically sees that this component requires the Button.css file and will send it to the browser for you without needed to put it in the public folder.

.Button {
  padding: 20px;
}

Using Sass

The "scss" Folder

Under the root folder is a folder called "scss". This houses all of the Sass files for the project. The "style.scss" file acts acts as a gateway for the Sass compiler to easily find all the other .scss files. If you created a new .scss file under the scss folder, you would need to import it in that root file to be included with all of the other ones.

Adding Changes to Sass Files

There are quite a few Sass files in Manifold, most of which are found under the bootstrap and core folders. Generally, you will not need to edit these files. The bootstrap folder is made up of the downloaded scss files from the bootstrap website. Modifying these files is not recommended, because if we wanted to upgrade to a newer bootstrap version, any customized changes would be overwritten when those files are replaced. The core scss files were created by the developer of CoreUI, whose template we are using. You may alter these files as you deem fit and not be worried about being overwritten (minus the usual merge conflicts when using git). Other custom classes may be put in the "_custom.scss" file. Any Sass variables you want to access are declared in the "_custom-variables.scss" file and are provided to the "_custom.scss" file by the imports happening in "style.scss". As in the case of developing with pure css, it is fine to create new .scss files to decompose your work, just make sure to import any new files in the "style.scss" file following the other import examples.

Compiling Sass Files

Because .scss files are not raw CSS, they need to be compiled into CSS before the browser can know what to do with them. There is an npm package called gulp, which is essentially a task executer, that we use to run various tasks that compile Sass files for us. A gulpfile.js is already provided for us in the manifold root folder, which defines all the tasks that gulp can execute at that folder location. To use gulp, install it globally:

npm install -g gulp

After a successful install, you can use the general gulp command:

gulp <task_name>

There are three gulp tasks defined in our gulpfile.js, one of which is just a shorthand for the other.

gulp sass

This is a single run command that takes all of the Sass files in the scss folder and compiles them into one CSS file located in the public folder. This overwrites any changes that you may have made directly to the "style.css" file. It also creates a minified version of that same file, called "style.min.css", but that is not currently linked to in the index.html file, so it is not loaded by the browser. The next two commands are more useful for developing.

gulp sass:watch

//OR the shorthand
gulp

This runs a program that watches for changes in any .scss file in the scss folder. If you create a new Sass file, you only need to register it via an import in the "style.scss" file to work. The default command is set up in gulpfile.js to automatically run this watch task, so not providing a task name will run the watch task anyway. These last two tasks are very helpful for developing because after starting the task in a terminal, any saved changes to Sass files will automatically recompile into CSS and your Manifold web page will automatically update for you. Unless we can get this gulp watch task included in the npm start script, running this second script is the recommended way to develop.