Sage 10

This page is a place for me to collect various knowledge about Sage 10, as of yet not out of development.

Table of Contents

Installing Sage 10

To install Sage 10 instead of Sage 9, add dev-master:

composer create-project roots/sage your-theme-name dev-master
cd your-theme-name
composer update
yarn
wp theme activate your-theme-name

In webpack.mix.js, change the browserSync URL to reflect your project:

mix
  .setPublicPath('./public')
  .browserSync('https://theproject.test');

Upgrade Tailwind

At the time of writing this, Sage 10 ships with Tailwind 2.0.3 already set up. However, the latest version is 2.1.0, which includes the new JIT engine, which we definitely want to use.

cd to theme directory. Then:

yarn add tailwindcss@latest --dev

Turn on JIT mode in tailwind.config.js:

module.exports = {
  mode: 'jit',
  purge: {
    content: [
    [...]

Start watching files:

yarn start

FontAwesome Pro

If you have a FontAwesome Pro license, here’s how you enable it in Sage 10:

Go to the FontAwesome account page and fetch the Pro Package Token.

In the Sage theme folder, add a .npmrc file with the token environment variable:

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Also remember to add .npmrc to .gitignore.

Then add to package.json:

yarn add @fortawesome/fontawesome-pro @fortawesome/fontawesome-svg-core @fortawesome/pro-regular-svg-icons @fortawesome/free-brands-svg-icons

In resources/assets/scripts/app.js, add:

// Font Awesome
// Import the needed Font Awesome functionality
import { library, dom } from '@fortawesome/fontawesome-svg-core';
// import Font Awesome icons
import {
    faUser, // Example
} from '@fortawesome/pro-regular-svg-icons';
import {
    faFacebook,
    faInstagram,
} from '@fortawesome/free-brands-svg-icons';

// add the imported icons to the library
library.add(
    faUser,
    faFacebook,
    faInstagram
);

// tell FontAwesome to watch the DOM and add the SVGs when it detects icon markup
dom.watch();

Enable global helper functions

The global helper functions, like app(), resolve(), logger() are disabled by default. To enable them, set ‘globals’ to true in config/app.php.

WooCommerce

Use smarteist / sage-woocommerce to add support for overriding WooCommerce templates/partials with Blade templates.

wp-cli

Acorn has a wp-cli command:

wp acorn <command>

Some useful commands:

  • wp acorn make:command
    Create a new console command
  • wp acorn make:component
    Create a new view component class
  • wp acorn make:composer
    Create a new view composer class