jbsnewmedia/bootstrap-bundle

Lightweight tools to scaffold and compile Bootstrap SCSS using scssphp. Provides console commands (bootstrap:init, bootstrap:compile) with sensible defaults and vendor-aware import paths.

1.0.0 2025-11-24 15:20 UTC

Requires

• php: >=8.2
• scssphp/scssphp: *
• symfony/console: ^6.4 || ^7.0
• symfony/framework-bundle: ^6.4 || ^7.0
• twbs/bootstrap: ^5.3

MIT

• Juergen Schwind

README

A lightweight Symfony bundle that helps you scaffold and compile Bootstrap SCSS with scssphp. It ships two console commands:

• bootstrap:init — scaffolds SCSS entry files under assets/scss/.
• bootstrap:compile — compiles SCSS to CSS (with sensible defaults and vendor‑aware import paths).

🚀 Features

• Ready‑to‑use SCSS entries (light and dark)
• SCSS → CSS via scssphp (pure PHP, no Node required)
• Include paths for vendor/twbs/bootstrap/scss out of the box
• Optional source maps (--source-map)
• Clean defaults: compressed output, standard paths

⚙️ Requirements

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

Note: This is a regular Symfony bundle and expects a Symfony kernel (it is auto‑registered).

📦 Installation

Install via Composer:

composer require jbsnewmedia/bootstrap-bundle

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

📋 Usage

1) Scaffold SCSS entries

Create the default SCSS entry files under assets/scss/:

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

Files created:

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

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

2) Compile SCSS → CSS

Compile with sensible defaults:

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 input/output 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 what would be written without creating files
  • -f, --force — overwrite existing files
• Alias: boostrap:init (common typo)

Creates the following files in assets/scss/:

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

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

bootstrap:compile

Compiles SCSS to CSS using scssphp.

• Arguments:
  • input (optional) — SCSS entry file; default assets/scss/bootstrap5-custom.scss
  • output (optional) — CSS output file; default assets/css/bootstrap.min.css
• Options:
  • --source-map — write 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 allows imports like:

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

Source map behavior

When using --source-map, the generated map is saved after compilation:

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

Example console output:

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

If no map is written even though --source-map is set, please check that your SCSS source actually produces output and that the defaults were not overridden.

✍️ Example SCSS

Light (created by bootstrap:init):

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

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

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

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

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

Dark (created by bootstrap:init):

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

// 2) Set dark-specific variables (adjust examples as needed)
$body-bg: #121212;
$body-color: #e6e6e6;
$primary: #0d6efd;

// Optional: load additional maps/variables from Bootstrap
@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 not resolved
  • Ensure twbs/bootstrap is installed: composer require twbs/bootstrap.
• Source map comment is present, but no file is written
  • With the current implementation the map is written after compilation. Check that --source-map is set and your SCSS produces content.
• scssphp versions
  • Since scssphp ≥ 1.12, source map constants live on Compiler. This bundle is aligned with that change.

📜 License

Licensed under the MIT License. See the LICENSE file for details.

Developed by Juergen Schwind and contributors.

🤝 Contribution

Contributions are welcome! Please fork the repository and open a pull request. For larger changes, consider opening an issue first to discuss your idea.

📫 Contact

For questions or issues, please open an issue or a pull request in the repository.

— Simple Bootstrap SCSS scaffolding and compilation, Composer‑native.