Squarespace engineering blog

Try:

Squarespace3 weeks ago

Making Documentation Simpler and Practical: Our Docs-as-Code Journey

Squarespace Domains engineering adopted a Docs-as-Code approach: documentation lives alongside code in Git, is reviewed via PRs, written in Markdown with Mermaid diagrams, and is deployed via CI/CD into Backstage. They describe tooling (TechDocs CLI, IntelliJ Mermaid plugin, Kroki), branch preview environments, and benefits including better architecture docs, traceability, faster iteration, and collaborative ownership.

Squarespace5 months ago

Leveraging Change Data Capture For Database Migrations At Scale

Squarespace migrated many PostgreSQL databases to CockroachDB with minimal downtime by building a logical CDC-based pipeline: Postgres WAL -> pgoutput -> Debezium (via Kafka Connect) -> Kafka (Avro) -> Apache Beam consumers -> CockroachDB. Pipelines ran on Google Cloud Dataflow (Terraform-managed Flex templates), were checkpointed and backpressured, and a fallback path mirrored changes back to Postgres for quick rollback. The team handled schema incompatibilities, referential integrity challenges, and validated data before cutover.

Squarespace1 year ago

Unfold's Modern Mobile Release Process and the Subtle Art of Making Them Boring

Squarespace's Unfold team describes how they made mobile releases "boring" by standardizing a one-week release train, rotating a release captain role, adopting test management (Xray), using a mobile release management platform (Runway), and integrating monitoring (Crashlytics, Amplitude) to automatically halt staged rollouts. The changes reduced hotfix frequency, lowered manual overhead, and improved QA and release predictability for iOS and Android apps.

Squarespace1 year ago

Why We Built a Write Back Cache for Our Asset Library with Google Cloud Spanner

Squarespace’s Alexandria asset library switched from synchronous GCS object updates to a write-back cache implemented on Google Cloud Spanner to avoid GCS per-object write limits and long-tail write latencies. Writes are applied to Spanner and served immediately, while an asynchronous process flushes the end-state to GCS; this removed complex write-coalescing logic and significantly reduced average and p99 write latencies. The change was rolled out via a canary fleet and load testing.

Squarespace1 year ago

Outro: What You Did and What’s Next

Final post of a five-part technical writing tutorial. It recaps accomplishments (draft, revise, publish), introduces a basic information architecture for organizing documentation, gives a step-by-step approach to revising existing docs (identify audience, identify goal/content type, reorganize, update, republish), recommends resources and communities for further learning (Google course, books, Google Season of Docs, WriteTheDocs Slack), and advises against tackling large glossaries as part of small updates.

Squarespace1 year ago

Part 4: Test, Edit, And Publish Content

Part 4 of a five-part Squarespace tutorial on technical writing that covers testing, editing, approving, merging, and publishing documentation. The author presents an A-TEAM workflow (Away from the content; Test; Edit; Approve; Merge; Away from the content), recommends using style guides and readability tools, stresses verifying code examples, describes reviewer/approval practices, and explains merging via pull requests and using a CI/CD pipeline to convert Markdown to HTML and auto-publish to platforms like Confluence or Backstage. The post also references docs-like-code/docs-as-code practices and tools for converting Google Docs to Markdown.

Squarespace1 year ago

Part 3: Draft Content That’s Accurate, Consistent, And Concise

Part 3 of a technical writing tutorial about drafting accurate, consistent, and concise documentation. Covers why accuracy and consistency matter, recommends a glossary, provides guidelines/cheat-sheet for common content types (getting started, tutorials, how-tos, explanations, reference, troubleshooting), uses a mock CLI tool (CatFactz) as an example, and recommends collaborative editing tools (Google Docs). Next post will cover testing, editing, and publishing content.

Squarespace1 year ago

Part 2: Use Good Headings For Structure And Scanning

Part 2 of a five-part technical-writing tutorial that explains how to use clear headings and content structure to make documentation easy to scan. It outlines common heading patterns for different doc types (getting started, tutorials, how-tos, explanations, reference, troubleshooting), cites Nielsen Norman Group research on web reading behavior, and gives examples (IBM, Figma).

Squarespace1 year ago

Part 1: Learn The Different Types Of Technical Documentation

Part 1 of a five-part technical writing tutorial that explains the different types of technical documentation (getting started, how-to, tutorial, explanation, reference, troubleshooting), describes reader traits (behavior, patience, experience, goal), references the Diataxis framework and the "Every Page Is Page One" philosophy, links to example resources (Microsoft, Pluralsight, Atlassian, IBM, etc.), and includes a short exercise to pick an app and a content type to document. It previews Part 2 on headings.

Squarespace1 year ago

Technical Writing: How To Start

A Squarespace engineering blog tutorial introducing a five-part guide to technical writing: types of documentation, using headings for scanning, drafting concise/consistent content, testing/editing/publishing (A-TEAM), and joining the docs community.

Squarespace3 years ago

Developing Fluid Engine

Squarespace’s Fluid Engine replaces their rigid 12-column Layout Engine with a system that supports independent, predictable drag-and-drop positioning and resizing of blocks while preserving responsive behavior and natural content flow. After prototyping approaches using absolute pixel and percentage positioning, the team identified the need to handle text wrapping and viewport changes without heavy JavaScript. They ultimately leaned on CSS Grid and a new data model to meet requirements for usability, responsiveness, and performance.

Squarespace3 years ago

A Better Way to Upload Images

Squarespace built a seamless "Upload from Mobile" feature that lets users import photos from the Squarespace mobile app directly into the desktop site editor. They evaluated WebSockets vs polling and chose a REST-based polling job approach (server maintains job state, returns jobID, mobile uploads image and posts assetID, browser polls and applies the image). The post covers UX research, architecture, trade-offs (security, cost), QR-code fallback for app installs, and launch.

Squarespace3 years ago

How we use WebGL at Squarespace

Squarespace engineers describe how they implemented the Background Art feature using WebGL. They built a small, modular WebGL library and component system to render animated section backgrounds across templates and the CMS UI, handling browser compatibility (OffscreenCanvas, drawImage fallback), resource limits, accessibility (reduced-motion), viewport-driven updates (IntersectionObserver), and planning for a future WebGPU migration.

Squarespace3 years ago

Engineering Manager Forum

The article describes why and how Squarespace created an Engineering Manager (EM) Forum: motives (manager isolation, onboarding, cross-team context), meeting principles (facilitator, agenda, timeboxing, recordings), typical agenda (announcements, new-manager intros, team overviews, management shares, Q&A), outcomes (community building, crowd-sourced burnout mitigation tips), and a blueprint/backlog for others to replicate. It emphasizes meeting hygiene, inclusivity for managers, and practical meeting mechanics.

Squarespace4 years ago

The Nuts and Bolts with Tom Drapeau

Interview with Tom Drapeau about his transition from engineer to manager, why he joined Squarespace, and his views on engineering culture, DEI, work–life balance, burnout, imposter syndrome, and career progression. The piece also briefly references past technical work (frontend replatform at HotJobs, C++ bindings to Yahoo's ysearch, and PHP extensions).

Squarespace4 years ago

Collaborating to Build an Uncertain Layout

Squarespace engineers and designers collaborated to build an Auto Layouts system that reduces manual block arrangement. The article describes the problem, preparatory work, a joint meeting where diagrams and concrete scenarios guided decisions (e.g., choosing max columns vs. direct column widths), and lessons about cross-functional collaboration, tradeoffs, and inclusive decision-making.

Squarespace4 years ago

How We Improved Our Core Block Editing Experience Without It Feeling Like Technical Debt

Squarespace’s Core Layout team modernized block editors by migrating from legacy YUI editors to a React + ES2020+ based flow aligned with the Rosetta design system. They used an internal JSON Schema Forms (JSF) approach and an uischema-builder tool to generate uiSchemas, published those schemas as a separate npm package (@sqs/block-editor-schemas) outside the monolith, and rolled changes out incrementally using feature flags and staged rollouts. The project also enabled deletion of legacy code and improved collaboration with Design and QA.

Squarespace4 years ago

Synchronizing Application State Across Browser Frames

Squarespace built an internal "Universal State" library to synchronize shared application state between the top window and iframe-mounted apps. It offers a Redux/useReducer-style interface; iframe imports create proxy stores that communicate with the top-window store via a Comlink-wrapped postMessage/MessageChannel bridge. During incremental rollout (feature flags) a race condition caused a production outage; they fixed it by queuing pending actions in iframes and plan to improve smoke tests and documentation.

Squarespace4 years ago

How I Learned to Stop Worrying and Love the Tests

An engineer describes how Squarespace introduced an automated testing culture for their iOS app between 2019–2020. They used coaching (1:1s, pairing), adopted tooling (Quick, Nimble, Resolver, SonarQube), applied architectural practices (mvvm, dependency injection, service-locator, router patterns), and focused on unit, integration, and snapshot tests. The effort increased code coverage (13.9% → 54.7%), reduced manual QA requests by ~75% and hotfix releases by ~66%, and improved modularity and developer confidence.

Squarespace4 years ago

How We Reimagined A/B Testing at Squarespace

Squarespace rebuilt its A/B testing program by creating a unified experimental stack (praetor for assignments, amplitude for analytics, horseradish for stats/visualization), decentralizing execution with self-service tooling and training, and fostering a culture of iterative, hypothesis-driven product development — resulting in higher test volume, faster turnaround, and more data-driven decisions.