Quick Start

Build and run your first SyncBooks add-on in under 5 minutes.

Prerequisites

You need Node.js 18+ and a SyncBooks account with developer access approved. Go to /developers → Developer Profile to register.

Create the project

Open your terminal and run:

bash

npm create vite@latest my-addon -- --template react-ts
cd my-addon
npm install @syncbooks/addon-sdk

Set up the SDK

Replace src/main.tsx with:

src/main.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'
import { SyncBooksProvider } from '@syncbooks/addon-sdk'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <SyncBooksProvider>
      <App />
    </SyncBooksProvider>
  </React.StrictMode>
)

Build your first component

Replace src/App.tsx with:

src/App.tsx

import { useSyncBooks, useCustomers, ui } from '@syncbooks/addon-sdk'

export default function App() {
  const { ready, organizationId } = useSyncBooks()
  const { data: customers, loading } = useCustomers({ limit: 5 })

  if (!ready) return <p>Connecting...</p>
  if (loading) return <p>Loading customers...</p>

  return (
    <div style={{ padding: 24 }}>
      <h1>My First Add-on</h1>
      <p>Connected to org: {organizationId}</p>
      
      <h2>Recent Customers</h2>
      <ul>
        {customers.map(c => (
          <li key={c._id}>{c.name} — {c.email}</li>
        ))}
      </ul>
      
      <button onClick={() => ui.notify('Hello from my addon!', 'success')}>
        Show Toast
      </button>
    </div>
  )
}

Run it

bash

npm run dev

Open http://localhost:5173 — you'll see your add-on.

API calls won't work yet

The SDK needs a valid session token from SyncBooks. To test with real data, you need to either register the add-on on the marketplace (draft mode) or configure a test token. See Testing for details.

Deploy & register

bash

npm run build
npx vercel deploy

Then go to /developers → Marketplace Add-ons → New Addon:

Set Launch URL to your Vercel URL
Select permissions: customers.read
Select placement: navigation.item
Click Create

Your add-on is now in draft mode. Install it from the Add-ons page in your dashboard to test.

What's Next?

Project Setup — detailed project configuration options
Fetching Data — all the hooks and API methods available
UI Components — 37 pre-styled components for native-looking UI