Skip to content

Sage 10 to 11 Migration

• By Jasper Frumau

We have migrated our theme from Sage 10 to Sage 11. This involves several key changes due to the shift from Bud to Vite as the new build tool in Sage 11.

Vite Configuration

To begin with, I’ve added a list of steps to guide the migration process. One of the first things I did was create a new vite.config.js file, which replaces the old bud.config.js used in Sage 10. Since Sage 11 now uses Vite, updating your asset pipeline configuration is essential.

Next, I replaced all references to the default sage theme name with the name of our custom theme: nynaeve. So you wind up with this including base adjustment

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite';
import laravel from 'laravel-vite-plugin'
import { wordpressPlugin, wordpressThemeJson } from '@roots/vite-plugin';

export default defineConfig({
  base: '/app/themes/nynaeve/public/build/',
  plugins: [
    tailwindcss(),
    laravel({
      input: [
        'resources/css/app.css',
        'resources/js/app.js',
        'resources/css/editor.css',
        'resources/js/editor.js',
      ],
      refresh: true,
    }),

    wordpressPlugin(),

    // Generate the theme.json file in the public/build/assets directory
    // based on the Tailwind config and the theme.json file from base theme folder
    wordpressThemeJson({
      disableTailwindColors: false,
      disableTailwindFonts: false,
      disableTailwindFontSizes: false,
    }),
  ],
  resolve: {
    alias: {
      '@scripts': '/resources/js',
      '@styles': '/resources/css',
      '@fonts': '/resources/fonts',
      '@images': '/resources/images',
    },
  },
})

NB The bud.config.js and jsconfig.json should be removed

Package.json Update

We of course needed to update the JS package.json . We basically copied the boilerplate code over from the Sage 11 theme:

{
  "name": "nynaeve",
  "private": true,
  "engines": {
    "node": ">=20.0.0"
  },
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "translate": "npm run translate:pot && npm run translate:update",
    "translate:pot": "wp i18n make-pot . ./resources/lang/nynaeve.pot --include=\"theme.json,patterns,app,resources\"",
    "translate:update": "for file in ./resources/lang/*.po; do wp i18n update-po ./resources/lang/nynaeve.pot $file; done",
    "translate:compile": "npm run translate:mo && npm run translate:js",
    "translate:js": "wp i18n make-json ./resources/lang --pretty-print",
    "translate:mo": "wp i18n make-mo ./resources/lang ./resources/lang"
  },
  "devDependencies": {
    "@roots/vite-plugin": "^1.0.2",
    "@tailwindcss/vite": "^4.0.9",
    "laravel-vite-plugin": "^1.2.0",
    "tailwindcss": "^4.0.9",
    "vite": "^6.2.0"
  }
}

I only renamed it nynaeve and made the language files nynaeve as well.

Theme Restructuring

The scripts directory becomes js , the styles directory becomes css and fonts.css is moved to root css directory and no longer in css/common . Not sure why this was done, but perhaps it does look clearer this way.

├── css
│   ├── app.css
│   ├── editor.css
│   └── fonts.css
├── fonts
│   ├── menlo-regular-webfont.woff2
│   ├── open-sans-v40-latin-300.woff2
│   ├── open-sans-v40-latin-500.woff2
│   ├── open-sans-v40-latin-600.woff2
│   ├── open-sans-v40-latin-700.woff2
│   ├── open-sans-v40-latin-800.woff2
│   └── open-sans-v40-latin-regular.woff2
├── images
│   ├── icons
│   ├── logo
│   │   └── logo-imagewize-smaller.png
│   └── profiles
│       ├── dall-e-profile image-male.webp
│       ├── dall-e-profile-female.webp
│       ├── dall-e-profile-stylish-male.webp
│       └── dall-e-stylized-illustration-woman-in-a-classic-en-profile-image.webp
├── js
│   ├── app.js
│   ├── editor.js
│   └── filters
│       └── button.filter.js

CSS & JS Updates

We did have to make changes in the main app.css and app.js . In the css we had to add

@import './fonts.css';
@import "tailwindcss" theme(static);
@source "../views/";
@source "../../app/";

theme {
  --font-open-sans: "Open Sans", sans-serif;
  --font-menlo: "Menlo", monospace;
}
...

In app.js we had to remove import domReady from '@roots/sage/client/dom-ready'; and use this at the beginning of the file

import.meta.glob([
  '../images/**',
  '../fonts/**',
]);
...

Acorn Update

We also decided to update Acorn tot he latest for the latest Laravel goodies. Did that with one command

composer require roots/acorn ^5.0 -W

Then reading the migration guide also needed

...
use Roots\Acorn\Application;
...
Application::configure()
    ->withProviders([
        App\Providers\ThemeServiceProvider::class,
    ])
    ->boot();
...

in site/web/app/themes/nynaeve/functions.php to register the bootloader instead of 

if (! function_exists('\Roots\bootloader')) {
    wp_die(
        __('You need to install Acorn to use this theme.', 'sage'),
        '',
        [
            'link_url' => 'https://roots.io/acorn/docs/installation/',
            'link_text' => __('Acorn Docs: Installation', 'sage'),
        ]
    );
}

\Roots\bootloader()->boot();

Installing Dependencies

After updating the theme name and configuration, you’ll need to install the required packages. Although we’re used to running yarn install, the Sage 11 documentation recommends using npm:

  • Run npm install from your theme directory to install all necessary dependencies (e.g., vite, @tailwindcss/vite, etc.).
  • Run npm run build to compile the theme assets.

Important: You must compile the theme assets before accessing your site. If you skip this step, you’ll encounter the following error:

Vite manifest not found at [/path/to/sage/public/build/manifest.json] cannot be found.

NB we removed yarn.lock as we are using npm now.

For all changes including some CSS style changes also see https://github.com/imagewize/imagewize.com/pull/12

Leave a Reply