I started to work in Sage 11 and the documentation isn’t clear.
I am having trouble setting up the templates.
I follow these steps as outlined, Installing Sage | Sage Docs | Roots
But I only get a Laravel Holding page that I can’t locate in the template files.
Any help would be appreciated.
Do you have a local PHP environment? You’d visit the hostname like example.test as you would with other projects– not the Vite dev server.
hot reload with Vite automatically works when visiting the normal host name. are you seeing the stylesheet load in the network tab?
Update on this, I had to change the base path to my theme.
base: '/wp-content/themes/{my_theme}/public/build'
does this work when you do npm run build? I get this error when activating the theme/accessing the site and for the life of me, i cant figure out why.
// the boilerplate that composer create-project roots/sage provides
export default defineConfig({
base: ‘/wp-content/themes/[theme_name]/public/build/’,//‘/app/themes/sage/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: {
// contains at symbol
‘scripts’: ‘/resources/js’,
‘styles’: ‘/resources/css’,
‘fonts’: ‘/resources/fonts’,
‘images’: ‘/resources/images’,
},
},
})
When I do npm run dev, the homepage loads and i can do development just fine but my concern is that when i need to deploy it on a wordpress hosted site, it will give this same error.
I do see that it is trying to look for a manifest.json file under public when the manifest.json is under build. I had already tried updating the base to …/public/ and rebuild but it still generates the same file structure in build and the exact same content in manifest.json and all the other files in assets. The docs doesnt provide much information and most examples i see uses v10 with bud.config.js. Any ideas?
Thank you so much! I totally missed this part. It resolved net::ERR_CONNECTION_REFUSED in my staging site.
Hello, dear @Log1x !
I can’t find any guide about linting in Sage 11. Previous article about linting on roots.io was removed.
So tell me please what steps we have to do for linting? Do we need to install ESLint, StyleLint and Prettier via “npm install” in Sage’s directory and that’s it? Or do we need something more?
What linting do you want to add?
If you want to use em, yeah, you gotta install em. Give it a shot 
I want to add linting by ESlint, Stylelint, HTMLHint and code formatting by Prettier.
Now I’m trying to make my own detailed guide to describe step-by-step process to configure linting for a Sage 11 theme. Let me show what I have done.
First, navigate to your Sage 11 theme directory in the terminal and install the required packages using npm.
#Install Prettier and its plugins
npm install -D prettier prettier-plugin-tailwindcss
#Install ESLint and its plugins
npm install -D eslint eslint-plugin-import eslint-config-prettier
#Install Stylelint and its plugins
npm install -D stylelint stylelint-config-standard stylelint-prettier
#Install HTMLHint
npm install -D htmlhint
prettier-plugin-tailwindcss: This is a crucial plugin that automatically sorts your Tailwind CSS classes in a consistent, readable order.eslint-config-prettier: This package ensures that ESLint rules don’t conflict with Prettier’s formatting, preventing a mess of errors.stylelint-prettier: The equivalent plugin for Stylelint, disabling any conflicting rules with Prettier.Prettier is an opinionated code formatter that ensures a consistent style across all your files.
Create a .prettierrc.json file in your theme’s root directory with the following configuration.
{
"singleQuote": true,
"trailingComma": "es5",
"tabWidth": 2,
"semi": true,
"plugins": ["prettier-plugin-tailwindcss"],
"tailwindFunctions": ["tw"]
}
"singleQuote" and "semi" are common formatting preferences. You can adjust these to your team’s style.
"plugins": ["prettier-plugin-tailwindcss"]: This loads the Tailwind plugin, which is essential for sorting classes correctly.
"tailwindFunctions": ["tw"]: For Tailwind 4.0’s new tw() function, this setting ensures Prettier recognizes and formats its contents.
Next, create a .prettierignore file to specify files and directories that Prettier should not format.
build
dist
vendor
node_modules
ESLint is a powerful linter for JavaScript that helps catch syntax errors and enforces best practices.
Create an .eslintrc.cjs file in your theme’s root. This uses the CommonJS format, which is standard for most Node.js build tools.
JavaScript
module.exports = {
root: true,
env: {
browser: true,
node: true,
es2021: true
},
extends: [
'eslint:recommended',
'eslint-config-prettier' // This must be the last extension to disable conflicting rules
],
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module'
},
rules: {
// You can add custom ESLint rules here
'prettier/prettier': 'error'
}
};
extends: This pulls in the standard ESLint recommended rules and the eslint-config-prettier to prevent formatting conflicts.
parserOptions: These options are configured for modern JavaScript, which is what Vite.js uses.
'prettier/prettier': 'error': This rule ensures that any code that doesn’t conform to your Prettier configuration will be flagged as an ESLint error.
Now, create an .eslintignore file.
build
dist
vendor
node_modules
Stylelint is a linter for CSS, ensuring your stylesheets are consistent and error-free.
Create a .stylelintrc.json file. Since you are primarily using Tailwind utility classes, Stylelint will focus on any custom CSS you write.
JSON
{
"extends": [
"stylelint-config-standard",
"stylelint-prettier/recommended"
],
"rules": {
"prettier/prettier": true
}
}
"stylelint-config-standard": This provides a solid set of standard CSS linting rules.
"stylelint-prettier/recommended": This ensures Stylelint doesn’t conflict with Prettier’s formatting.
Create a .stylelintignore file.
build
dist
vendor
node_modules
HTMLHint is a static analysis tool that checks your HTML for syntax errors, accessibility issues, and best practices. It’s perfect for linting your Blade files.
Create an .htmlhintrc file in your theme’s root.
JSON
{
"tag-pair": true,
"tagname-lowercase": true,
"attr-lowercase": true,
"attr-sorted": true,
"doctype-first": true,
"id-unique": true,
"spec-char-escape": true,
"img-alt-require": true,
"inline-style-disabled": true
}
This configuration is a good starting point for a Blade-based project. It ensures proper tag structure, attributes, and basic accessibility checks.
package.jsonAdd a few scripts to your package.json file to make running these tools easy. This will allow you to format and lint your entire project with simple commands.
Open package.json and add the following to the "scripts" section:
"scripts": {
"dev": "vite",
"build": "vite build",
"lint:js": "eslint 'resources/scripts/**/*.js'",
"lint:css": "stylelint 'resources/styles/**/*.css'",
"lint:html": "htmlhint 'resources/views/**/*.blade.php'",
"format": "prettier --write 'resources/**/*.{js,css,json,blade.php}'",
"lint": "npm run lint:js && npm run lint:css && npm run lint:html"
}
format: Runs Prettier to automatically format all your supported files.
lint: A composite command that runs all the linters.
VS Code, with the right extensions, is an excellent environment for a seamless linting and formatting workflow. Instead of relying on Vite plugins for real-time feedback, your IDE will provide it directly in the editor as you type.
Here are the essential VS Code extensions you need to install and configure for your Sage 11 setup:
This is the most critical extension. It integrates Prettier directly into your editor, allowing you to format your code on save or on command.
Extension Name: Prettier - Code formatter
Publisher: esbenp
ID: esbenp.prettier-vscode
Why you need it: This extension reads your .prettierrc.json file and automatically applies the defined formatting rules to your code. It’s the engine that makes all the formatting happen.
Recommended VS Code Settings: To make Prettier work automatically when you save a file, you need to configure a few settings in VS Code.
Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
Search for and select Preferences: Open User Settings (JSON).
Add the following lines:
JSON
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true
}
"editor.defaultFormatter": This tells VS Code to use the Prettier extension as the default formatter for all supported file types.
"editor.formatOnSave": This is a powerful setting that automatically formats the file every time you save it, making code formatting effortless.
This extension provides real-time linting for your JavaScript files. It highlights issues directly in the editor and can even offer auto-fixes.
Extension Name: ESLint
Publisher: dbaeumer
ID: dbaeumer.vscode-eslint
Why you need it: This extension reads your .eslintrc.cjs file and displays any JavaScript errors or warnings as squiggly underlines in your code. It works in conjunction with the Prettier extension to ensure that formatting issues are also flagged as ESLint errors, as per the eslint-plugin-prettier setup.
Key features:
Shows linting errors and warnings.
Provides code actions to fix problems (source.fixAll.eslint).
Integrates with the Problems panel in VS Code.
For your CSS files, this extension is a must-have. It highlights Stylelint errors and warnings.
Extension Name: Stylelint
Publisher: Stylelint
ID: stylelint.vscode-stylelint
Why you need it: Just like the ESLint extension, this one reads your .stylelintrc.json file and provides live feedback on your CSS code. This is particularly useful for any custom CSS you write outside of Tailwind’s utility classes.
Recommended VS Code Settings: To ensure the Stylelint extension works on all your CSS-like files, you might need to add a small configuration, especially if you’re using CSS-in-JS or other specific file types. For a standard Sage 11 setup, the default configuration should be sufficient.
While this one is a bit more niche, it’s the perfect extension for linting your Laravel Blade templates.
Extension Name: HTMLHint
Publisher: ctf0
ID: ctf0.htmlhint
Why you need it: It reads your .htmlhintrc file and checks your Blade files for HTML syntax errors and best practices. While Blade itself is a PHP templating engine, the output is pure HTML, and this extension helps you keep that HTML clean and valid.
esbenp.prettier-vscode
dbaeumer.vscode-eslint
stylelint.vscode-stylelint
ctf0.htmlhint
By installing these four extensions and configuring editor.formatOnSave for Prettier, you will have a comprehensive and powerful linting setup that provides instant feedback right within your editor, making for a smooth and efficient development experience.