Renaming Your Theme
Introduction
There are two main reasons you might want to rename a theme in Botble CMS:
- Customization: You want to customize an existing theme and prevent losing your changes when upgrading to a new version
- Branding: You want to change the theme name to match your brand or project name
This guide provides two approaches to rename your theme, depending on your needs.
Method 1: Complete Theme Rename
Important Note
With this method, you won't be able to automatically upgrade the theme through the System Updater. You'll need to manage updates manually.
Option A: Using Command Line (Recommended)
This is the easiest and most reliable method if you have command line access to your server.
Prepare your environment:
bash# Remove vendor directory rm -rf vendor # Reinstall dependencies composer install
Run the theme rename command:
bashphp artisan cms:theme:rename {current_theme} {new_theme}
For example, to rename the "ripple" theme to "shop":
bashphp artisan cms:theme:rename ripple shop
Update theme information: Edit the file
platform/themes/{new_theme}/theme.json
to update:- Theme name
- Description
- Author information
- Version number
Option B: Manual Rename
If you don't have command line access, you can rename the theme manually:
Rename theme directories:
- Rename
platform/themes/{current_theme}
toplatform/themes/{new_theme}
- Rename
public/themes/{current_theme}
topublic/themes/{new_theme}
- Rename
Update database records:
- In the
settings
table: Replace all keys starting withtheme-{current_theme}
totheme-{new_theme}
- In the
widgets
table: Update all values in thetheme
column to the new theme name
- In the
Update theme information: Edit
platform/themes/{new_theme}/theme.json
to update theme detailsClear cache:
- Delete all files in the
storage/framework/cache
directory - Or run
php artisan cache:clear
if you have command line access
- Delete all files in the
Method 2: Public Theme Name Only
Recommended for Theme Updates
This method allows you to keep receiving theme updates through the System Updater while changing how the theme appears publicly.
With this approach, you only change the theme name in public-facing areas while keeping the original theme files intact for updates:
Rename the public theme directory:
bashmv public/themes/{current_theme} public/themes/{new_theme}
Configure environment variable: Add the following line to your
.env
file:CMS_THEME_PUBLIC_NAME={new_theme}
Create custom theme information:
- Copy the theme.json file:bash
cp platform/themes/{current_theme}/theme.json public/themes/{new_theme}/theme.json
- Edit
public/themes/{new_theme}/theme.json
to update theme details
- Copy the theme.json file:
Verifying the Theme Rename
After renaming your theme, verify that everything works correctly:
Clear cache:
bashphp artisan cache:clear
Check admin panel:
- Go to Admin → Appearance → Themes
- Confirm your theme appears with the new name
Check frontend:
- Visit your website
- Verify that all styles and functionality work correctly
Troubleshooting
If you encounter issues after renaming your theme:
- Missing styles: Run
php artisan cms:theme:assets:publish
- Blank pages: Check your error logs in
storage/logs
- Database errors: Verify all database updates were completed correctly
For more detailed information, check this article: Rename Theme in Botble CMS