- Overview
- Features
- Documentation
- Getting Started
- Project Structure
- Usage Examples
- Contributing
- CI/CD
- Roadmap
- License
Unified product synchronization from Google Sheets to any e-commerce platform.
commerce-sync enables non-technical shop owners to manage their store’s product catalog directly from a Google Sheet and sync it with platforms like Squarespace (initial support), Shopify, and beyond. A “Sync Now” button in the sheet pushes product updates to the respective platform, while the backend also writes platform-generated values (product ID, variant ID, SKU, etc.) back into the sheet for consistency.
This project is designed with test-driven development (TDD), strict type safety, and a modular architecture to ensure long-term maintainability.
- Language/Runtime: Node.js (≥20), TypeScript (ESM, NodeNext)
- Framework: Express
- Testing: Vitest
- Linting: ESLint (Airbnb Base config)
- Deployment: Vercel (serverless functions)
- Docs: JSDoc (per module, function, type)
- Google Sheets integration (Apps Script frontend + Sheets API backend).
- Squarespace product sync (CSV export headers normalized → API payloads).
- Explicit type modeling (
ProductRow,SquarespacePayload). - Profiles system (pluggable validators/mappers for different platforms).
- Automatic write-back of Squarespace IDs/metadata into the sheet.
- Strict normalization of stringly-typed values (stock, visibility, booleans, URLs).
- JSDoc is available throughout the codebase. See JSDoc Guidelines
- Development Plan – full architecture, phases, risks, and deliverables.
- Project Roadmap
- Project Milestones
- Changelog
- Google Sheets Template (download “sheets-template.xlsx” from Releases) – required columns with a sample product row
- Node.js ≥ 20
- npm ≥ 9 (or pnpm/yarn if preferred)
- A Google account with Sheets access
- A Squarespace site (with developer API enabled)
git clone https://github.com/<your-org>/<repo>.git
cd <repo>
npm installnpm run testnpm run buildnpm run dev(The dev script starts an Express server locally; on Vercel, serverless routes are deployed automatically.)
src/
┣ integrations/ # Vendor API wrappers (Squarespace API client)
┣ sync/ # Core parsing, types, utilities
┣ sync/profiles/ # Validation & mapping for targets (SquarespaceProfile, etc.)
┣ server.ts # Express entrypoint
This example shows a complete flow using the Squarespace profile.
As other profiles are added (e.g., Shopify, Webflow), examples will be added for each.
- Shop owner fills out rows in the Google Sheets Template (download “sheets-template.xlsx” from Releases).
- Clicks “Sync Now” in the custom menu (Apps Script).
The Apps Script calls your backend’s /sync endpoint with the sheet’s data:
curl -X POST https://<your-vercel-deployment>/api/sync -H "Content-Type: application/json" -d '{"rows":[["Title","Price","Stock"],["Poster","25","7"]]}'- Rows are normalized into
ProductRowobjects. - Passed through the Squarespace profile validator.
- Mapped to a
SquarespacePayload. - Sent to Squarespace API.
- Squarespace response contains generated values (e.g.,
Product ID,Variant ID,SKU). - Backend updates the sheet via Sheets API to keep records consistent.
Result: the sheet is always the single source of truth, and Squarespace is updated accordingly.
We welcome contributions! Please follow the guidelines outlined in CONTRIBUTING
- GitHub Actions run linting, tests, and build.
- Deployment is handled via Vercel (staging + production environments).
See Development Plan for detailed phases and deliverables. Key milestones include:
- Phase 2: Row parsing finalized
- Phase 3: Profiles + validation
- Phase 4: Squarespace API integration
- Phase 5: Google Sheets integration
- Phase 6: Express/Vercel deployment
This project is licensed under the MIT License. See LICENSE for details.