npm package: @squarespace/toolbelt
Description: Utilities for building and maintaining Squarespace templates
Author: Squarespace, Inc.
Latest version: 0.12.5

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.

#### Using `--trigger-reload`:

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.