If you built a Varbase site a few years ago, the theming workflow you remember is gone. The bash scripts, the Bootstrap 4 base theme, and the Gulp pipeline that older guides describe do not match what current Varbase ships. The current path is shorter and more standard: you generate a sub-theme from Vartheme BS5 with Drupal core's own theme generator, then build it with the theme's Yarn and webpack 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.
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.
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.
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:init
Run 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-build compiles everything: SCSS, JavaScript, and SVG icons.
yarn theme:watch recompiles on every .scss change during development.
yarn theme:build compiles theme styling only, without components.
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: true
Vartheme 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_bs5
Preview a full migration without saving anything, then run it for real:
If components render with unexpected styles or Canvas shows version errors, fix only the stale version hashes:
drush varbase-components:fix-versions mytheme
What 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-build
How 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.
Raghad Eid is a content strategist at Vardot, a Drupal Diamond Certified Partner and Drupal AI Initiative Gold Sponsor. She writes on enterprise CMS architecture, headless Drupal, and digital experience platforms.
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.
