Sage + Vite Theme
Motivations for WordPress + Vite
This is a modified version of Sage combined with github user andrefilipe’s vite configuration that allows developers to use Vite in a WordPress site. It works by serving assets from localhost:3000 during development for HMR, and from the dist folder when compiled for production. It uses a simple abstraction around wp_enqueue_script to make registering and loading assets as easy as possible.
Because Vite is incredibly fast and supports HMR, you no longer need to reload the entire page to see your js, css changes. Additionally any changes to php files or blade templates will automatically trigger the browser to refresh the page for you. I believe that this is a much better developer experience than using the built-in sage tools, or even laravel-mix. Additionally, all top-level files are automatically added as entry points, so there is less to manage during development, and you can get right to coding. WordPress has enough going on without needing to worry about your front-end as well.
- Vite tooling with support for TypeScript, React, and Vue, and Hot Module Replacement (HMR) out-of-the-box.
- Scss for stylesheets
- Image lazy loading.
- Basic styles
- Blade as a templating engine
- Controller for passing data to Blade templates
- No IE Support! Don’t want it – not adding it.
Make sure all dependencies have been installed before moving on:
Install Sage using Composer from your WordPress themes directory (replace
your-theme-name below with the name of your theme):
# @ app/themes/ or wp-content/themes/ $ composer create-project 8bit-echo/sage your-theme-name
To install the latest development version of Sage, add
dev-master to the end of the command:
$ composer create-project 8bit-echo/sage your-theme-name dev-master
themes/your-theme-name/ # → Root of your Sage based theme ├── app/ # → Theme PHP │ ├── Controllers/ # → Controller files │ ├── Classes/ # → Other PHP files │ ├── admin.php # → Theme customizer setup │ ├── filters.php # → Theme filters │ ├── helpers.php # → Helper functions │ └── setup.php # → Theme setup ├── composer.json # → Autoloading for `app/` files ├── composer.lock # → Composer lock file (never edit) ├── dist/ # → Built theme assets (never edit) ├── node_modules/ # → Node.js packages (never edit) ├── package.json # → Node.js dependencies and scripts ├── resources/ # → Theme assets and templates │ ├── assets/ # → Front-end assets │ │ ├── fonts/ # → Theme fonts │ │ ├── images/ # → Theme images │ │ ├── scripts/ # → Theme JS │ │ └── styles/ # → Theme stylesheets │ ├── functions.php # → Composer autoloader, theme includes │ ├── functions-default.php # → Opinionated default functions. │ ├── functions-app.php # → Write all your custom functionality here. │ ├── index.php # → Never manually edit │ ├── screenshot.png # → Theme screenshot for WP admin │ ├── style.css # → Theme meta information │ └── views/ # → Theme templates │ ├── layouts/ # → Base templates │ └── partials/ # → Partial templates └── vendor/ # → Composer packages (never edit)
app/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.
.env and choose one of the preset values for
NOTE: THIS VALUE WILL CHANGE AUTOMATICALLY WHEN YOU RUN THE YARN SCRIPTS BELOW.
yarnfrom the theme directory to install dependencies
By default all top-level files in the
scriptsdirectory will be used as entry points for the build process.
to register a script on a page, go to the Page’s Controller and in the
This line is what enables HMR to work during development and the production scripts to be registered directly in production.
yarn dev— Compile assets when file changes are made with HMR.
yarn build— Compile and optimize the files in your assets directory