Back to list
Jürgen Schwind 24 Nov 2025 symfony, bootstrap, scss, php, scssphp, bundle
JBSNewMedia Bootstrap Bundle: SCSS without Node, right inside Symfony

JBSNewMedia Bootstrap Bundle: SCSS without Node, right inside Symfony

Why another Bootstrap bundle?

If you customize Bootstrap in Symfony projects, you’ll quickly end up with SCSS. Many teams reach for Node‑based toolchains — but you don’t have to. The new JBSNewMedia Bootstrap Bundle is fully PHP‑based and uses scssphp to compile your styles. The result: less setup, no extra runtime, sensible defaults.

Features at a glance

  • Ready‑to‑use SCSS entries (light and dark)
  • SCSS ➝ CSS via scssphp (pure PHP, no Node required)
  • Preconfigured import paths for vendor/twbs/bootstrap/scss
  • Optional source maps (--source-map)
  • Sensible defaults: compressed output, standard paths

Requirements

  • PHP ≥ 8.2
  • Symfony 6.4 or 7.x (framework‑bundle, console)
  • Composer
  • Dependencies: twbs/bootstrap (≥ 5.3), scssphp/scssphp (tested from ≥ 1.12)

Note: This is a regular Symfony bundle and is auto‑registered by the kernel.

Installation

composer require jbsnewmedia/bootstrap-bundle

If not already present, Composer will install the required packages (twbs/bootstrap, scssphp/scssphp).

Use in 2 steps

1) Scaffold SCSS entries

php bin/console bootstrap:init
# preview without writing
php bin/console bootstrap:init --dry-run
# overwrite existing files
php bin/console bootstrap:init --force

The following files are created by default:

  • assets/scss/bootstrap5-custom.scss
  • assets/scss/bootstrap5-custom-dark.scss

Both entries import Bootstrap after your variable overrides and in the correct order.

2) Compile SCSS ➝ CSS

php bin/console bootstrap:compile

Defaults:

  • Input: assets/scss/bootstrap5-custom.scss
  • Output: assets/css/bootstrap.min.css
  • Output style: compressed

Generate a source map:

php bin/console bootstrap:compile --source-map

Custom paths:

php bin/console bootstrap:compile path/to/entry.scss public/css/app.css

Command reference

bootstrap:init

Scaffolds Bootstrap SCSS entry files.

  • Options:
  • --dry-run — show pending changes without writing
  • -f, --force — overwrite existing files
  • Alias: boostrap:init (common typo)

The following files are created in assets/scss/:

  • bootstrap5-custom.scss (light)
  • bootstrap5-custom-dark.scss (dark)

Recommended order inside the files: functions → your variables → Bootstrap import.

bootstrap:compile

Compiles SCSS to CSS using scssphp.

  • Arguments:
  • input (optional) — SCSS entry; default assets/scss/bootstrap5-custom.scss
  • output (optional) — CSS target file; default assets/css/bootstrap.min.css
  • Options:
  • --source-map — writes a .map file next to the CSS output

Preconfigured include paths (in this order):

  1. vendor/twbs/bootstrap/scss
  2. vendor
  3. assets/scss
  4. assets

This makes imports without relative paths possible:

@import "functions";
@import "variables";
@import "bootstrap";

Source map behavior

With --source-map, the map is saved after compilation, for example:

  • CSS: assets/css/bootstrap.min.css
  • Map: assets/css/bootstrap.min.css.map

Example output:

Compiled assets/scss/bootstrap5-custom.scss -> assets/css/bootstrap.min.css
Source map written: assets/css/bootstrap.min.css.map

Example SCSS

Light (created by bootstrap:init):

// Project-wide Bootstrap configuration
// -----------------------------------
// Order: load functions first, then override variables,
// finally import Bootstrap.

// 1) Bootstrap functions (used in variable calculations)
@import "functions";

// 2) Your variable overrides (omit !default so they apply)
$primary: #ff0000;

// 3) Optional: Bootstrap base variables
@import "variables";

// 4) Import full Bootstrap
@import "bootstrap";

Dark (created by bootstrap:init):

// Dark-mode build for Bootstrap
// -----------------------------------
// 1) Bootstrap functions
@import "functions";

// 2) Dark-specific variables
$body-bg: #121212;
$body-color: #e6e6e6;
$primary: #0d6efd;

// Optional: additional maps/variables
@import "variables";

// 3) Import full Bootstrap
@import "bootstrap";

Troubleshooting

  • Input file not found
  • Run php bin/console bootstrap:init to create default entries, or pass your own path to bootstrap:compile.
  • Bootstrap imports are not resolved
  • Check whether twbs/bootstrap is installed: composer require twbs/bootstrap.
  • Source map comment is present, but no file is written
  • The map is written at the end of the build. Check that --source-map is set and that your SCSS source actually produces output.
  • scssphp versions
  • Since scssphp ≥ 1.12, source map constants live on Compiler. The bundle is aligned with that.

Conclusion

The JBSNewMedia Bootstrap Bundle is ideal if you want to build Bootstrap SCSS in Symfony without a Node toolchain. Simple commands, sensible defaults, and vendor‑aware import paths provide a fast, reliable workflow — powered purely by PHP.

Links