Dependencies

Before getting started with Granola, please have the following dependencies setup

For a streamlined development environment, we recommend the following

Getting started

First thing to do is setup a WordPress install that you would like to develop a theme for. After that, its time to install Granola.

You can create a new theme based on Granola by downloading a copy of the git repository or by running the following in the themes directory of your WordPress installation:

# @ wp-content/themes
$ composer create-project wholegrain/granola your-theme-name

Once the theme files have downloaded, we need to install the dependencies to compile the source files for a production build

# @ wp-content/themes/your-theme-name
$ npm run setup

If you open WordPress now and head to the themes page, the Granola theme will be available for activation.

To have the build tools watch the files for changes and live reload the browser, type gulp watch from the root of the theme.

Note: you should probably check out the “Browsersync configuration” section below.

Configuring project details

style.css

WordPress depends on style.css for various aspects of the WordPress admin interface. Due to template caching based on the version specified in the style.css file, this file is dynamically generated.

You can modify the specifics of the style.css file in _development/config/wordpress.js. The version number for the stylesheet will be generated from as a timestamp of the current time.

Browsersync configuration

Copy the .env.js.sample file to .env.js and replace the BROWSERSYNC_PROXY url to match your WordPress url.

.mjs mimetypes

Once the build tools have run, granola will output two javascript files for every input file, a .js file and a .mjs file. The purpose of the two files is two produce a smaller file for modern browsers, and a polyfilled file for older browsers.

Not all development environments natively support the .mjs extension as a javascript mimetype, and browsers will throw a warning in the console. To address the issue, the .mjs must be added to the valid javascript mimetypes.

Laravel Valet

# @ /usr/local/etc/nginx/mime.types

Find
application/javascript js;

Replace
application/javascript mjs js;

Then
valet restart

Apache .htaccess

<IfModule mod_mime.c>
  AddType text/javascript js mjs
</IfModule>

Service Worker

Granola comes with an integrated service worker so the website can be considered a progressive web app (PWA). The service worker file is copied to the WordPress root directory when a user logs into WordPress. To successfully register a service worker, a page with a slug of offline needs to be created.

The relevant service worker code can be found in the following files

  • _development/general/serviceworker.js
  • granola/wordpress/serviceworker.php