Installation and setup

#Installation and setup

By the end of this guide you'll have a configured SvelteSync client instance ready to make API calls from your frontend or server.

#Prerequisites

• A running EmuView API (local dev server or deployed Worker)
• An API key or a user account for session-based auth
• Node.js 18+ or any runtime with a global fetch

#Steps

#1. Install the SDK

The SDK is a TypeScript package at packages/sdk/ in the EmuView repo. It has zero dependencies and compiles to ES modules, so it works in browsers, Node.js, Deno, and Cloudflare Workers.

# Option A: Copy the built SDK into your project
$ cp -r path/to/SvelteSync/packages/sdk/dist ./src/lib/sveltesync-sdk

# Option B: npm link during local development
$ cd path/to/SvelteSync/packages/sdk
$ npm link
$ cd path/to/your-frontend
$ npm link @emuview/sdk

#2. Initialise the client

Create one SvelteSync instance and reuse it across your app:

import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: 'https://your-api.example.com',
	auth: { apiKey: 'sk-your-api-key' }
});

#3. Use environment variables

Keep the API URL out of your source code so the same build works across environments:

// src/lib/sveltesync.ts
import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: import.meta.env.VITE_EMUVIEW_URL || 'http://localhost:8787'
});

export default sdk;

# .env.development
VITE_EMUVIEW_URL=http://localhost:8787

# .env.production
VITE_EMUVIEW_URL=https://your-api.example.com

#4. Verify the connection

Listing collections requires authentication (schemas are not public), so run this check on the server with an API key — never ship an admin key to the browser:

import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: process.env.EMUVIEW_URL!,
	auth: { apiKey: process.env.EMUVIEW_API_KEY! } // server-side only
});

const collections = await sdk.listCollections();
console.log(collections.map((c) => c.name)); // ['products', 'orders', ...]

#Configuration reference

The SvelteSync constructor accepts a single config object:

Option	Type	Required	Description
url	string	Yes	Base URL of your EmuView API, without the /api/v1 prefix
auth.apiKey	string	No	Server-side API key. Sent as a Bearer token on every request
auth.sessionToken	string	No	Client-side session token from a previous sign-in. Takes precedence over apiKey when both are set
fetch	typeof fetch	No	Custom fetch implementation. Defaults to globalThis.fetch
autoRefresh	boolean	No	Re-validate the session and retry once on a 401 response. Defaults to false
onSessionExpired	() => void	No	Callback invoked when the session has expired and cannot be refreshed

import { EmuView } from '@emuview/sdk';

const sdk = new EmuView({
	url: 'https://your-api.example.com',
	auth: { sessionToken: storedToken },
	autoRefresh: true,
	onSessionExpired: () => {
		window.location.href = '/login';
	}
});

See error handling for how autoRefresh and onSessionExpired behave when a request fails.

#Choosing an auth method

Scenario	Auth method
Public website reading published content	Read-only API key with the viewer role
User dashboard with login	Session token from sdk.auth.signIn()
Server-side rendering (SSR)	API key in a server-only environment variable
Third-party integration	Scoped API key with a custom role

#What you learned

• The SDK is a zero-dependency ES module that runs in any JavaScript runtime
• One SvelteSync instance per app, configured with url and optional auth
• API keys are for servers; session tokens are for browsers
• autoRefresh and onSessionExpired handle session expiry gracefully

#Next steps

• SDK authentication — sign users in and manage sessions
• SDK collections — create, query, and update records
• Error handling — catch and inspect ApiError