Installation & Build 🛠

Automate time-consuming or repetitive tasks in your development workflow using Gulp 🥤


Installation

Installing Node & Gulp and running it is super easy in Materio, please follow these steps and you should be ready to rock 🤘

  1. First of all, make sure you have installed Node (LTS). If Node.js is already installed in your system, make sure the installed version is LTS and jump to step 2.
  2. Once you have npm installed you can run the following command to install and upgrade Yarn. If you want to use npm than you can skip this step.
  3. npm install --global yarn
  4. Install the Gulp CLI: Open Terminal/Command Prompt and run the following command and wait until it finishes. If you have already installed Gulp CLI, you can skip this step and jump to step 3.
  5. npm install --global gulp-cli
  6. Navigate to the Materio root directory and run following command to install our local dependencies listed in package.json.
    You can use npm OR yarn as per your preference.
  7. # For Yarn
    yarn
    
    # For npm
    npm install
  8. Now, you are ready to run npm tasks, below command will start the server and watch the code using browsersync. Open http://localhost:3000/ to check your development 🚀
  9. # yarn
    yarn serve
    
    # npm
    npm run serve

The above command will install all the required Node.js modules into the node_modules/ directory inside your app folder. While installing this command you may see few warnings, don't worry about that for more details refer to our FAQ npm/yarn install warnings.


VS Code Setup

Materio using VS Code as a primary editor. You can find .vscode/ folder in your downloaded package. It includes predefined extensions.json and settings.json files for VS Code.

Find below steps to start project with VS Code :

  1. Open project folder which contains .vscode/ folder in VS Code editor.
  2. In VS Code Extensions Tab, search @recommended and Install Workspace Recommended Extensions
  3. Follow the installation steps as explained above.

Build

Materio's build system is a simple but powerful solution. It uses NPM scripts for its build system. To utilize the power of Gulp & Webpack to achieve maximum automation to help developers saving their precious time for any kind of manual and repetitive tasks and file changes.

  • Uses Gulp to compile SCSS and Autoprefix it.
  • Uses Webpack + Babel for transpile & compilation. Use all Webpack features and write your code using the ES6 specification.
  • Easy to configure - just edit build-config.js file. Read more
  • Separate development and production environments by using gulp-environment. To add environment edit gulp-environment.environments section within package.json file.
  • Easy to extend the build system by adding new Gulp/Webpack tasks.

The following files powers the Gulp & Webpack:

📦
├── 📂 ...
├── 📂 tasks                                      > Gulp tasks
│   ├── 📄 build.js                                 > Gulp tasks for development build
│   └── 📄 prod.js                                  > Gulp tasks for production build
├── ...
├── 📄 .browserslistrc                            > Browserslist config for Autoprefixer
├── 📄 build-config.js                            > Template build config file 👷
├── 📄 gulpfile.js                                > Gulpfile 🥤
├── 📄 index.html                                 > Index page to check all demos
├── 📄 package.json                               > Heart of Node, contain all npm tasks 🛠
└── 📄 webpack.config.js                          > Webpack file to transpile & bundle JS files.

Build Config

Materio use build-config.js for development and production related build configuration. You can use it to set build configuration i.e buildTemplatePath, buildPath, distPath, minify and sourcemap etc...

Below is the build-config.js file code which contain useful comments to understand the each properties. Make sure you read them carefully.

module.exports = {
  base: {
    // Excludes folders relative to `root` directory.
    exclude: ['html', 'html-starter', 'html-demo', 'dist', 'build', 'assets', 'tasks', 'node_modules', '_temp'],

    // Base Path to Serve from using Browser Sync, Currently set to root of the project
    // You can also point to specific folder like 'build/'
    serverPath: './',

    // Template/Folder to build for production
    buildTemplatePath: 'html/vertical-menu-template',

    // Folder for production build
    buildPath: './build'
  },
  development: {
    // Build path can be both relative or absolute.
    // Current dist path is `./assets/vendor` which will be used by templates from `html\` directory. Set distPath: './dist' to generate assets in dist folder.
    distPath: './assets/vendor',

    // Minify assets.
    minify: false,

    // Generate sourcemaps.
    sourcemaps: true,

    // https://webpack.js.org/configuration/devtool/#development
    devtool: 'eval-source-map',

    // Use this option with caution because it will remove entire output directory.
    // Will affect only and `build` command
    cleanDist: false
  },
  production: {
    // Build path can be both relative or absolute.
    // Current dist path is `./assets/vendor` which will be used by templates from `html\` directory. Set distPath: './dist' to generate assets in dist folder.
    distPath: './assets/vendor',

    // Minify assets.
    // Note: Webpack will minify js sources in production mode regardless to this option
    minify: true,

    // Generate sourcemaps.

    sourcemaps: false,
    // https://webpack.js.org/configuration/devtool/#production
    devtool: '#source-map',

    // Use this option with caution because it will remove entire output directory.
    // Will affect only `build:prod` command
    cleanDist: true
  }
};

Available Tasks

Open command prompt/terminal, go to the Materio root directory and run yarn {task_name}. For example, To generate build run yarn build.
Run a task with specified environment(development/production) just execute the task with --env={environment} option, For example, yarn build --env=production.

Development build

Development tasks use tasks/build.js and generate compiled assets in assets/vendors folder for development purpose.

When you execute build task, it performs the following actions:

  • Read build config options from build-config.js.
  • Run clean task if cleanDist option is true.
  • Run the following gulp tasks in series:
    • build:css Compile each SCSS files which filename is does not starts with a _ symbol and generate CSS.
    • build:js - Collects all .js files which filename is not starting with a _ symbol. Then performs transpile & compilation via Webpack and Babel.
    • build:fonts - Collects fonts file which is defined in the tasks/build.js file as FONT_TASKS and copy them from node_modules.
    • build:copy - Copies images and other font files

Task (yarn or gulp) lists for development build.

Yarn Task Gulp Task Description
yarn serve gulp serve Run the local node server on serverPath (defined in build-config.js) path.
yarn watch gulp watch Watch files for changes and automatically recompile them when it changed.
yarn build gulp build Compile sources and copy assets.
yarn build:css gulp build:css Compile SCSS sources and generate CSS.
yarn build:js gulp build:js Transpile & Compile JS sources using Webpack.
yarn build:fonts gulp build:fonts Copy fonts from node_module/ to fonts/ that defined in the tasks/build.js.
yarn build:copy gulp build:copy Copy images, fonts and other assets files.

Production build

Production tasks use tasks/prod.js and generate build/ folder for production ready html and assets.

When you execute production build task, it performs the following actions:

  • Run all build tasks explained same as above
  • Run the following gulp tasks in series:
    • prodCopyTask tasks will copy html (templatePath only) and assets files to the buildPath
    • prodRenameTasks tasks will replace the assets path.
    • prodUseRefTasks tasks use gulp-useref to concat common js files to core.js to reduce http-requests.

Task (yarn or gulp) lists for production build.

Yarn Task Gulp Task Description
yarn build:prod gulp build --env=production Run build task in production environment.
yarn build:prod:css gulp build:css --env=production Run build:css task in production environment.
yarn build:prod:js gulp build:js --env=production Run build:js task in production environment.
yarn build:prod:fonts gulp build:fonts --env=production Run build:fonts task in production environment.
yarn build:prod:copy gulp build:copy --env=production Run build:copy task in production environment.
© 2017- ThemeSelection, Hand-crafted & Made with ❤️