@resypress/theme-sdk

SDK for building ResyPress themes - reusable components, API services, and utilities.

Open Source

This project is open source and available under the MIT License.

Installation

npm install @resypress/theme-sdk

Quick Start

Initialize the SDK

The SDK automatically detects configuration from multiple sources. You can initialize it with minimal or no configuration:

import { init } from '@resypress/theme-sdk';

// Option 1: Auto-detect from domain (recommended for production)
// The SDK will automatically detect account from the current domain
await init();

// Option 2: Override specific values
await init({
  accountID: '123',
  apiBaseUrl: 'https://api.resypress.com/api',
  locale: 'en',
});

// Option 3: Use environment variables in development
// In your theme project, create a .env file with:
// VITE_RESYPRESS_ACCOUNT_ID=123
// VITE_RESYPRESS_API_BASE_URL=http://localhost:8080/api
// VITE_RESYPRESS_LOCALE=en
// Then pass them to init():
await init({
  accountID: import.meta.env.VITE_RESYPRESS_ACCOUNT_ID,
  apiBaseUrl: import.meta.env.VITE_RESYPRESS_API_BASE_URL || '/api',
  locale: import.meta.env.VITE_RESYPRESS_LOCALE || 'en',
});

Configuration Priority

The SDK uses the following priority order (highest to lowest):

1. Explicit init() options - Values passed directly to init()
2. localStorage overrides - For runtime testing (useful for development)
   • RESYPRESS_ACCOUNT_ID
   • RESYPRESS_API_BASE_URL
   • RESYPRESS_LOCALE
3. window.RESYPRESS__CONFIG - Injected config object (from config.json or server-side)
4. Domain auto-detection - Automatically detects account from current hostname
   • Uses the FULL domain name (e.g., example.com or www.example.com)
   • Matches backend's WebsiteDomain lookup behavior (looks up by full domain_value)
   • Skips localhost and IP addresses
5. Default values - Fallback defaults (/api for base URL, en for locale)

Environment Variables in Development

For development, you can use environment variables in your theme project's .env file:

VITE_RESYPRESS_ACCOUNT_ID=123
VITE_RESYPRESS_API_BASE_URL=http://localhost:8080/api
VITE_RESYPRESS_LOCALE=en

Then pass them to init():

await init({
  accountID: import.meta.env.VITE_RESYPRESS_ACCOUNT_ID,
  apiBaseUrl: import.meta.env.VITE_RESYPRESS_API_BASE_URL || '/api',
  locale: import.meta.env.VITE_RESYPRESS_LOCALE || 'en',
});

Note: The SDK cannot directly access your project's import.meta.env at runtime, so you need to pass environment variables explicitly to init().

Use API Services

import { apiClient } from '@resypress/theme-sdk';

// Make API calls
const properties = await apiClient('/public/{accountID}/properties');

Use Utilities

import { getText } from '@resypress/theme-sdk';

// Handle multilingual strings
const name = getText(property.name, 'en'); // Returns 'en' version or fallback

Features

• ✅ Core Configuration - Initialize and manage SDK configuration
• ✅ API Client - Type-safe API client with error handling
• ✅ i18n Utilities - Multilingual string handling
• ✅ React Components - Pre-built UI components (PropertyCard, BookingForm, GuestPortalLogin, GuestPortalChat, etc.)
• ✅ React Hooks - Data fetching hooks with React Query integration
• ✅ API Services - Direct API access functions

Documentation

• Usage Guide - Complete guide for using the SDK (components, hooks, services, utilities)
• Implementation Plan - Detailed technical implementation documentation

Development

# Install dependencies
npm install

# Build the library
npm run build

# Type check
npm run type-check

# Watch mode
npm run dev

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.