Package.json for Bootstrap WordPress theme

Steven     30.12.2022

Here are the basics to get started with a fully customizable WordPress theme based on the Bootstrap framework. In it’s most basic form, your custom theme contains 5 files:

  • package.json
    • javascripts/application.js containing all JS code
    • stylesheets/style.scss containing all SCSS code
  • functions.php
  • style.css

1. Package.json

We use Yarn to manage dependencies. Yarn allows very fast installation, and you can utilize script syntax in the package.json file. The core only needs popperjs (a Bootstrap dependency if you want to use dropdowns, tooltips and/or popovers), and furthermore includes esbuild (JS compilation) and SASS (SCSS compilation).

  • yarn build takes ./javascripts/application.js and outputs it minified and bundled to builds/
  • yarn build:css takes ./stylesheets/style.scss and outputs it to builds/, using node_modules as a source load path (for the bootstrap dependency)
# wp-content/themes/my-custom-theme/package.json
  "name": "assistancy",
  "version": "1.0.0",
  "description": "Assistancy bootstrap compiler package",
  "private": true,
  "dependencies": {
    "@popperjs/core": "^2.11.2",
    "bootstrap": "^5.2",
    "bootstrap-icons": "^1.8.1",
    "esbuild": "^0.16",
    "sass": "^1.52.1"
  "browserslist": [
    ">= 0.5%",
    "last 2 major versions",
    "not dead",
    "Chrome >= 60",
    "Firefox >= 60",
    "not Edge < 79",
    "Firefox ESR",
    "iOS >= 10",
    "Safari >= 10",
    "Android >= 6",
    "not Explorer <= 11"
  "scripts": {
    "build": "esbuild javascripts/application.js --bundle --minify --analyze --sourcemap --outdir=builds",
    "build:css": "sass ./stylesheets/style.scss ./builds/style.css --load-path=node_modules",
    "dev": "start yarn build --watch && start yarn build:css --watch"
  "author": "Assistancy",
  "license": "ISC"

Once added, install all dependencies with yarn install


A possible structure of style.scss is as follows. First, import any custom variable overrides, and then import the native Bootstrap stack, followed by any customizations you want to make.

# wp-content/themes/my-custom-theme/stylesheets/style.scss
@import "variables";
@import "../node_modules/bootstrap/scss/bootstrap";

Compile with yarn build:css


Just import the bootstrap namespace to enable the default Bootstrap functionality. Tooltips and popovers require manual initialization.

# wp-content/themes/my-custom-theme/javascripts/application.js
import * as bootstrap from 'bootstrap'

Compile with yarn build


Now that we have our Bootstrap compiled code ready, we still need to say to WordPress to load if from our theme folder. For that, create your functions.php file, and add into it:

# wp-content/themes/my-custom-theme/functions.php

 * Enqueue scripts and styles.
function assistancy_starter_scripts() {  
  // load css
  wp_enqueue_style('assistancy-style', get_stylesheet_directory_uri().'/builds/style.css');
  wp_enqueue_style('custom-style', get_stylesheet_directory_uri().'/style.css');
  // load custom jquery
  wp_enqueue_script('assistancy-custom-js', get_template_directory_uri() . '/builds/application.js', array(), '', true );
add_action( 'wp_enqueue_scripts', 'assistancy_starter_scripts' );



This file contains at the top commented code that WordPress reads in as the theme description. Customize according to your liking. Here is the complete reference. Next to this theme description, the file stays empty, as all our customizations go into stylesheets/style.scss

# wp-content/themes/my-custom-theme/style.css
  Theme Name: Assistancy
  Author: Steven Bellens
  Author URI:
  Description: Assistancy theme, based on the popular Twitter Bootstrap framework
  Version: 1.0.0
  License: GNU General Public License v2 or later
  License URI:
  Text Domain: assistancy

/* Custom css to be added below */



Yay, we’re on the new Bootstrap v5.0.2!

Bootstrap v5 has reached beta status. That means no more new features or breaking changes in the future releases of the V5 branch. We're testing it out on this website.

The right way to serve responsive images (srcset and sizes attribute) with WordPress and Bootstrap 5

The most confusing thing when you inspect responsive images is the fact that the browser takes into account the DPR (Device Pixel Ratio) in order to download the most appropriate image size. Find out here how to serve your visitors responsive images.

WordPress 403 Forbidden after using WordPress app

Wordpress 403 Forbidden errors typically happen with corrupt .htaccess or faulty file/folder permissions. A third common cause is often overlooked: the use of the Wordpress app through XML-RPC.