Skip to content
This repository was archived by the owner on Dec 16, 2025. It is now read-only.

Update migration documentation. #8

Merged
jaymeh merged 1 commit into from
Aug 29, 2025
Merged

Update migration documentation. #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 47 additions & 35 deletions docs/migrating-from-theme-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Follow the [installation guide](/installation) to install the Creode WordPress T
Using composer, remove the theme core from your project.

```bash
composer remove creode/theme-core
composer remove creode/wordpress-theme-core
```

### 4: Remove the installer path for theme core
Expand All @@ -33,43 +33,55 @@ In your composer.json file remove the following line:
```jsonc
{
// ... other composer.json code ...
"extra": { // [!code --]
"installer-paths": { // [!code --]
"wp-content/themes/gibraltar-international-bank/core/": ["type:wordpress-themecore"] // [!code --]
} // [!code --]
} // [!code --]
"extra": { // [!code --]
"installer-paths": { // [!code --]
"wp-content/themes/gibraltar-international-bank/core/": ["type:wordpress-themecore"] // [!code --]
} // [!code --]
} // [!code --]
// ... other composer.json code ...
}
```

### 5: Remove the requirement of the theme-core boot file
### 5: Add the new theme framework to your project
Require the new theme framework into your project.

```bash
composer require creode/wordpress-theme
```

### 6: Add the new mu-plugin to your .gitignore file
Add the following line to your .gitignore file:

`/wp-content/mu-plugins/wordpress-theme*`

### 7: Remove the requirement of the theme-core boot file
Remove the following line from your `functions.php` file.

```php
require_once get_template_directory() . '/core/boot.php'; // [!code --]
```

### 6: Replace class of register_vite_script function
### 8: Replace class of register_vite_script function
The assets class from theme core has been removed and instead is now replaced with a function from the new theme framework.

You will need to replace all occurrences and function calls:
```php
use Creode_Theme\Asset_Enqueue; // [!code ++]

function [[THEME_NAME]]_enqueue_script() {
Assets::register_vite_script( 'header', 'src/components/header.js', array( 'jquery' ), true ); // [!code --]
Assets::register_vite_script( 'header', 'src/components/header.js', array( 'jquery' ), true ); // [!code --]

$asset_enqueue = Asset_Enqueue::get_instance(); // [!code ++]
$asset_enqueue->register_vite_script( 'header', 'src/components/header.js', array( 'jquery' ), true ); // [!code ++]
// ... other required code ...
$asset_enqueue = Asset_Enqueue::get_instance(); // [!code ++]
$asset_enqueue->register_vite_script( 'header', 'src/components/header.js', array( 'jquery' ), true ); // [!code ++]
// ... other required code ...
};
add_action( 'wp_enqueue_scripts', '[[THEME_NAME]]_enqueue_script' );
```

This will now ensure that all JS is loaded from Vite correctly.

### 7: Remove hot reloading from your vite config file.
### 9: Remove hot reloading from your vite config file.
Hot reloading was a feature that was a little buggy on the theme core. It is therefore no longer supported in the new theme framework. There may be plans in future to reintroduce this feature.

In order to remove hot reloading, you will need to remove the following line from your vite config file.
Expand All @@ -79,19 +91,19 @@ import { manageHotReloadFile } from './core/js/hot-reload.js'; // [!code --]

export default defineConfig(
(command) => {
manageHotReloadFile(command.mode, DDEV_HOSTNAME, HOT_RELOAD_PORT); // [!code --]
manageHotReloadFile(command.mode, DDEV_HOSTNAME, HOT_RELOAD_PORT); // [!code --]

// ... other vite config code ...
// ... other vite config code ...
}
);
```

### 8: Move your SCSS folder up a level
### 10: Move your SCSS folder up a level
In the previous version of the theme core framework, the SCSS folder was located within the `src` folder. As part of this migration, you will need to move the SCSS folder up a level to the root of the project. The `SCSS` folder should now be located in the root of the theme.

For example if you had a `src/scss` folder in the theme, it should now be moved to the root of the theme to `scss/`.

### 9: Migrate the component specific CSS files up to the component directory
### 11: Migrate the component specific CSS files up to the component directory
As part of the changes to how blocks are handled, the SCSS files for each block should now be moved to their relevant block folder.

For example a header.scss component file will now be located in the following folder based on the theme root: `/blocks/header-block/assets/header.scss`.
Expand All @@ -100,17 +112,12 @@ Each of these components should be moved to their relevant block folder.

This is a change that will need to be done manually and can be quite tedious however it will ensure that all themes and blocks are kept consistent in the future.

### 10: Remove individual components imports from the `admin.scss` and `main.scss` files
### 12: Remove individual components imports from the `admin.scss` and `main.scss` files
As part of the changes to how blocks are handled, the individual components `@use` and `@include` from the `admin.scss` and `main.scss` files are no longer required. These are now handled by the theme framework and will be automatically added to the theme in a new `blocks/_all.scss` file.

This is a change that will need to be done manually and can be quite tedious however it will ensure that all themes and blocks are kept consistent in the future.

You can recompile the assets to check over your changes periodically during this process by running the following WP CLI command:
```bash
wp creode-theme:build
```

### 11: Clean up scss import paths
### 13: Clean up scss import paths
After moving the SCSS files to their relevant block folder, you will need to clean up the `@use` paths for each of the SCSS files. Paths to scss files in vite can be absolute based on where the `vite.config.js` file is located. In this case it will be in the theme.

An example of this is demonstrated below with pulling the global file into the `header.scss` file:
Expand All @@ -122,29 +129,34 @@ An example of this is demonstrated below with pulling the global file into the `

This change can be quite tedious to do manually however we want to ensure that all themes keep the same structure and paths so a change like this will help our projects stay consistent in the future.

### 12: Run the script to install any framework files and compile assets
### 14: Run the script to install any framework files and compile assets
As part of the theme framework, there is a WordPress CLI command that will install any missing files and compile the assets. This ensures that the structure of the theme is kept consistent and that new files as part of the boilerplate can be added automatically to themes without having to keep track of them manually.

### 13: Remove the admin and main js files from src
As part of the framework, the main.js and admin.js within the `src` folder are no longer required. These are now handled by the theme framework and will be automatically added to the theme in a new `vite-entry-points` folder. These files are no longer required and can be removed from the `src` folder, if there is more content to them, ensure this is now merged with the newly created equivalent files in the `vite-entry-points` folder.
```bash
wp creode-theme:install
```

You should now be able to see some new files in your theme alongside a new `vite-entry-points` folder with the new admin.js and main.js files. You should copy the contents of the `src/main.js` and `src/admin.js` files into the corresponding new `vite-entry-points` folder, apart from the import lines for scss as these should be updated to the new new `/scss/` folder.

Once this has been done, you can remove the old `src/main.js` and `src/admin.js` files from your theme.

### 14: Update the vite config file to switch these entrypoints over
### 15: Update the vite config file to switch these entrypoints over
The `vite.config.js` file will need to be updated to switch these entrypoints over to the new `vite-entry-points` folder.

```js
export default defineConfig(
(command) => {
return {
// ... other vite config code ...
// ... other vite config code ...
build: {
rollupOptions: {
// overwrite default .html entry
input: {
main: resolve(__dirname, 'src/main.js'), // [!code --]
main: resolve(__dirname, 'src/main.js'), // [!code --]
admin: resolve(__dirname, 'src/admin.js'), // [!code --]
main: resolve(__dirname, 'vite-entry-points/main.js'), // [!code ++]
main: resolve(__dirname, 'vite-entry-points/main.js'), // [!code ++]
admin: resolve(__dirname, 'vite-entry-points/admin.js'), // [!code ++]
// ... other vite config code ...
// ... other vite config code ...
}
}
}
Expand Down Expand Up @@ -175,7 +187,7 @@ Add the following to the top of the `main.scss` file:

This will ensure that all blocks are loaded into the theme.

### 16: Import the new `blocks/_all.scss` file into the admin.scss file
### 17: Import the new `blocks/_all.scss` file into the admin.scss file
This process is very similar to the `main.scss` file however you will need to ensure that any admin specific mixins are handled manually using the new folder location. The new blocks all file only handle the render mixin and admin ones will need to be handled manually. See the below example for how this has changed:

```scss
Expand Down Expand Up @@ -206,7 +218,7 @@ Add the following to the `admin.scss` file:
@include blocks.render; // [!code ++]
```

### 17: Recompile the assets
### 18: Recompile the assets
Once these steps have been completed, you will need to recompile the assets. This can be done by running the following WP CLI command:

```bash
Expand Down