HydePHP v2.0 Upgrade Guide

Overview#

HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.

This document will guide you through the upgrade process. If you want to learn more about the new features, take a look at the Release Notes.

Before You Begin#

Prerequisites#

Before upgrading to HydePHP v2.0, ensure your application is running HydePHP v1.6 or later (ideally v1.8). These versions include transition helpers that will make the migration process smoother.

Backup Your Project#

Before starting the upgrade process, it's strongly recommended to:

Commit all changes to Git - This allows you to easily revert if needed
Create a backup of your entire project directory
Have a previous site build so you can compare output

If you're not already using Git for version control, now is an excellent time to initialize a repository:

git init
git add .
git commit -m "Pre-upgrade backup before HydePHP v2.0"

Estimated Time#

The upgrade process typically takes 30-60 minutes for most projects. Complex sites with extensive customizations may take up to 90 minutes. The majority of this time involves:

Updating and installing dependencies (~15 minutes)
Migrating configuration files (~20 minutes)
Testing and verifying the site (~15-30 minutes)

Step 1: Update Dependencies#

Update Composer Dependencies#

Open your composer.json file and update the following dependencies:

{
    "require": {
        "php": "^8.2",
        "hyde/framework": "^2.0",
        "laravel-zero/framework": "^11.0"
    },
    "require-dev": {
        "hyde/realtime-compiler": "^4.0"
    }
}

Then run:

composer update

The dump-autoload script will likely fail, but this is expected and will be resolved in subsequent steps.

Update Node Dependencies#

Open your package.json file and replace the entire devDependencies section:

Before (v1.x with Laravel Mix):

{
    "devDependencies": {
        "@tailwindcss/typography": "^0.5.2",
        "autoprefixer": "^10.4.5",
        "hydefront": "^3.4.1",
        "laravel-mix": "^6.0.49",
        "postcss": "^8.4.31",
        "tailwindcss": "^3.0.24"
    }
}

After (v2.x with Vite):

{
    "type": "module",
    "devDependencies": {
        "@tailwindcss/typography": "^0.5.0",
        "@tailwindcss/vite": "^4.1.0",
        "autoprefixer": "^10.4.0",
        "hyde-vite-plugin": "^1.1.0",
        "hydefront": "^4.0.0",
        "postcss": "^8.5.0",
        "tailwindcss": "^4.1.0",
        "vite": "^7.1.0"
    }
}

Update the NPM scripts in your package.json:

{
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    }
}

Then run:

npm install

Step 2: Migrate from Laravel Mix to Vite#

Delete the Old Mix Configuration#

Remove the webpack.mix.js file from your project root.

Create the New Vite Configuration#

Create a new vite.config.js file in your project root:

import { defineConfig } from 'vite';
import tailwindcss from "@tailwindcss/vite";
import hyde from 'hyde-vite-plugin';
 
export default defineConfig({
    plugins: [
        hyde({
            input: ['resources/assets/app.css', 'resources/assets/app.js'],
            watch: ['_pages', '_posts', '_docs'],
            refresh: true,
        }),
        tailwindcss(),
    ],
});

Update Your CSS imports#

Update resources/assets/app.css:

Before:

@import '~hydefront/dist/hyde.css';
 
@tailwind base;
@tailwind components;
@tailwind utilities;
 
[x-cloak] { display: none !important; }

After:

@import 'hydefront/components/torchlight.css' layer(base);
 
@import 'tailwindcss';
 
@config '../../tailwind.config.js';

Step 3: Upgrade Tailwind CSS to v4#

Run the automated Tailwind upgrade tool:

npx @tailwindcss/upgrade

Review the Tailwind v4 Upgrade Guide for detailed information about breaking changes in custom configurations.

Step 4: Verify Vite Works#

Now you can run Vite build:

npm run build

Step 5: Update Configuration Files#

Update `config/hyde.php`#

Replace Features With Enum Values#

Before:

'features' => [
    Features::htmlPages(),
    Features::markdownPosts(),
],

After:

'features' => [
    Feature::HtmlPages,
    Feature::MarkdownPosts,
],

Before:

'navigation' => [
    'custom_items' => [
        'Custom Item' => '/custom-page',
    ],
],

After:

'navigation' => [
    'custom' => [
        ['label' => 'Custom Item', 'destination' => '/custom-page'],
    ],
],

Or use the Navigation facade:

use Hyde\Facades\Navigation;
 
'navigation' => [
    'custom' => [
        Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200),
    ],
],

Update Subdirectory Display Setting#

Before:

'navigation' => [
    'subdirectories' => 'hidden',
],

After:

'navigation' => [
    'subdirectory_display' => 'hidden',
],

Update Author Configuration#

If you're using blog post authors, update the configuration format:

Before:

'authors' => [
    Author::create('username', 'Display Name', 'https://example.com'),
],

After:

'authors' => [
    'username' => Author::create(
        name: 'Display Name',
        website: 'https://example.com',
        bio: 'Author bio',
        avatar: 'avatar.png',
        socials: ['twitter' => '@username']
    ),
],

Rename Cache Busting Setting#

Before:

'enable_cache_busting' => true,

After:

'cache_busting' => true,

Remove Deprecated HydeFront Settings#

Remove these configuration options (they're now handled automatically):

'hydefront_version' => ...,
'hydefront_cdn_url' => ...,

Update `config/docs.php`#

Reorganize the sidebar configuration:

Before:

'sidebar_order' => [
    'readme',
    'installation',
],
 
'table_of_contents' => [
    'enabled' => true,
],
 
'sidebar_group_labels' => [
    // ...
],

After:

'sidebar' => [
    'order' => [
        'readme',
        'installation',
    ],
 
    'labels' => [
        // ...
    ],
 
    'table_of_contents' => [
        'enabled' => true,
        'min_heading_level' => 2,
        'max_heading_level' => 4,
    ],
],

Update `app/config.php`#

Add the new navigation service provider under the 'providers' array:

Hyde\Foundation\Providers\NavigationServiceProvider::class,

And add the following classes to the 'aliases' array:

'Vite' => \Hyde\Facades\Vite::class,
'MediaFile' => \Hyde\Support\Filesystem\MediaFile::class,

Step 6: Update Code References#

Routes Facade API Changes#

Before:

$route = Routes::get('route-name');        // Returns null if not found
$route = Routes::getOrFail('route-name');  // Throws exception

After:

$route = Routes::find('route-name');       // Returns null if not found
$route = Routes::get('route-name');        // Throws exception

Asset API Updates#

If you're using asset methods in custom code, note that they now return MediaFile instances:

// Methods renamed for clarity
Hyde::asset('image.png');          // Previously: Hyde::mediaLink()
Asset::get('image.png');           // Previously: Asset::mediaLink()
Asset::exists('image.png');        // Previously: Asset::hasMediaFile()
HydeFront::cdnLink('app.css');     // Previously: Asset::cdnLink()
MediaFile::sourcePath('image.png') // Previously: Hyde::mediaPath()

The MediaFile instances are Stringable and will automatically resolve to relative links, so in most cases (especially in Blade templates), no code changes are needed.

Includes Facade Return Types#

Methods now return HtmlString objects instead of raw strings:

Before:

{!! Includes::html('partial') !!}

After:

{{ Includes::html('partial') }}

Security Note: Output is no longer escaped by default. If you're including user-generated content, use {{ e(Includes::html('foo')) }} for escaping.

DataCollections Renamed#

Before:

use Hyde\Support\DataCollections;

After:

use Hyde\Support\DataCollection;

Step 7: Update Build Commands#

Update any CI/CD pipelines or build scripts:

Before:

npm run prod
php hyde build --run-prod

After:

npm run build
php hyde build --vite

The --run-dev, --run-prod, and --run-prettier flags have been removed. Use --vite instead.

Step 8: Clear Caches#

Next, to ensure we have a clean slate, run the following commands:

composer dump-autoload
php hyde cache:clear
rm app/storage/framework/views/*.php

You may also want to republish any views you have published.

Step 9: Rebuild Your Site#

After completing all the configuration updates:

npm run build
 
# Build your site
php hyde build
 
# Or use the realtime compiler for development
php hyde serve

Step 10: Test Your Site#

Test all navigation menus for correct ordering and appearance
Verify media assets are loading correctly
Check that all pages render properly
Test the search functionality (if using documentation)
Verify author information displays correctly on blog posts
Test dark mode if you're using theme toggle buttons

Migration Checklist#

Use this checklist to track your upgrade progress:

Confirmed running HydePHP v1.6+ (preferably v1.8)
Updated composer.json dependencies
Ran composer update
Updated package.json dependencies and scripts
Added "type": "module" to package.json
Ran npm install
Deleted webpack.mix.js
Created vite.config.js
Updated resources/assets/app.css imports
Ran npx @tailwindcss/upgrade for Tailwind v4
Updated config/hyde.php features to use enum values
Updated navigation configuration to array format
Renamed enable_cache_busting to cache_busting
Removed deprecated HydeFront settings
Updated author configuration format (if using blog)
Reorganized sidebar configuration in config/docs.php
Updated Routes facade method calls (if used in custom code)
Updated Includes facade usage (if used in custom views)
Renamed DataCollections to DataCollection (if used)
Ran npm run build
Ran php hyde build
Tested site menus for correct ordering and appearance
Verified media assets load correctly
Checked all pages render properly
Tested documentation search (if applicable)
Verified blog author information (if applicable)

Troubleshooting#

Assets Not Compiling#

If you encounter issues with asset compilation:

Delete node_modules and package-lock.json
Run npm install again
Clear the _media directory
Run npm run build

Missing Routes#

If you get RouteNotFoundException errors:

Check that you've updated Routes::get() to Routes::find() for cases where the route might not exist
Verify your page source files are in the correct directories

Validation Errors#

If you get syntax validation errors from DataCollection:

Ensure all your YAML/JSON data files have valid syntax
Empty data files are no longer allowed in v2.0

Errors During build#

If you have published Blade views, those may need to be republished if they use old syntax. If you use custom code you may need to look closer at the full release diff.

Getting Help#

If you encounter issues during the upgrade:

Documentation: https://hydephp.com/docs/2.x
GitHub Issues: https://github.com/hydephp/hyde/issues
Community Discord: https://discord.hydephp.com

For the complete changelog with all pull request references, see the full release notes.

Overview#

Before You Begin#

Prerequisites#

Backup Your Project#

Estimated Time#

Step 1: Update Dependencies#

Update Composer Dependencies#

Update Node Dependencies#

Step 2: Migrate from Laravel Mix to Vite#

Delete the Old Mix Configuration#

Create the New Vite Configuration#

Update Your CSS imports#

Step 3: Upgrade Tailwind CSS to v4#

Step 4: Verify Vite Works#

Step 5: Update Configuration Files#

Update config/hyde.php#

Replace Features With Enum Values#

Update Navigation Configuration#

Update Subdirectory Display Setting#

Update Author Configuration#

Rename Cache Busting Setting#

Remove Deprecated HydeFront Settings#

Update config/docs.php#

Update app/config.php#

Step 6: Update Code References#

Routes Facade API Changes#

Asset API Updates#

Includes Facade Return Types#

DataCollections Renamed#

Step 7: Update Build Commands#

Step 8: Clear Caches#

Step 9: Rebuild Your Site#

Step 10: Test Your Site#

Migration Checklist#

Troubleshooting#

Assets Not Compiling#

Missing Routes#

Validation Errors#

Errors During build#

Getting Help#

Update `config/hyde.php`#

Update `config/docs.php`#

Update `app/config.php`#