Home / , / SCSS Compilation for WpResidence WordPress Them

SCSS Compilation for WpResidence WordPress Them

152 views

SCSS Compilation for WpResidence WordPress Theme

This guide explains how SCSS compilation is handled in the WpResidence WordPress theme. We will cover the installation process for a localhost environment, Node.js setup, how to start the watch process, and the SCSS compilation process. Each section also covers practical examples of how to extend the existing code and adjust the theme’s SCSS and CSS files.

1. Prerequisites

Before starting the SCSS compilation process, make sure you have the following tools installed:

  • A local server environment like XAMPP, MAMP, or Local by Flywheel
  • Node.js and npm

The theme should already be installed and running on your localhost.

2. Installing Node.js and npm on Localhost

Step 1: Download and Install Node.js

Download Node.js from the official Node.js website and follow the instructions for your operating system. Once installed, verify that Node.js and npm were successfully installed by running the following commands in your terminal:

node -v
npm -v

Step 2: Initialize Node.js in the WpResidence Theme Directory

Navigate to your WpResidence theme directory via the terminal and initialize npm:

npm init

This will create a package.json file. This file is crucial as it manages all the dependencies and scripts for the theme.

3. Installing Dependencies for SCSS Compilation

Step 1: Install Laravel Mix and SCSS-related Dependencies

To manage the SCSS compilation, we use Laravel Mix, a tool that simplifies the process. Run the following command to install Laravel Mix and the necessary SCSS dependencies:

npm install laravel-mix sass sass-loader autoprefixer --save-dev

These tools help you compile SCSS files into CSS and apply vendor prefixes for better browser compatibility.

Step 2: Verify the package.json Configuration

After installing the dependencies, your package.json should look similar to this:


{
"name": "wpresidence",
"version": "1.0.0",
"scripts": {
"dev": "mix",
"watch": "mix watch",
"prod": "mix --production"
},
"devDependencies": {
"laravel-mix": "^6.0.49",
"sass": "^1.62.1",
"sass-loader": "^13.3.1",
"autoprefixer": "^10.4.2"
}
}

Now, Laravel Mix is ready to compile the SCSS files for your theme.

4. Setting Up SCSS Compilation with webpack.mix.js

Step 1: Create the webpack.mix.js File

The webpack.mix.js file controls how SCSS and JavaScript files are compiled. Create this file in your theme directory if it doesn’t exist. Add the following configuration:


const mix = require('laravel-mix');
mix.sass('scss/app.scss', 'public/css').sourceMaps();

This tells Laravel Mix to compile the app.scss file into public/css/app.css and generate source maps for debugging.

Step 2: Customizing webpack.mix.js for WpResidence

In WpResidence, SCSS files are organized in specific directories. For example, you can compile the main SCSS and dashboard SCSS files into separate CSS files:


mix.sass('scss/app.scss', 'public/css/main.css').sourceMaps();
mix.sass('scss/dashboard.scss', 'public/css/dashboard.css').sourceMaps();

This configuration ensures that main theme styles and dashboard-specific styles are separated.

5. Compiling SCSS Files

Step 1: Running SCSS Compilation for Development

To start SCSS compilation, use the npm run watch command:

npm run watch

This command watches for changes in your SCSS files and automatically compiles them into CSS files whenever a change is detected.

Step 2: Compiling SCSS for Production

For production, run:

npm run prod

This command will compile and minify your SCSS files for faster loading times in production environments.

6. SCSS File Structure in WpResidence

Main SCSS and Dashboard SCSS Compilation

In the WpResidence theme, SCSS files are located in the scss/ directory. The main theme styles are in scss/app.scss, while dashboard styles are in scss/dashboard.scss. These files are compiled into separate CSS files (main.css and dashboard.css) for better organization.

Extending SCSS Compilation

If you want to add new SCSS files, simply include them in your webpack.mix.js file. For example, to add a new SCSS file for forms, you can do the following:


mix.sass('scss/forms.scss', 'public/css/forms.css').sourceMaps();

This will compile the forms.scss file into forms.css and generate a source map.

7. Output and Cache Busting

The compiled CSS files are output in the public/css directory. The file paths are managed by the mix-manifest.json file, which ensures that browsers load the latest versions of the files by appending unique IDs to the filenames.

For example, your mix-manifest.json might look like this:


{
"/public/css/main.css": "/public/css/main.css?id=0ece3f2e82289579b40bcd7155392bd5",
"/public/css/dashboard.css": "/public/css/dashboard.css?id=e067e8f31eb4a8ce346fcb070f832a0b"
}

Versioning and Cache Busting

By using cache busting, you ensure that browsers always load the most recent versions of your compiled CSS and JavaScript files. Laravel Mix appends a unique hash to each file’s URL.

8. Common Issues and Troubleshooting

If you run into issues with SCSS compilation, such as missing dependencies, try running:

npm install

This will reinstall all necessary packages. If you experience SCSS compilation errors, check the terminal for error messages and correct your SCSS syntax accordingly.

Additionally, ensure that the SCSS file paths in your webpack.mix.js file are correct, and check the browser’s developer console to see the source map for debugging.

Compiling Specific SCSS Files into a New CSS File

If you need to compile specific SCSS files into a separate CSS file, you can easily modify your webpack.mix.js configuration to include those SCSS files and output them as a new CSS file.

For example, let’s say you want to compile a set of SCSS files related to form styling into a single forms.css file.

Step 1: Create the SCSS Files

In the scss/ directory of your WpResidence theme, create a new file called forms.scss. You can add your form-related styles here. If you have multiple partial SCSS files for forms, you can include them in forms.scss using @import:


/* scss/forms.scss */
@import 'partials/_form-elements.scss';
@import 'partials/_form-layout.scss';

This way, all form-related styles from the _form-elements.scss and _form-layout.scss files will be combined into forms.scss.

Step 2: Update webpack.mix.js

Next, open your webpack.mix.js file and add a new line to compile forms.scss into forms.css. Here’s an example:


mix.sass('scss/forms.scss', 'public/css/forms.css').sourceMaps();

This line tells Laravel Mix to compile the scss/forms.scss file into public/css/forms.css. The .sourceMaps() method ensures that source maps are generated, making it easier to debug your styles in the browser.

Step 3: Run the SCSS Compilation

To compile your new SCSS file, run the following command:

npm run watch

This will automatically compile the forms.scss file and create the forms.css file in the public/css directory whenever you make changes to the SCSS files.

Step 4: Using the New CSS File

After compilation, the new forms.css file will be available in the public/css folder. You can then enqueue it in your WordPress theme by adding it to your theme’s functions.php file:


function wpresidence_enqueue_styles() {
wp_enqueue_style('wpresidence-forms', get_template_directory_uri() . '/public/css/forms.css', array(), null);
}
add_action('wp_enqueue_scripts', 'wpresidence_enqueue_styles');

This will load the forms.css file on the front end of your site.

Customizing Further

If you need to add more SCSS files to be compiled into the same CSS file, simply add more @import statements inside forms.scss, or create additional SCSS files and include them in the webpack.mix.js file following the same structure.