Using Grunt on the Squarespace Developer Platform

Update: This newer post is a better representation of my views on this topic.

Over the past two years I’ve watched Squarespace turn into a bonafide platform for developers. One of the more interesting features of the platform is the automatic CSS preprocessing using Less. It makes managing your CSS super easy, and preprocessing becomes an afterthought.

There are some gaps, though.

  • Squarespace has a custom Less compiler written in Java that’s, apparently, much faster than the JavaScript version. But it’s on version 1.3, so you’ll miss out on some of the newest, coolest features of Less.
  • I prefer using autoprefixer to mixin libraries for managing vendor prefixes. And there’s no way to do that in Squarespace by default

In this post I’ll outline how I overcame those two minor gaps in functionality using Grunt.

Before we get started I should give the full disclaimer: I am a Squarespace employee. Any opinions in this post are my own. These techniques are not best practices endorsed by Squarespace, they’re just cool things that I felt like sharing.

Now let’s get started with the tutorial.

Setting up a Dev Environment

I’m going to be outlining a fairly opinionated workflow in this post. There are lots of different workflows that work well for other people, but this one works for me.

Here’s a list of the tools we’re going to use:

The first thing you’ll need to do is start your Squarespace Developer site. These are free to use as long as they’re in development, you only have to pay once you want to take a site live. To get started, follow the instructions on the get started page, that will take you through starting a site, enabling developer mode, and downloading your template code.

Once you’ve downloaded your template code, open up the folder in Sublime Text 2. You should have a file structure like this:

/assets
/blocks
/collections
/pages
/scripts
/styles
site.region
template.conf

If you don’t already have the Sublime SFTP Plugin installed, do that now. Once it’s installed, right click on the root folder name in the left hand sidebar. Select SFTP/FTP > Map to Remote. This will add an sftp-config.json file, which you can configure to automatically upload your files when you save them.

{
“type”: “sftp”,
  “save_before_upload”: true,
“upload_on_save”: true,
“sync_down_on_open”: false,
“sync_skip_deletes”: false,
“sync_same_age”: true,
“confirm_downloads”: false,
“confirm_sync”: true,
“confirm_overwrite_newer”: false,

“host”: “dev.squarespace.com”,
“user”: “youremail@gmail.com”,
“password”: “**********",
“port”: “2030",
  “remote_path”: “/example-site/”, // fill in your site name here.
  “ignore_regexes”: [
“\\.sublime-(project|workspace)”, “sftp-config(-alt\\d?)?\\.json”,
“sftp-settings\\.json”, “/venv/”, “\\.svn/”, “\\.hg/”, “\\.git/”,
“\\.bzr”, “_darcs”, “CVS”, “\\.DS_Store”, “Thumbs\\.db”, “desktop\\.ini”
],
  “connect_timeout”: 7
}

Now we need to add a package.json file to the root directory so Grunt knows what dependencies we need for this project. Here’s my package.json file.

{
"name" : "Example Site",
"version" : "0.0.1",
"description" : "Using Grunt with Squarespace.",
"repository" : {
"type" : "git",
"url" : "https://example-site.squarespace.com/template.git",
},
"author" : "Kevin Foley",
"homepage" : https://example-site.squarespace.com",
"dependencies" : {
"grunt" : "^0.4.5",
"grunt-auto-prefixer" : "*",
"grunt-contrib-less" : "~0.10.0",
"grunt-contrib-watch" : "~0.6.1"
}
}

Once you’ve got your package.json file installed, open up your terminal application, cd into your site directory, and type the following command.

npm install

This will install all of the dependencies you need to run your Grunt task. Now we need to add a gruntfile.js to the directory, again on the root level. My grunt file looks like this.

module.exports = function( grunt ) { 
‘use strict’;
  grunt.initConfig( {
less: {
dev: {
files: [
{
expand: false,
flatten: false,
src: [
‘styles/reset.css’,
‘styles/dense-regular.css’,
‘styles/*.less’
],
dest: ‘styles/_main.css’
}
],
cleancss: false
}
},
    autoprefixer: {
multiple_files: {
expand: true,
flatten: true,
src: ‘styles/_main.css’,
dest: ‘styles’
}
},
    watch: {
files: [
‘styles/*.less’,
‘styles/reset.css’
],
tasks: [ ‘css’ ]
}
} );
  // Load required modules
grunt.loadNpmTasks( ‘grunt-contrib-less’ );
grunt.loadNpmTasks( ‘grunt-autoprefixer’ );
grunt.loadNpmTasks( ‘grunt-contrib-watch’ );
  // Task definitions
grunt.registerTask( ‘css’, [
‘less’,
‘autoprefixer’
] );
};

The Grunt task is searches through the /styles/ folder for any .less files and compiles them into a single _main.css file. The autoprefixer then parses through the _main.css file and adds the appropriate vendor prefixes.

Now open your template.conf file. There is a section inside the template.conf file called “stylesheets.” This is how Squarespace knows which CSS and Less files to compile into the final site.css file that is loaded on your site. Remove all the files from the stylesheets array and add in _main.css.

“stylesheets” : [ “_main.css” ]

Now Squarespace will load just your compiled CSS.

Developing Your Site

Now that we’ve got a dev environment set up, it’s time to get started writing some code. There are two steps you have to take to fire up your dev environment and get started.

First, start the grunt watch task, which listens for changes to all of your .less and .css files. They will automatically compile into _main.css. You can start the task by going into your terminal and typing “grunt watch.”

grunt watch

Now, set up your _main.css file to automatically upload whenever it changes. The Sublime SFTP plugin handles this easily. Just right click on the file in Sublime Text and select SFTP/FTP > Monitor File (Upload on External Save).

Conclusion

That’s it, you’re now running a completely custom build script for your CSS on Squarespace. This was a fairly simple example, but I hope you see how this technique can be applied to almost any task. This type of technique could easily be used to write Sass instead of Less, or lint your JavaScript, for example.

If you’re looking for more on this topic, my buddy Brandon Kitajchuk from Instrument created grunt-init-squarespace. He also wrote a blog post about it.

Hope you enjoy building your Squarespace site.