If you’ve ever tried setting up Sage 10 with Acorn and Vite and felt like you were losing your mind, you’re not alone.
I recently went through the whole mess too — broken themes, missing PHP extensions, Vite build errors, and Acorn refusing to behave. So here’s the real-world setup guide I wish someone handed me at the start.
This article is based on real-world debugging, not just the happy-path setup instructions. Here’s what worked for me — and what I wish I knew at the start.
Step 1: Fix your PHP setup first
The #1 issue that’ll break your install is a missing PHP extension. You’ll usually get errors like: league/flysystem-local requires ext-fileinfo
That’s because your php.ini doesn’t have fileinfo enabled — and yes, it needs to be the actual php.ini file, not php.ini-development or php.ini-production.
Configurate the .php.ini
Run php –ini in your terminal or you can usually find this on C:\Program Files\PHP\php.ini . Please make sure that you are updating the right .php.ini because they have both production and development. Then open that file and make sure this line is uncommented then restart your terminal or web server
extension=php_fileinfo.dll
Step 2. Install Acorn 5.0.3 before Sage (Recommend if you run other than Sage)
Do this before installing Sage, or things will break later. Acorn is the engine behind Sage’s Laravel-style functionality (like Blade and the container).
composer require roots/acorn:^5.0.3 –with-all-dependencies
This can be run in your main Bedrock app, or even just to verify your system dependencies and PHP are ready. It’s useful for:
- Checking for any global conflicts (like fileinfo, illuminate/*, etc.)
- Testing if your PHP setup supports Acorn
- Think of this like testing your car engine before going on a road trip.
Step 3: Create a new Sage theme (and install Acorn inside it too)
composer create-project roots/sage your-theme-name
cd your-theme-name
composer require roots/acorn:^5.0.3 –with-all-dependencies
Step 4: Run Vite build (this will save you from 500 errors)
Now your theme’s code is set up, but the browser doesn’t know what to do with the JS and CSS until you compile it.
Run the following command inside the Sage theme
npm install
npm run build
This will generate your assets in:
/public/build/manifest.json