Documentation

What you can do:

Create a Session

A session represents one theme development project. It connects to a store, tracks your git repo, manages previews, and holds all QA and feedback data.

Shopify vs WooCommerce

Git Integration

Connect a git repository to keep your theme in sync with your team's workflow. ThemeSync clones the repo, pulls changes automatically, and — for WooCommerce — deploys updates to the live site.

Supported providers:

• GitHub — Use a Personal Access Token (PAT) with repo access
• GitLab — Use a Project or Personal Access Token
• Bitbucket — Use an App Password with repository read access
• Any git host — Any HTTPS git URL with credentials works

Auto-sync options:

Dashboard Navigation

The dashboard has a sidebar listing all your sessions and a main area with tabs for each feature:

Each session and tab has a shareable URL — bookmark or share links directly to specific views.

Connecting Your Store

When you start a session for the first time, Shopify asks you to authenticate:

Theme Access Password

A Theme Access password lets your session run without any manual authentication. This is the recommended setup for production use — your session stays running indefinitely with no re-auth prompts.

How to set it up:

1. Install the Theme Access app from the Shopify App Store on your client's store
2. Create a new password with the necessary permissions
3. Paste it into the session settings in ThemeSync

Benefits:

• No browser prompts — runs completely unattended
• Never expires — session stays active indefinitely
• Survives restarts — session automatically reconnects after any downtime
• Best for team use — no individual auth sessions to manage

Dev Server & Preview

Once your session is running, you get three key URLs:

Live Console

The dashboard includes a live console showing real-time output from the Shopify CLI. You can:

• Watch file change notifications and live-reload status
• See errors and warnings as they happen
• Send input to the CLI — answer prompts, select themes, type commands
• Reconnect anytime and see recent output history

How it works:

1. Install the Theme Sync plugin on your client's WordPress site
2. Connect the site to your ThemeSync session
3. Push theme changes via git — they automatically appear on the client's site
4. Share a preview link with your client to review the dev theme
5. Production visitors are completely unaffected — they see the normal live theme

Installing the Plugin

The Theme Sync plugin handles preview switching, theme delivery, and sync on the WordPress side:

Connecting to Your Site

To connect ThemeSync to a WordPress site, you need:

• Site URL — e.g., https://client-site.com
• WordPress username — An admin account
• Application Password — Generated in WP Admin → Users → Profile → Application Passwords

Once connected, ThemeSync can:

• Install and configure the plugin remotely
• Push theme updates automatically when you commit to git
• Fetch your site's pages for template mapping

Theme Preview

Once connected, ThemeSync generates a preview link you share with clients:

Only people with this link see the dev theme. Everyone else — shoppers, search engines, bots — sees the production theme. Zero risk.

Preview features:

• Full WordPress site rendering with your dev theme
• WP Admin access in preview mode (custom fields, page editor)
• Template overrides applied per page
• Secure token — cryptographically random, not guessable

Syncing Changes

When you push to your git branch, ThemeSync automatically delivers the updated theme to the client's WordPress site. The process takes seconds:

1. You push to git (or ThemeSync auto-pulls on schedule)
2. ThemeSync packages the theme and delivers it to the WordPress plugin
3. The plugin extracts the new files — your client sees the update immediately on their preview link

With auto-sync on, changes typically appear within 30–60 seconds of pushing.

Publishing Live

When the client approves the theme and you're ready to go live, publish directly from ThemeSync:

• The preview theme becomes the active live theme
• The preview session is cleaned up automatically
• No manual file copying or FTP needed

Why it matters:

• QA screenshots need real URLs — not just template file names
• Clients should browse the preview like a real store (homepage, products, collections, etc.)
• Different pages use different templates — mapping ensures the right template renders for each page

Shopify Templates

ThemeSync auto-detects template files from your theme and shows them in the Templates tab:

• Homepage — index.json
• Product pages — product.json
• Collections — collection.json
• Custom pages — page.*.json
• Blog & articles — blog.json, article.json

For each template, assign a store URL — the real page on the client's store that uses that template. ThemeSync fetches your store's products, collections, pages, and blogs so you can pick URLs from a dropdown.

WooCommerce Templates

For WordPress themes, ThemeSync scans for PHP template files and shows them in the Templates tab:

• Custom page templates — page-*.php
• Single post/product — single.php, single-*.php
• Archive pages — archive.php, archive-*.php
• Homepage — front-page.php

ThemeSync also fetches your WordPress pages so you can assign URLs with autocomplete.

Custom URLs

Not all pages come from the CMS. Add custom URLs for anything you want included in QA:

• Landing pages created via apps
• Cart and checkout pages
• Search results
• 404 pages
• Any special URL path

Custom URLs are saved per session and persist across QA runs.

Preview Snippet (Shopify)

The preview snippet enables template-aware routing — when a client browses /products/shirt on the preview, they see it rendered with the correct product template from your dev theme.

• Inject — adds a small snippet to your theme's layout (one click)
• Remove — cleanly removes it when you're done (one click)
• Uses your template mappings to serve the right template for each URL

How it works:

1. Select which pages to capture (from template mappings + custom URLs)
2. Choose devices — Desktop, iPhone, iPad, Android, Wide monitor
3. Pick a browser — Chrome, Firefox, Safari (WebKit), or real Safari via BrowserStack
4. Click capture — ThemeSync takes full-page screenshots with smart scrolling for lazy-loaded images
5. Review results in a visual grid and approve or flag issues per page

Device Presets

Select any combination of devices per QA run. The most common combo is Desktop + iPhone for quick checks, or all 5 for a full pre-launch audit.

Browser Engines

ThemeSync uses real browser engines — not device emulators or simulators. Each engine renders CSS and JavaScript differently, which is exactly why cross-browser testing matters:

Real Safari Testing

For the most accurate Safari testing, ThemeSync integrates with BrowserStack to capture screenshots on real hardware:

• iPhone 16 — real Mobile Safari on iOS 18
• iPad Pro 12.9" — real tablet Safari
• macOS Sonoma — real desktop Safari (latest version)
• Samsung Galaxy S24 — real Android Chrome

Code Scan

The code scan checks your theme source files for cross-browser compatibility issues and common performance problems:

What it checks:

Each finding includes a description, the affected file and line, and a recommended fix. Run a code scan before QA screenshots to fix issues proactively.

Dismiss Selectors

Many sites have popups, cookie banners, or modals that obscure the page during screenshots. Add dismiss selectors to automatically close them before capture:

• Add a CSS selector for the close button (e.g., .cookie-banner .close)
• ThemeSync clicks it before taking the screenshot
• Saved per session — works across all future QA runs

QA Approvals

After capturing screenshots, team members can approve or reject each page at each viewport:

A page is fully approved only when all required roles have signed off on all viewports. Rejections include a reason and can be resolved and re-approved later.

Feedback Sessions

A feedback session is a timed link that gives clients access to leave comments on your preview:

• Configurable expiry — set from 1 hour to 30 days
• No client login — they just click the link and start commenting
• Secure — links are cryptographically random and not guessable
• Revocable — close the session early if needed
• Reopenable — extend expired sessions with a new deadline

Feedback Overlay

When a client opens the feedback link, a lightweight commenting tool appears on top of the preview site:

• Pin-drop mode — click anywhere on the page to place a comment
• Comment form — type feedback with full page context captured automatically
• Free navigation — browse the entire theme naturally, leave comments on any page
• Device-aware — comments are tagged by viewport (mobile/tablet/desktop)
• Name entry — optional name/email so you know who said what

Comments & Pins

Each comment captures rich context so you know exactly what the client saw:

• Precise positioning — pinned to the exact spot on the page, even if the layout shifts
• Page context — which page, what viewport size, which browser
• Threaded replies — discuss back and forth on each pin
• Resolve & reopen — mark comments as fixed, reopen if the fix doesn't land
• Numbered pins — each pin gets a sequential number for easy reference in calls or emails

Page Approvals

Feedback sessions include a multi-role approval system. Each page can be approved per viewport per role:

• Client — approves via the feedback overlay
• Designer — approves visual fidelity
• QA — approves cross-browser correctness
• PM — final sign-off on scope and requirements

A page is "done" when all required roles have approved all viewports. The dashboard shows approval progress at a glance.

Exporting Feedback

Export all feedback data as structured JSON for your project management tool, reports, or archives. The export includes:

• All comments with their page and position context
• Resolution status and timestamps
• Page approval decisions and who approved
• Client identity (if provided)

Roles & Permissions

Inviting Members

Add team members in a few clicks:

1. Go to the Team page
2. Enter their email and choose a role
3. Share the invite link (valid for 7 days)
4. When they sign in, they're automatically added to your team

Approval Workflow

The approval system tracks sign-offs across Page × Viewport × Role. A theme is ready to ship when:

• All required roles have approved each page at each viewport
• All feedback comments are resolved
• No critical code scan findings remain

You can see overall approval progress on the QA tab — a quick visual showing what's approved, what's pending, and what's been rejected.

Connecting a Repo

Add a git URL when creating a session (or update it in settings). ThemeSync clones the repo and checks out your specified branch:

• Supports any git host — GitHub, GitLab, Bitbucket, or self-hosted
• Private repos are supported — embed credentials in the URL or use a token
• Each session has its own isolated copy of the repo

Auto-Sync

With auto-sync enabled, ThemeSync periodically pulls the latest changes from your remote branch:

• Choose an interval: 30s, 1 min, or 5 min
• Changes are pulled in the background — you see a notification in the console
• For WooCommerce, updates are automatically deployed to the client site
• Manual pull is always available via the "Sync" button

Branches & Versions

Need to preview a different branch? Use Duplicate Session:

1. Click "Duplicate" on an existing session
2. Choose a different git branch
3. Optionally carry over template mappings
4. Both sessions run side-by-side — compare branches in real-time

This is ideal for A/B testing designs, reviewing feature branches before merge, or maintaining a "staging" and "production" preview simultaneously.

Theme Intelligence

Theme Intelligence scans your theme and builds a map of everything a client can edit:

• Templates — which pages the theme supports
• Sections — every customizable section and its options
• Settings — all theme settings (colors, fonts, layouts, toggles)
• Editability — what the client can change vs what requires a developer

This data powers the script generator and helps you build accurate handoff docs.

Script Generation

Using the theme intelligence data, ThemeSync generates client-facing walkthrough scripts that explain:

• How to edit each section of the theme
• Where to upload images and change text
• What each theme setting controls
• Tips for keeping the design consistent

Scripts can be generated as text (for documentation) or paired with AI voiceover for video walkthroughs. Supports professional-quality voice synthesis for polished client deliverables.

Your Account

Sign in with Google, GitHub, or email and password. Your account is created automatically on first sign-in — no separate registration step.

• Sessions stay active across tabs and browser windows
• All your sessions, team memberships, and billing info are tied to your account
• Admin access is granted to designated team leads (configured by your org)

Billing & Plans

• Free tier — 1 session with basic QA features, no card required
• Paid plans — Multiple sessions, BrowserStack integration, team features, priority support
• Self-serve portal — Upgrade, downgrade, update payment, and view invoices anytime
• Cancel anytime — Access continues until end of your billing period