Squarespace Toolbelt
Utilities for building and maintaining Squarespace templates
Installation
npm install --save-dev @squarespace/toolbelt
Usage
In your package.json you can use Squarespace Toolbelt to automatically run build tasks on Squarespace templates. Example:
{
"name": "your-squarespace-template",
"version": "0.0.1",
"devDependencies": {
"@squarespace/toolbelt": "^0.1.0",
"webpack": "^1.12.9"
},
"scripts": {
"build": "squarespace assemble && webpack",
"watch": "squarespace assemble -wT & webpack --watch",
"server": "squarespace runserver -T",
"start": "squarespace setup && (npm run watch & npm run server)",
"deploy": "squarespace setup && squarespace deploy"
}
...
}
Above we include @squarespace/toolbelt
in the devDependencies, and then use squarespace assemble
in the project's build and watch scripts.
Automatic Reloading
The assemble
command is designed to work with Squarespace Development Server's --trigger-reload
option to automatically refresh the browser each time a change is detected. To take advantage of this, run assemble
with the -T
or --trigger-reload
and -w
or --watch
flags like so:
squarespace assemble -wT
This will watch your build folder, automatically assembling each time a file changes, and triggering the dev server to reload.
You must also run the dev server with -T
or --trigger-reload
to listen for the triggers:
squarespace runserver -T
For more info see the reference below.
Reference
Squarespace Toolbelt exposes several scripts you can use in your template's package.json:
squarespace [options] [command]
Commands:
clean cleans the build directory
assemble assembles Squarepace template files into the build directory
deploy [repository] deploys a Squarepace template
runserver runs the Squarespace Development Server. (Must be installed separately. See http://developers.squarespace.com/local-development.)
setup configures a Squarepace template for local development
help [cmd] display help for [cmd]
Options:
-h, --help output usage information
-V, --version output the version number
squarespace setup [options]
Options:
-h, --help output usage information
-d, --directory <directory> Directory to setup. Default is the current one.
squarespace assemble [options]
Options:
-h, --help output usage information
-n, --noclean Assemble without first cleaning the output directory.
-w, --watch Watch for changes and assemble incrementally.
-d, --directory <directory> Source directory. Default is '.'
-o, --output <output> Output directory for assembled files. Default is 'build'
-T, --trigger-reload [host:port] Trigger Local Development Server to reload on each assemble.
-l, --legacy Copies scripts directory for older templates with squarespace:script tags.
-a, --after <command> Run a command after the build has completed.
--trigger-reload
:
Using Trigger reload takes an optional [host:post] that defaults to "localhost:9000". You can also provide a full domain with protocol, such as "https://192.168.10.10:3000". Typically all that's needed to watch your template files and trigger the Local Development Server is:
squarespace assemble -wT
squarespace clean [options]
Options:
-h, --help output usage information
-d, --directory <directory> Directory to clean. Default is 'build'
squarespace deploy [options] [repository]
Options:
-h, --help output usage information
-d, --directory <directory> Deploy from this directory. Default is 'build'
-m, --message <message> Deployment message. Default is 'sqs-deploy <date time>'
-w, --watch Watch the build directory for changes and deploy automatically.
-f, --force Force deployment of build. This will overwrite any git history in your site's /template.git repository.
-a, --after <command> Run a command after the build has completed.
Troubleshooting
If you are attempting to deploy a template other than the one cloned from your site's /template.git
repository, you will encounter the following error:
fatal: refusing to merge unrelated histories
To solve this, you can use squarespace deploy --force
. Beware that this will overwrite any git history in your site's /template.git
repository.
squarepace runserver URL [options]
Runs Squarespace Local Development Server.
Requires @squarespace/server to be installed globally.
Options:
-h --help output usage information
-d --directory=PATH Path to cloned template repository [default ./build].
-p --port=PORT Port that server listens on [default 9000].
-T --trigger-reload Listen for reload trigger and refresh page.
--host=HOST Host that server listens on [default localhost].
--auth Log in to work on trial or password protected sites.
For full squarespace server options, see squarespace runserver --help
.
Contributing
We are currently not accepting contributions to Squarespace Toolbelt.
Copyright and License
Copyright 2016 Squarespace, INC.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.