Table of Contents

1. Introduction
2. Prerequisites
3. Installation
   1. Setting Up the Local Environment
   2. Installing Node.js and npm
   3. Installing Dependencies
4. SCSS and CSS Structure
   1. File Structure
   2. Creating SCSS Files for Components
   3. Creating Variables
5. Using Bootstrap
   1. Installing Bootstrap
   2. Importing Bootstrap in SCSS
6. Compiling SCSS to CSS
7. How Compiled CSS and JS are Added
8. Example: Changing and Compiling CSS
9. Summary

Introduction

This document provides detailed instructions on integrating SCSS, CSS, and Bootstrap into the WpResidence WordPress theme. The guide covers everything from setting up the local development environment to compiling SCSS into CSS, making it easier for developers to maintain and extend their theme styles.

Prerequisites

• A local development environment (Local by Flywheel is strongly recommended or XAMPP)
• Node.js and npm installed on your machine to manage dependencies and build processes
• Basic knowledge of WordPress theme development, including PHP, HTML, and CSS

Installation

Setting Up the Local Environment

1. Download and Install Local by Flywheel or XAMPP/WAMP/MAMP:
   • We strongly recommend using Local by Flywheel for its ease of use and dedicated WordPress environment support.
2. Set Up WordPress: Create a new WordPress site using your chosen local environment tool.
3. Download and Install WpResidence Theme:
   • Place the WpResidence theme folder in the wp-content/themes/ directory of your WordPress installation.
   • Activate the theme in your WordPress dashboard under Appearance > Themes.

Installing Node.js and npm

1. Download and Install Node.js:
   • Download Node.js from Node.js. It includes npm, which is essential for managing packages.
2. Verify Installation:
   • To ensure Node.js and npm are correctly installed, open your terminal and run:
     node -v and npm -v

     If you see the installed version numbers, your setup is complete.

Installing Dependencies

1. Navigate to Theme Directory:
   • In your terminal, navigate to your theme’s root directory:
     cd path/to/your/theme
2. Initialize npm:
   • Run the following command to initialize npm:
     npm init -y

     This creates a package.json file to track project dependencies.

3. Install Laravel Mix and Other Dependencies:
   • Run:
     npm install

     This installs all required dependencies, such as Laravel Mix and Bootstrap.

SCSS and CSS Structure

File Structure

Your theme should have a logical and modular file structure. Here’s an example:

/path/to/your/theme
├── scss/
│   ├── components/
│   │   ├── _buttons.scss
│   │   ├── _cards.scss
│   ├── _variables.scss
│   ├── main.scss
├── public/
│   ├── css/
│   │   └── main.css
│   ├── js/
│   │   └── app.js
├── webpack.mix.js
├── package.json

Creating SCSS Files for Components

1. Organize SCSS Components: For example, keep button-related styles in scss/components/_buttons.scss.
2. Link Components in main.scss: Import all component SCSS files into your main.scss.

// main.scss
@import "~bootstrap/scss/bootstrap";
@import "variables";
@import "components/buttons";


Example: Changing and Compiling CSS

By following these instructions, you can effectively manage your styles and integrate Bootstrap seamlessly with your WordPress theme. Remember to test changes by compiling and viewing updates in your browser.

Understanding webpack.mix.js and package.json in WpResidence Theme

In the WpResidence theme, the webpack.mix.js and package.json files are located in the root directory of the theme. These files are essential for managing and automating the compilation and optimization of SCSS, JavaScript, and other assets. Here’s how they work specifically in the context of the WpResidence theme:

package.json

The package.json file in the root of the WpResidence theme provides important metadata about the project and defines the dependencies and scripts for asset management. Here’s a breakdown:

• name and version: The project name is set as wpresidence, and the version reflects the current theme version.
• description: Provides a summary of the WpResidence theme and its purpose as a premium real estate WordPress theme.
• main: Specifies the primary JavaScript configuration file, which is webpack.mix.js.
• scripts: Defines commands that simplify development tasks:
  • npm run dev: Compiles assets in development mode for testing.
  • npm run watch: Continuously monitors for changes and automatically rebuilds assets.
  • npm run prod: Creates production-ready, minified CSS and JS files for optimal performance.
  • npm run purge: Executes a custom script to remove unused CSS, improving efficiency.
• dependencies: Includes required libraries like:
  • bootstrap: Provides a robust CSS framework for the theme’s design.
  • @popperjs/core: Enables Bootstrap’s tooltips and popovers functionality.
• devDependencies: Lists tools for development, including:
  • laravel-mix: Simplifies Webpack configuration for compiling SCSS and JavaScript.
  • sass and sass-loader: Convert SCSS files into CSS.
  • postcss: Adds CSS processing tools like autoprefixers for browser compatibility.

webpack.mix.js

The webpack.mix.js file, also located in the root of the WpResidence theme, defines how SCSS and JavaScript files are compiled and optimized. It works seamlessly with the theme’s file structure to ensure assets are ready for both development and production environments. Here’s a detailed look:

• Public Path:

  The line mix.setPublicPath(themeDir); ensures that the compiled files are output to the public/css and public/js directories within the theme folder.

• SCSS Compilation:

  All SCSS files in the scss/ directory are compiled into a single main.css. This is the primary CSS file used by the theme.

  mix.sass(file, path.join(cssOutputDir, 'main.css')).sourceMaps();

• RTL Support:

  If an rtl.scss file exists, it is compiled into a separate rtl.css file to support right-to-left languages.

  mix.sass(rtlScssPath, path.join(cssOutputDir, 'rtl.css')).sourceMaps();

• Dashboard SCSS:

  The scss/dashboard/ folder contains styles specifically for the theme’s dashboard, which are compiled into dashboard.css.

  mix.sass(dashboardScssPath, path.join(cssOutputDir, 'dashboard.css')).sourceMaps();

• JavaScript Compilation:

  Custom JavaScript files like app.js are bundled and output to the public/js directory. Source maps are generated for easier debugging.

  mix.js(appJsPath, `${jsOutputDir}/app.js`).sourceMaps();

• Bootstrap Integration:

  The Bootstrap JavaScript bundle is copied directly from node_modules to public/js, ensuring the theme uses the latest version of Bootstrap.

  mix.copy('node_modules/bootstrap/dist/js/bootstrap.bundle.min.js', `${jsOutputDir}/bootstrap.bundle.min.js`);

• Performance Optimization:

  Webpack is configured to minimize files, disable unnecessary code splitting, and suppress warnings for a smoother build process.

  optimization: { minimize: true, splitChunks: false }

• Custom Plugins:

  A custom plugin suppresses warnings during compilation, keeping the console output clean and focused.

  new SuppressWarningsPlugin()

Workflow in WpResidence

The combination of package.json and webpack.mix.js provides a robust development workflow for the WpResidence theme. The typical process includes:

1. Installing Dependencies: Run npm install in the root directory of the theme to install all necessary packages.
2. Development Builds: Use npm run dev or npm run watch to compile assets in real-time during development.
3. Production Builds: Run npm run prod to create optimized CSS and JavaScript files for live use.
4. CSS Cleanup: Execute npm run purge to remove unused styles, reducing the CSS file size.

In the WpResidence theme, the webpack.mix.js and package.json files play a critical role in managing and optimizing assets. They are designed to streamline development, ensure compatibility, and produce high-quality, efficient code for both the back-end and front-end of the theme. By leveraging these tools, developers can maintain a scalable and maintainable workflow.