Wordpress Starter Theme with Sage and Vite

Overview

WordPress starter theme with block editor support and Vite builder.

Requirements

• Acorn v3
• PHP >= 8.0 (with php-mbstring enabled)
• Composer
• Vite >= 3.1.0
• Node.js >= 18.0.0
• Yarn

Theme installation

Install Sage using Composer from your WordPress themes directory (replace theme-name below with the name of your theme):

# /wp-content/themes/
$ composer create-project onepixnet/sage-vite theme-name

To install the latest development version of Sage, add dev-main to the end of the command:

# /wp-content/themes/
$ composer create-project onepixnet/sage-vite theme-name dev-main

Then jump to your theme-name and install Acorn

# /wp-content/themes/theme-name
$ composer require roots/acorn

Then install dependencies and compile assets

$ yarn
$ yarn build

You're ready to go!

To start dev server and HMR just run

$ yarn dev

Full list of commands

# /wp-content/themes/
$ composer create-project onepixnet/sage-vite theme-name dev-main

# /wp-content/themes/theme-name
$ composer require roots/acorn
$ yarn
$ yarn build
$ yarn dev

Theme structure

themes/your-theme-name/   # → Root of your Sage based theme
├── app/                  # → Theme PHP
│   ├── Providers/        # → Service providers
│   ├── View/             # → View models
│   ├── filters.php       # → Theme filters
│   ├── helpers.php       # → Global helpers
│   ├── medias.php        # → Medias helper
│   └── setup.php         # → Theme setup
├── composer.json         # → Autoloading for `app/` files
├── public/               # → Built theme assets (never edit)
├── functions.php         # → Theme bootloader
├── index.php             # → Theme template wrapper
├── node_modules/         # → Node.js packages (never edit)
├── package.json          # → Node.js dependencies and scripts
├── resources/            # → Theme assets and templates
│   ├── fonts/            # → Theme fonts
│   ├── images/           # → Theme images
│       ├── icons/        # → Theme icons
│   ├── scripts/          # → Theme scripts
│   ├── styles/           # → Theme styles
│   └── views/            # → Theme templates
│       ├── components/   # → Component templates
│       ├── forms/        # → Form templates
│       ├── layouts/      # → Base templates
│       ├── partials/     # → Partial templates
        └── sections/     # → Section templates
├── screenshot.png        # → Theme screenshot for WP admin
├── style.css             # → Theme meta information
├── vendor/               # → Composer packages (never edit)
└── vite.config.ts        # → Vite configuration

Theme development

• Run yarn from the theme directory to install dependencies
• Update vite.config.ts for bundler fine tuning

Build commands

• yarn dev — Start dev server and hot module replacement
• yarn build — Compile assets
• yarn lint — Lint stylesheets & javascripts
• yarn lint:css — Lint stylesheets
• yarn lint:js — Lint javascripts

Hot Module Replacement

Project Side

Add the following variables in your project .env

# Endpoint where the bundler serve your assets
HMR_ENTRYPOINT=http://localhost:3000

Theme side

For advanced dev server configuration, copy .env.example according to Vite naming convention and loading order and update variables

FYI

Running HMR Mode remove the public/manifest.json file, so do not forget to re-run the assets compilation with yarn build if needed.

Documentation

• Sage documentation
• Controller documentation
• Vite