Home
JS SDK (Browser)
JS SDK (Server)
FAQ
Home
JS SDK (Browser)
JS SDK (Server)
FAQ

Getting Started

This guide will walk you through setting up the Asterisms JS SDK in your browser application. You'll learn how to install, configure, and make your first API call.

Prerequisites

Before you begin, ensure you have:

  • Node.js 16.0 or higher
  • TypeScript 4.5 or higher (recommended)
  • A modern browser (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
  • Access to an Asterisms ecosystem domain

Installation

Install the Asterisms JS SDK using your preferred package manager:

# Using npm
npm install @asterisms/sdk

# Using yarn
yarn add @asterisms/sdk

# Using pnpm
pnpm add @asterisms/sdk

Basic Setup

1. Create a Navigation Adapter

The SDK requires a navigation adapter to handle routing within your application. Here's how to create one for different frameworks:

SvelteKit

import { goto } from '$app/navigation';
import { page } from '$app/stores';

function createSvelteKitNavigator() {
  return {
    navigate: async (url: string) => {
      await goto(url);
    },
    getCurrentUrl: () => {
      return window.location.href;
    }
  };
}

React Router

import { useNavigate, useLocation } from 'react-router-dom';

function createReactRouterNavigator() {
  const navigate = useNavigate();
  const location = useLocation();

  return {
    navigate: async (url: string) => {
      navigate(url);
    },
    getCurrentUrl: () => {
      return window.location.href;
    }
  };
}

Vanilla JavaScript

function createBasicNavigator() {
  return {
    navigate: async (url: string) => {
      window.location.href = url;
    },
    getCurrentUrl: () => {
      return window.location.href;
    }
  };
}

2. Initialize the SDK

Create your SDK instance with the required configuration:

import { asterismsFactory, createFetchAdapter } from '@asterisms/sdk';

// Initialize the SDK
const sdk = asterismsFactory({
  // Your application's unique identifier
  bundleId: 'com.example.your-app',

  // Your Asterisms ecosystem domain
  domain: 'your-ecosystem.asterisms.io',

  // Navigation adapter for your framework
  navigator: createSvelteKitNavigator(),

  // HTTP adapter (optional - defaults to fetch)
  httpFactory: createFetchAdapter(fetch),

  // Persistence adapter (optional - defaults to localStorage)
  persistence: LocalPersistence,

  // Hydration data for SSR (optional)
  hydration: {
    account: initialAccount,
    workspace: initialWorkspace
  }
});

3. Boot the SDK

The SDK must be booted before use. This initializes all registered resources:

async function initializeApp() {
  try {
    // Boot the SDK
    const { status } = await sdk.boot();
    console.log('SDK boot status:', status);

    if (status === 'booted') {
      console.log('✅ Asterisms JS SDK ready!');
    }
  } catch (error) {
    console.error('❌ SDK initialization failed:', error);
  }
}

// Call during app startup
initializeApp();

Your First API Call

Once the SDK is booted, you can start making API calls. Here's how to check authentication status and get user information:

async function checkAuthentication() {
  // Check if user is authenticated
  const isAuthenticated = sdk.auth().currentTokenIsValid();

  if (!isAuthenticated) {
    console.log('User not authenticated');
    // Redirect to login or show login UI
    await sdk.auth().authenticate();
    return;
  }

  // Get current user account
  const account = sdk.account().currentAccount();
  console.log('Current user:', account?.email);

  // Get user's workspace
  const workspace = sdk.account().currentWorkspace();
  console.log('Current workspace:', workspace?.name);

  // Get user profile
  const profile = sdk.profile().currentProfile();
  console.log('User profile:', profile);
}

checkAuthentication();

Complete Example

Here's a complete working example combining all the pieces:

// app.ts
import { asterismsFactory, createFetchAdapter } from '@asterisms/sdk';

// Create navigation adapter
function createNavigator() {
  return {
    navigate: async (url: string) => {
      window.location.href = url;
    },
    getCurrentUrl: () => window.location.href
  };
}

// Initialize SDK
const sdk = asterismsFactory({
  bundleId: 'com.example.my-app',
  domain: 'demo.asterisms.io',
  navigator: createNavigator(),
  httpFactory: createFetchAdapter(fetch)
});

// Application startup
async function startApp() {
  try {
    // Boot SDK
    const { status } = await sdk.boot();

    if (status !== 'booted') {
      throw new Error(`SDK failed to boot: ${status}`);
    }

    // Check authentication
    const isAuthenticated = sdk.auth().currentTokenIsValid();

    if (isAuthenticated) {
      // User is logged in
      const account = sdk.account().currentAccount();
      console.log(`Welcome back, ${account?.email}!`);

      // Load application data
      loadAppData();
    } else {
      // Redirect to authentication
      console.log('Please log in');
      await sdk.auth().authenticate();
    }
  } catch (error) {
    console.error('Application startup failed:', error);
  }
}

async function loadAppData() {
  // Example: Get platform information
  const platform = sdk.platform();
  const apps = platform.currentProductCatalog();
  console.log('Available applications:', apps);

  // Example: Set up event listeners
  sdk.auth().subscribe('loggedin', () => {
    console.log('User logged in');
  });

  sdk.auth().subscribe('loggedout', () => {
    console.log('User logged out');
    // Redirect to login
  });
}

// Start the application
startApp();

Framework Integration

SvelteKit Integration

For SvelteKit applications, you can use the provided UI context:

// app.html or layout
import { AsterismsProvider } from '@asterisms/svelte-ui';

const initProps = {
  bundleId: 'com.example.my-app',
  domain: 'demo.asterisms.io',
  navigator: createSvelteKitNavigator()
};

// In your layout
<AsterismsProvider {initProps}>
  <slot />
</AsterismsProvider>

React Integration

For React applications, create a context provider:

// AsterismsProvider.tsx
import React, { createContext, useContext, useEffect, useState } from 'react';
import { asterismsFactory, type AsterismsSdk } from '@asterisms/sdk';

const AsterismsContext = createContext<AsterismsSdk | null>(null);

export function AsterismsProvider({ children }: { children: React.ReactNode }) {
  const [sdk, setSdk] = useState<AsterismsSdk | null>(null);

  useEffect(() => {
    const sdkInstance = asterismsFactory({
      bundleId: 'com.example.my-app',
      domain: 'demo.asterisms.io',
      navigator: createReactRouterNavigator()
    });

    sdkInstance.boot().then(() => {
      setSdk(sdkInstance);
    });
  }, []);

  return (
    <AsterismsContext.Provider value={sdk}>
      {children}
    </AsterismsContext.Provider>
  );
}

export function useAsterismsSDK() {
  const sdk = useContext(AsterismsContext);
  if (!sdk) {
    throw new Error('useAsterismsSDK must be used within AsterismsProvider');
  }
  return sdk;
}

Next Steps

Now that you have the SDK set up and running:

  1. Learn Core Concepts - Read the Core Concepts guide to understand SDK architecture
  2. Explore Authentication - Check out Authentication for advanced auth patterns
  3. Work with Resources - Learn about Resources and how to register custom ones
  4. Handle Events - Understand the Event System for real-time updates
  5. Browse Examples - See practical implementations in the Examples section

Troubleshooting

If you encounter issues during setup:

  • Ensure your bundle ID is unique and follows reverse DNS notation
  • Verify your domain configuration with your Asterisms administrator
  • Check browser console for detailed error messages
  • Review the Troubleshooting guide for common issues

Community Support

Need help? Join our community:

  • 💬 GitHub Discussions - Ask questions and share ideas
  • 🐛 GitHub Issues - Report bugs and request features
  • 📖 Documentation - Browse the complete API reference
ON THIS PAGE