Local Development

Notice: Use of the Local Development Server is now subject to our Developer Terms, rather than the Squarespace Local Development Server EULA (which we've sunsetted). The Oracle Binary Code License Agreement continues to cover the Java SE Runtime Environment Software that comes bundled with the Dev Server software.

Now you can work on template code locally using the Squarespace Local Development Server. The local development server is a command line tool that sets up a test server on your computer, allowing you to see changes to your template before making them "live."

NOTE: Prior to developing locally, you'll need a website set up with developer mode enabled. (See Getting Started)

Installing the Dev Server

To begin working locally, you first must download and install the Squarespace Local Development Server. This tool is available via Node Package Manager (NPM). Here are the steps required:

1. Install NPM: If you don't have NPM installed you'll need to set that up first, by following the NPM installation guide. You'll also need to ensure you have the appropriate permissions configured for NPM.

2. Install squarespace-server: You can do this with the following NPM command:

npm install -g @squarespace/server

Using the Dev Server

First you need to have your template in Developer Mode, and have cloned your site into a folder using Git. (See Quick Start):

git clone https://github.com/{{ your_org }}/{{ your_repo }}.git
cd {{ your_repo }}

Then, to start Dev Server, run the following command:

squarespace-server https://site-name.squarespace.com

NOTE: When developing while using a trial site, you must use the --auth flag as described in Advanced Usage below.

After starting squarespace-server, you will see the following screen:

Starting Development Server

           _
       /  /      _
      /  /  /  /   \
     /  /  /  /  /  |    Squarespace Inc.
    |  /  /  /  /  /     Local Development Environment
     \ _ /  /  /  /
              /  /
            -

Version 0.1.00
Listening on port 9000

The start-up message displays both the version of squarespace-server, and the port on which the server is running.

Now you can open your browser to your site by typing in the url http://localhost:9000. Any changes you make to your local template files will be visible when you refresh your browser.

NOTE: You'll need to commit and push custom collection, custom post type and static page template files to Squarespace in order to preview them locally. Once a static page has been pushed it can be previewed and edited locally. After a custom collection or post type has been pushed you'll need to create a collection or item in the CMS first.

Advanced Use

You can view all the options with the command:

squarespace-server --help

If you have a site password, or your site is in trial mode, you'll need to log into your site via the dev server. You can do that with the following command:

squarespace-server https://site-name.squarespace.com --auth

Here's a list of some of the more useful options:

-h --help               Show this screen.
-d --directory=PATH     Path to template source.
-p --port=PORT          Port that server listens on.
--auth                  Login when starting server.
--verbose               Verbose logging.

You can also visit the NPM registry page for @squarespace/server to read about additional documentation and discover more advanced options.

Site CSS

According to our page on URL Queries, typically on a site you can append /site.css? and see all of the CSS. This doesn’t work with the Local Development Server.

http://localhost:9000/local-assets/site.css

This will only work when using the Local Development Server. Otherwise, please use what is stated on our URL Queries page.

Help and Feedback

If you have questions about working locally, or would like to provide feedback on Dev Server, please contact support and be sure to let them know you're using the Squarespace Local Development Server.