Project Setup

Create and configure your add-on project. Choose your preferred framework and tools.

Choose a Framework

SyncBooks add-ons work with any web technology. Here are the most common setups:

React + Vite (Recommended)

The fastest setup with the best SDK integration (hooks, components, TypeScript):

Terminal

# Create project
npm create vite@latest my-addon -- --template react-ts
cd my-addon

# Install SyncBooks SDK
npm install @syncbooks/addon-sdk

# Optional: Add Tailwind CSS for styling
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Next.js

If you need server-side rendering or API routes in your add-on:

Terminal

npx create-next-app@latest my-addon --typescript --tailwind
cd my-addon
npm install @syncbooks/addon-sdk

Next.js App Router note

If using App Router, make sure to add "use client" to components that use SDK hooks since they require browser APIs (postMessage, localStorage).

Vue 3

Terminal

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

Note: Vue doesn't use the React hooks, but you can use the initBridge() function and API client directly.

Plain HTML (No Framework)

For simple add-ons that don't need a build step:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My SyncBooks Addon</title>
</head>
<body>
  <div id="app">
    <h1>My Addon</h1>
    <div id="customers"></div>
  </div>

  <script type="module">
    // Import from CDN (ESM)
    import { initBridge, getContext } from 'https://esm.sh/@syncbooks/addon-sdk'

    // Initialize bridge — waits for context from SyncBooks
    const context = await initBridge()
    console.log('Connected!', context.organizationId)

    // Fetch customers using the token
    const res = await fetch('https://api.syncbooksapp.com/api/addon/v1/customers?limit=5', {
      headers: { Authorization: `Bearer ${context.sessionToken}` }
    })
    const { data } = await res.json()

    // Render
    document.getElementById('customers').innerHTML = data
      .map(c => `<p>${c.name} — ${c.email}</p>`)
      .join('')
  </script>
</body>
</html>

Project Structure

A typical React add-on project looks like this:

text

my-addon/
├── public/
│   └── icon.png              ← App icon (128×128, shown in marketplace)
├── src/
│   ├── main.tsx              ← Entry point (SyncBooksProvider here)
│   ├── App.tsx               ← Root component (routing/layout)
│   ├── pages/
│   │   ├── Dashboard.tsx     ← Main view
│   │   ├── Settings.tsx      ← Addon settings
│   │   └── Detail.tsx        ← Detail view
│   ├── components/
│   │   ├── Header.tsx
│   │   └── InvoiceCard.tsx
│   ├── hooks/
│   │   └── useAddonData.ts   ← Custom hooks for your logic
│   ├── lib/
│   │   └── utils.ts          ← Helper functions
│   └── index.css             ← Global styles (Tailwind imports)
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
├── tailwind.config.js
└── postcss.config.js

Configure Tailwind CSS

If you installed Tailwind, configure it:

tailwind.config.js

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        // Match SyncBooks brand colors
        brand: {
          50: '#ecfdf5',
          500: '#10b981',
          600: '#059669',
          700: '#047857',
        },
      },
    },
  },
  plugins: [],
}

src/index.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Optional: Match SyncBooks typography */
body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  font-size: 14px;
  line-height: 1.5;
}

TypeScript Configuration

The default Vite TypeScript config works perfectly. No changes needed.

SDK types are included

The @syncbooks/addon-sdk package includes full TypeScript definitions. You'll get autocomplete for all hooks, API methods, component props, and resource types.

Using the Starter Template

For the fastest start, copy the pre-configured template:

Terminal

# From the SyncBooks repo
cp -r packages/addon-starter-template my-addon
cd my-addon
npm install
npm run dev

The starter template includes everything pre-configured: React, TypeScript, Vite, Tailwind, SDK, and a working demo component.

Next Steps

Once your project is set up:

SDK Initialization — wire up the SyncBooksProvider
Fetching Data — start reading from the SyncBooks API