Sage + Vite Theme

Sage is a WordPress starter theme with a modern development workflow.

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.

Features

• 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
• Modern JavaScript
• Blade as a templating engine
• Controller for passing data to Blade templates
• No IE Support! Don't want it - not adding it.

Requirements

Make sure all dependencies have been installed before moving on:

• WordPress >= 4.7
• PHP >= 7.1.3 (with php-mbstring enabled)
• Composer
• Node.js >= 8.0.0
• Yarn

Theme installation

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

Theme structure

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)

Theme setup

Edit app/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.

Rename .env.example to .env and choose one of the preset values for APP_ENV.

NOTE: THIS VALUE WILL CHANGE AUTOMATICALLY WHEN YOU RUN THE YARN SCRIPTS BELOW.

Theme Development

• Run yarn from the theme directory to install dependencies
• By default all top-level files in the scripts directory 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 __before method, write

Vite::register('scriptName.ts');

This line is what enables HMR to work during development and the production scripts to be registered directly in production.

Build commands

• yarn dev — Compile assets when file changes are made with HMR.
• yarn build — Compile and optimize the files in your assets directory

Documentation

• Sage documentation
• Controller documentation
• Vite Documentation