Creating Your Own Theme
After building and installing the project with the Varbase Project template, use the Drupal Generate Theme using the Vartheme starterkit command.
Before that have a look at:
Understanding The Vartheme Starterkit Theme
Learn more about Bootstrap standard build tools documentation, compile source code, run tests, and more.
https://getbootstrap.com/docs/5.3/getting-started/contribute/#tooling-setup
Install Needed Tools Command
Utilize the command provided in the following link to automatically configure all necessary Node.js or theme processing requirements:
Command to Install Needed Theming Tools
Install Needed Tools Manually
Please refer to the following link for a comprehensive set of instructions or an external resource to guide you through the setup process:
Manually Install Needed Theming Tools
Create new Vartheme BS5 Cloned Generated Theme
How to use the Vartheme BS5 Starterkit
To generate a new theme from Vartheme BS5 using the starterkit/theme-generation script, run the following from Drupal's installation root:
cd PROJECT_DIR_NAME/docrootRun the following Drupal Generate Theme script:
Additionally, you can create the theme's human-readable name and it description with two optional arguments:
This script will copy over all the files from the Vartheme BS5 theme, and replace instances of Vartheme BS5's machine name and label with the strings you provide.
After Installing the New Custom Theme
Uninstall Vartheme BS5 after creating a new theme
At this point the new generated theme will not need the Vartheme BS5 to be installed.
Customizing CSS
The new theme should look and function identically to Vartheme BS5 out of the box, but the styles could be changed to suit the project's needs. Vartheme BS5's styles are written using Bootstrap 5, SASS, PostCSS, which is installed and configured Varbase, and allows CSS authors to write modern CSS while still supporting browsers that have not fully implemented the newest methodologies.
Customizing Bootstrap's JavaScripts
As part of the generate-theme command, the necessary package.json dependencies and scripts files are copied over for the project. Simply install the dependencies and then run yarn theme:init once, and then either the yarn theme:full-build command to compile the assets once or the yarn theme:watch command to re-compile the assets every time a .scss file is changed.
Install the Dependencies for Needed Packages
Recommended to use Yarn, Please do not use npm install
you may run into issue while installing
the list of packages in the package.json was optimized for better use with Yarn
Install Needed YARN and Webpack Tools
Initialize the Theme Once
Ensure that you perform this step immediately after generating and installing packages, or after updating Bootstrap, Font Awesome, or any other necessary extensions.
The theme:init script alias will trigger the execution of webpack --progress --config webpack.config.init.js. This command is responsible for copying the specified files and folders from the webpack.config.init.js configuration file to their respective locations.
Additionally, any additional external libraries from the node_modules folder can be managed by copying them to a designated target libraries folder.
It is essential to include comprehensive "install once" or "configure once" options that can be utilized by new development team members when they join the project for custom theme development or theming. This approach ensures a smooth onboarding process and facilitates seamless setup for new team members.
Compile Once
With webpack, project can compile may type of files and integrate with more nodejs processing tools.
Compile all
Use the following alias script command to compile all SCSS, JS, or SVG icons.
Compile SDC Components Only
In case of working on a custom SDC component, an alias script command can help with the.
The components:build script alias will trigger the execution of webpack --progress --config webpack.config.components.js. This command is responsible only for compiling custom SDC components in the them. The webpack.config.components.js file has the list of entry, and output for compiled css/js/svg script to the right public path.
The theme also ships webpack.config.dev.js for development builds with watch mode and source maps (used by yarn theme:watch), and webpack.config.build.js for the production styling-only build (used by yarn theme:build).
Have a look at the following link for more info:
Compile Custom Theme Styling Only
In case of working on small custom theme styling, which no need to compile components. The following alias script command can help compile in a quick way.
Watching and Syncing
Use to only while working to auto compile custom theme styling
theme:watch is targeted for the theme only, but it can be customized in custom theme
Switching Component References to Your New Theme
After generating your custom theme and setting it as the default theme, Varbase Components automatically migrates all Canvas component IDs, content templates, and entity field data from the old theme to the new one. This is handled by the Active Theme Change Subscriber (ActiveThemeChangeSubscriber), which fires whenever the default theme changes in Drupal's system configuration.
How the Auto-Switch Is Triggered
The Active Theme Change Subscriber listens to the ConfigEvents::SAVE event. When the system.theme configuration is saved, it compares the old and new default theme values. The auto-switch only runs when both the old theme and the new theme have the auto_switch_components: true flag set in their themename.info.yml file.
This flag is already set in Vartheme BS5 and in any theme generated from it using the starterkit. If you create your own theme from a different base, add this flag manually to opt in to the automatic migration.
What the Auto-Switch Does
When triggered, the subscriber runs four sequential migration steps:
Step 1 — Replace Component References in Config Entities
The Replace and Save Theme in Active Configs step scans every active Drupal configuration object (Canvas pages, content templates, entity view displays, and any other config containing SDC component IDs). It processes entity view displays first, then all remaining configs.
For each config it:
Replaces dot-separated SDC component IDs:
sdc.vartheme_bs5.button→sdc.mytheme.buttonReplaces colon-separated legacy plugin IDs:
vartheme_bs5:button→mytheme:buttonReplaces filesystem paths:
themes/contrib/vartheme_bs5/→themes/custom/mytheme/Updates theme dependencies listed in each config's
dependencies.themearray
Component definition configs that belong to the old theme itself (e.g. canvas.component.sdc.vartheme_bs5.*) are intentionally skipped — the new theme already has its own equivalent component definitions and renaming those would cause UUID conflicts on cache rebuild.
Step 2 — Replace Component IDs in Content Entity Field Data
The Replace Theme in Content Entity Component Fields step discovers all content entity types that have fields of type component_tree (used by the Canvas field to store per-entity layout data). For each such field it locates the field data and revision tables in the database and updates the component_id column, replacing the old SDC prefix with the new one.
For example, a stored value of sdc.vartheme_bs5.card becomes sdc.mytheme.card in every row of every affected table.
Step 3 — Replace Theme Paths in Text Fields
The Replace Theme Paths in Text Fields step scans all text, long text, and text-with-summary fields across all content entities for hardcoded theme filesystem paths. It replaces both themes/contrib/vartheme_bs5/ and themes/custom/vartheme_bs5/ with the actual path of the new theme (e.g. themes/custom/mytheme/). This covers cases where editors or content templates embed direct references to theme asset paths in body or rich-text fields.
Step 4 — Fix Stale Component Version Hashes
After the component IDs in config entities are updated, the stored component_version hashes may still reference version snapshots that only existed in the old theme's component config. The Fix Component Versions in Configs step loads the active version of each new-theme component and replaces any invalid stored hash with the correct active version. This prevents Canvas from rendering components with stale or missing version data.
Troubleshooting Theme Switch Issues
In some edge cases the automatic migration may not complete fully — for example if the theme was changed through a recipe, a Drush command, or a batch process that does not fire the standard config save event. The Varbase Components Drush Commands (VarbaseComponentsCommands) expose the same migration logic as the subscriber so it can be run manually, inspected, or re-run after a failure.
Scan for Remaining References to an Old Theme
Before or after a switch, audit which configs and entity rows still reference the old theme name:
Aliases: vc-scan, vcscan
The output is a table with three columns: Source (config or entity_field), Location (the config name or table.column), and Note (number of affected rows or a label marking expected component-definition configs).
Re-run the Full Theme Switch Manually
If references to the old theme are still found after switching, run the full migration manually:
Aliases: vc-switch, vcs
Use --dry-run first to preview what would change without saving anything:
Fix Only Stale Component Version Hashes
If components render with unexpected styles or the Canvas editor shows version errors after a switch, fix only the version hashes without re-running the full migration:
Aliases: vc-fix-versions, vcfv
Reporting Starterkit Bugs
Should you encounter a bug while generating a new theme, please create a new issue
Additional Information
Starterkit is for generating new themes that include reasonably un-opinionated templates and styles that eliminate much of the the initial work required to create a theme.
Starterkit is the recommended approach for creating new themes. For more information, consult the Starterkit documentation on Drupal.org.
Cloning a Project
On the state of working in a team in a project, the created theme could be don by other member of the team.
When the theme get committed by git for example, the node_modules folder will not be committed. As it is listed in the .gitignore file.
After cloning a project with a Vartheme cloned generated theme.
Run the following commands to get all development tools
Last updated