How to Create a Custom Theme in Varbase
If your last Varbase theme involved bash scripts, Bootstrap 4, and Gulp, none of that describes how current Varbase works. The current path is shorter and runs on Drupal core's own tooling. This guide covers that current process for a developer creating a custom Varbase theme on a current Varbase project, including the automatic component migration that older guides never mention.
Key Takeaways
- Generate the sub-theme with Drupal core's generate-theme against the vartheme_bs5 starterkit, then build with Yarn and webpack.
- Use Yarn, not npm. The package list is not supported under npm and installs can fail.
- Varbase Components migrates Canvas component IDs and field data automatically when auto_switch_components is set.
- The failure mode after a theme switch is stale component references, not broken styling.
Creating a custom Varbase theme means generating a sub-theme from Vartheme BS5 with Drupal core's generate-theme script, then compiling its Bootstrap 5 SCSS and Single Directory Components with the theme's Yarn and webpack tooling. Varbase Components migrates your component references from the base theme to the new one automatically when you set it as default.
What Changed in Varbase Theming?
Varbase theming moved off bespoke scripts and onto Drupal core tooling. The old approach shipped a Bootstrap 4 base theme, created sub-themes with a project-specific shell script, and compiled styles with Gulp. Current Varbase replaces all three pieces with standard Drupal and front-end tools. The current line, Varbase 11.0.x, runs on Drupal 11 with Bootstrap 5.3.
The table below maps the older workflow to the current one.
| Task | Older Varbase (BS4) | Current Varbase (BS5) |
|---|---|---|
| Base theme | Vartheme BS4 (Bootstrap 4) | Vartheme BS5 (Bootstrap 5) |
| Create a theme | Custom bash script or yarn theme:create-sub-theme | Drupal core generate-theme --starterkit vartheme_bs5 |
| Style compilation | Gulp | webpack, run through Yarn script aliases |
| Component model | Theme-level SCSS partials | Single Directory Components (SDC) with CVA variants |
| Package manager | Mixed npm and Yarn | Yarn (npm install is discouraged) |
| Component migration on theme switch | None (no SDC/Canvas component model in the BS4 era) | Automatic, via Varbase Components |
Vartheme BS5 also adds a design-system layer the older base theme did not have: Single Directory Components bundle each component's Twig, SCSS, JavaScript, and metadata in one folder, and CVA (Class Variance Authority) manages component variants such as button size and color from a single definition.
That component library is published as a design system in Storybook, which teams use as the visual reference for the components available to them.
What the Shift Means for How You Build a Theme
The practical effect is that a custom Varbase theme is now mostly a thin sub-theme. Drupal core's generate-theme produces a working copy of Vartheme BS5 under your own name, so you inherit the Bootstrap 5 grid, the SCSS structure, the Single Directory Components, and the CVA variant system without rebuilding any of it.
Your work narrows to overrides: Bootstrap variables, component SCSS, and the occasional new component. That is less code to own, and less to break when Varbase or Bootstrap updates.
The Theme Is No Longer Where Your Design System Lives
Our view: in current Varbase, the visible styling is a thin sub-theme, but the design system lives in the component layer, not in your theme's CSS. The state that matters after you create a theme is which components a page uses, how Canvas references them, and the version hashes behind them, and all of that lives in configuration and entity data rather than in SCSS.
That is why Varbase automates the theme switch instead of leaving it to a find-and-replace. The failure mode to watch after a switch is stale component references, not broken styling, which is exactly what the automatic migration exists to prevent. Treat the component-reference migration as the real deliverable of creating a theme, and treat the styling as the easy part.
How Do You Create a Custom Theme in Varbase?
Creating a custom theme in Varbase takes five steps: generate the sub-theme, set it as default, install the build tools, compile, and let Varbase migrate your component references. The steps below assume a project built from the Varbase Project template.
Step 1: Generate the Sub-Theme From Vartheme BS5
Generate the theme with Drupal core's generate-theme script, run from your project's docroot against the vartheme_bs5 starterkit.
cd PROJECT_DIR_NAME/docroot
php core/scripts/drupal generate-theme mytheme \
--starterkit vartheme_bs5 \
--path themes/custom \
--name "MyTheme" \
--description "Custom theme generated from Vartheme BS5"The script copies the Vartheme BS5 files into themes/custom/mytheme and replaces the base theme's machine name and label with the ones you provide. The --name and --description arguments are optional.
Step 2: Set Your Theme as Default and Uninstall Vartheme BS5
Set your generated theme as the site's default theme, then uninstall Vartheme BS5. The generated theme is self-contained, so once it is the default, the base theme no longer needs to be installed. Your theme should look and behave identically to Vartheme BS5 out of the box.
Step 3: Install the Build Tools With Yarn
Install the theme's dependencies with Yarn from inside the theme directory, then initialize the theme once. Use Yarn rather than npm: the package list is optimized for Yarn, and npm install can fail.
cd themes/custom/mytheme
yarn install
yarn theme:initRun yarn theme:init once after installing, and again after upgrading Bootstrap, Font Awesome, or other vendor packages. It copies vendor files from node_modules into the theme's libraries folder. The theme's package.json requires Node.js 20 or newer and Yarn 4.9.3 or newer, and Yarn is required because the package list is not supported under npm. For the operating-system packages and any later version bumps, follow the Varbase "install needed theming tools" documentation.
Step 4: Compile Your Styles and Components
Compile with the theme's Yarn script aliases. Each alias maps to a specific webpack configuration.
yarn theme:full-buildcompiles everything: SCSS, JavaScript, and SVG icons.yarn theme:watchrecompiles on every.scsschange during development.yarn theme:buildcompiles theme styling only, without components.yarn components:buildcompiles custom SDC components only.
Restyle by overriding Bootstrap 5 SCSS variables and editing component SCSS, which is how Vartheme BS5 is designed to be customized.
Step 5: Let Varbase Migrate Your Component References
When you set your generated theme as default, Varbase Components migrates Canvas component IDs, content templates, and entity field data from Vartheme BS5 to your theme automatically. The Active Theme Change Subscriber fires when Drupal saves the system.theme configuration, and it runs only when both the old and the new theme carry auto_switch_components: true in their info.yml file.
# mytheme.info.yml
auto_switch_components: trueVartheme BS5 and every theme generated from it already set this flag, so for the standard workflow the migration happens without any extra action. The subscriber replaces component IDs in config entities, updates component IDs in content-entity field data, rewrites hardcoded theme paths in text fields, and fixes stale component version hashes.
How Do You Fix Component References if the Auto-Switch Does Not Run?
Run the Varbase Components drush commands when the automatic migration does not complete, for example when the theme was changed through a recipe, a Drush command, or a batch process that does not fire the standard config-save event. The commands expose the same migration logic so it can be inspected or re-run.
Audit which configs and entity rows still reference the old theme:
drush varbase-components:scan-refs vartheme_bs5Preview a full migration without saving anything, then run it for real:
drush varbase-components:switch-theme vartheme_bs5 mytheme --dry-run
drush varbase-components:switch-theme vartheme_bs5 mythemeIf components render with unexpected styles or Canvas shows version errors, fix only the stale version hashes:
drush varbase-components:fix-versions mythemeWhat About Cloning a Project That Already Has a Custom Theme?
Rebuild the theme's tooling after cloning, because the node_modules folder is gitignored and does not travel with the repository. When a teammate clones a project that already contains your generated theme, they need to reinstall and recompile before the theme's assets exist locally.
cd PROJECT_DIR_NAME/docroot/themes/custom/THEME_NAME
yarn install
yarn theme:init
yarn theme:full-buildHow Does a Custom Theme Work With Drupal Canvas?
Your custom theme supplies the components that editors assemble in Drupal Canvas, the visual page builder that ships with Varbase and Vartheme BS5. Canvas lets editors build and manage pages, regions, and components with no code: they drag Single Directory Components from a Library, arrange them in a Layers panel, edit global regions such as the header and footer, and set component props like a hero slider's autoplay or a button's style. Varbase also ships a Canvas AI Agent that can assemble pages from a prompt.
This is why creating a theme and migrating component references are the same job. When editors build pages in Canvas, Drupal stores which of your theme's components each page uses.
Generate a new theme, and those stored references still point at Vartheme BS5 until Varbase Components migrates them, which is the automatic step covered above. Your theme defines the components; Canvas is where they get used.
Where to Go Next
If you are setting up theming on a Varbase project, the Varbase theme-development documentation covers the Vartheme BS5 architecture, the exact tool versions, the drush commands referenced here, and how theming connects to Drupal Canvas. It is the reference to keep open while you work, especially for teams standardizing a component-driven build across several sites.
Building theming on a Varbase project? Keep the Varbase theme-development documentation open while you work.
FAQs
Create a custom theme in Varbase 11 by generating a sub-theme from Vartheme BS5 with Drupal core's generate-theme script: run "php core/scripts/drupal generate-theme mytheme --starterkit vartheme_bs5 --path themes/custom" from the docroot. Set the new theme as default, uninstall Vartheme BS5, then install and compile its assets with Yarn.
No. Varbase 11 themes are built with webpack, run through Yarn script aliases, not Gulp. Use "yarn theme:full-build" to compile SCSS, JavaScript, and icons, "yarn theme:watch" to recompile on change during development, and "yarn components:build" to compile custom Single Directory Components only.
Vartheme BS5 is the default Bootstrap 5 front-end theme for Varbase 11. It provides a responsive grid, SCSS with variable overrides, Single Directory Components, and CVA variant management. A custom Varbase theme is generated as a sub-theme of Vartheme BS5, inheriting this architecture out of the box.
Varbase Components migrates component references automatically when you set a generated theme as default. Its Active Theme Change Subscriber updates Canvas component IDs, content templates, entity field data, and version hashes. If it does not run, the drush commands varbase-components:switch-theme and varbase-components:fix-versions perform the same migration manually.
Use Yarn for Varbase theme tooling. The theme's package list is optimized for Yarn, and running npm install can cause installation problems. After generating a theme, run "yarn install" then "yarn theme:init" once, and use the theme's yarn build aliases to compile styles and components.