Here at Squarespace, we use the Developer Platform every day to create templates and to work on our front site. We’re customers of our own platform, just like any developer who uses Squarespace. As such, we’re always looking for ways to improve the developer experience -- not only does it help our developer community, it makes us more productive as well.

Today, we’re announcing a new developer tool called the Squarespace Local Development Server. With it, developers can preview changes to template code locally (on their computer) before pushing them to a live website. This is the story of how this tool came about, and what it does.

A Hard Truth

A few months back we had a company offsite focused on our developer platform. During discussions between our template developers and other engineers, we decided that our workflow needed some love. We were resorting to workarounds in order to be productive. For example, despite the fact that every Squarespace template comes with a built-in Git server, we weren’t using Git. Instead, we were using SFTP to sync our files. Additionally, we were creating multiple copies of each template during development, and struggling to keep our code in sync.

The root cause was the lack of a local development server. Such a tool would allow us to work locally, preview changes instantly, and work with multiple versions of our templates. Without it, the Git workflow made little sense.

Of course, we weren’t the only ones feeling this pain. Since I arrived at Squarespace in late 2014, I’ve talked with several developers and agencies that use Squarespace. Whenever I asked for feedback, the most frequent request I heard was for a way to develop templates locally.

With this in mind, we set out to create a tool that would let us work on Squarespace without having to deploy every change we wanted to test. We hoped to make the process of working on Squarespace much more simple, immediate, and creative.

Starting from Scratch

Though we already had a server capable of rendering Squarespace templates (squarespace.com), this new tool had very different requirements. We needed something lightweight that used the filesystem instead of a distributed database. Essentially we needed to build a local version of Squarespace from scratch.

We got to work, and after a few months, our server was ready for internal testing. During the following weeks, we attempted to use the server to discover bugs; we’d fix them, and then repeat the process over and over again. After each cycle, we were able to use the Dev Server for bigger, more complex websites. Eventually we were able to render our own website (www.squarespace.com) on the Server. This was a watershed moment.

Once the WWW team got their hands on the Server, it quickly became clear that our hard work had been worthwhile. Suddenly, this team could test new designs without having to shuffle content between production and staging sites. Another bonus was that it greatly improved collaboration on the team. Whereas each developer previously needed to maintain his or her own repository, now team members could work on separate branches while remaining in sync with each other’s changes.

The Dev Server quickly became our standard tool for working on Squarespace templates. We now use it daily across multiple teams and it has dramatically improved the way we work.

Under the Hood

The Squarespace Local Development Server is a relatively simple HTTP server that renders web pages using a local copy of a template’s source code. It’s half web application, half proxy. To render web pages, it combines the local template files with data from a remote Squarespace website. This means the template code that’s edited locally is rendered locally, while content that’s edited on squarespace.com is fetched from a live website.

When you access a website running the Dev Server via http://localhost:9000, you’ll see the console logging various requests from your browser. The first time you access a local template, it will take a while to load as the server fetches the site content. However, once the content has been cached, subsequent requests will complete more quickly until you terminate the server. If you need to invalidate the cache (because you’ve updated your website in the online editor, for example) you can use the ?nocache=true query parameter on any URL.

Fetching content from the live website has positive and negative aspects. It means that the Server still needs a network connection to function. You can’t always use it to develop sites while flying in a plane, for example. On the other hand, it’s easy to test a new design using content from an existing website. Just run Dev Server from your local template folder and point it to a live website. Finally, we’re working on improving the caching of Dev Server so you can pull down your live content and view it at a later point.

The Development Server is built with Java using the Dropwizard framework. It takes advantage of our open-sourced JSON-T compiler and Less compiler. It’s packaged and distributed over NPM using a set of install scripts that detect the target platform and ensure Java is configured correctly. It’s built to be cross-platform, so Windows, Linux, and Mac developers can all take advantage of the efficiencies the Dev Server provides.

Trying it Out

Squarespace Local Development Server is available as a public NPM package. You can download it by running:

npm install -g @squarespace/server

For more help with installation and use, please check out our Help Guide. Finally, we’d love your feedback! If you run into any issues or have feature requests, please reach out to our Customer Care team, and mention that you’re using the Local Development Server.

If you love creating creative tools for web developers, or you’re interested in exploring challenges like the one we faced creating the Development Server, we’re hiring!