Getting Started

Responsive Framework introduces a new development workflow to support sharing and optimizing front-end assets across child themes. This workflow adds Sass for a better CSS authoring experience, Grunt to orchestrate Sass compilation and asset optimization and Bower to manage front-end dependencies.

Front-end assets shared across themes live in the Responsive Foundation repository and are pulled down locally for development using Bower.

Quick Start

1. Install xCode and Homebrew Package Manger (macOS only)
2. Install Node and Node Package Manager
3. Install Grunt
4. Clone the theme repository you need to work on
5. Install theme development dependencies
6. Start Grunt to initiate the build process

The first three steps need only happen once; the last three need to be repeated for each theme you want to work on.

Install xCode and Homebrew Package Manger (macOS only)

Install xCode from the App store. Make sure to open it and accept the license conditions. If you don't accept the license the Homebrew installation will fail. It's also needed to install Sass, and provides you with Simulator, which you can use to quickly debug iPhone and iPad issues straight from your Mac.

When installing the packages listed below sometimes you will get permission errors on Mac. Installing Homebrew before the packages listed below should change permissions properly so you will not get errors while installing. To install Homebrew visit https://brew.sh/ and follow the instructions.

Optionally, there are instructions below for changing permissions for each package below if an error occurs.

Install Node and Node Package Manager

The build process introduced for Responsi uses several Node.js packages including Grunt, Bower and several Grunt plugins. Node packages are installed using the Node Package Manager.

You can download the latest version of both Node and Node Package Manager from http://nodejs.org/.

Install Grunt

We recommend installing Grunt CLI globally so that you don't have to re-install it for every project. This can be accomplished by running the following command in your Terminal:

npm install -g grunt-cli

ProTip: Stop npm Permissions Errors

Seeing permissions errors when attempting to run npm install?

npm install -g bower
npm ERR! Error: EACCES, mkdir '/usr/local/lib/node_modules/bower'
npm ERR!  { [Error: EACCES, mkdir '/usr/local/lib/node_modules/bower']
npm ERR!   errno: 3,
npm ERR!   code: 'EACCES',
npm ERR!   path: '/usr/local/lib/node_modules/bower',
npm ERR!   fstream_type: 'Directory',
npm ERR!   fstream_path: '/usr/local/lib/node_modules/bower',
npm ERR!   fstream_class: 'DirWriter',
npm ERR!   fstream_stack:
npm ERR!    [ '/usr/local/lib/node_modules/npm/node_modules/fstream/lib/dir-writer.js:36:23',
npm ERR!      '/usr/local/lib/node_modules/npm/node_modules/mkdirp/index.js:46:53',
npm ERR!      'Object.oncomplete (fs.js:107:15)' ] }
npm ERR!
npm ERR! Please try running this command again as root/Administrator.

Some OS X installs don't always have the correct owner for the global node_modules / package cache directories.

Run the following command to fix:

sudo chown -R `whoami` /usr/local/lib/node_modules ~/.npm

Install theme development dependencies

The Grunt build process depends on several Node packages which must be installed for every theme. These dependencies are captured in the top-level package.json file, and installed to a node_modules directory for each theme which is ignored by Git when committing changes.

To install these dependencies, run the following in your theme directory:

npm install

These dependencies include Responsive Foundation files. The specific location and version of the Foundation framework is captured in the top-level package.json file within your theme.

Note: if you are receiving errors like: ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`

Then you can run the command xcode-select --install to download and install the Xcode command line developer tools. After they are done installing, bower install should run flawlessly.

If at any point during development your Grunt or npm requirements change (e.g. the package.json file is updated) these commands need to be re-run.

Start Grunt to initiate the build process

The Grunt build process requires a command to be run after any source files (Sass and Javascript files) are modified.

You can run this manually:

grunt build

Or you can tell Grunt to "watch" your theme directory as you work, triggering build steps automatically:

grunt

Be sure to commit the generated output files (style.css, js/script.js) along side source file changes!

If you're getting a SASS error: sudo gem install -n /usr/local/bin sass -v 3.4.13

Development Considerations

• Remember that with Git commits are local; no one can see your commits until you have published them to the remote repository (Github) using git push.
• Always run git pull when you resume work on a theme to ensure your working copy is up-to-date with the remote.

Optional: Run CodeClimate and PHP Unit Testing locally

If you like, you can run tests on your code before you push it to Github. This is totally optional, since you'll see errors on your pull request in Github if you have them. But it's a lot faster to do it locally if you're up for a little setup. Follow the instructions for the CodeClimate CLI for Sass testing, and at VVV to set up PHP unit testing.