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

Configuration

The Asterisms JS SDK provides configuration options to customize behavior and integration with your application. This guide covers all available configuration options and their usage.

SDK Factory Configuration

The SDK is initialized using asterismsFactory() with the following configuration options:

Required Configuration

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

const sdk = asterismsFactory({
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator: yourNavigationAdapter
});

Complete Configuration

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

const sdk = asterismsFactory({
  // Required Configuration
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator: yourNavigationAdapter,

  // Optional Configuration
  initialRoute: '/dashboard',
  persistence: createPersistence(),
  httpFactory: createAxiosAdapter(axios),
  registrations: customAppRegistrations,
  hydration: ssrHydrationData,
  extenders: [customExtensionBuilder],
  lightspeed: {
    kid: 'your-key-id',
    loginUrl: 'https://auth.yourapp.com/login',
    requiresAuth: true
  },
  loggerLevel: 'INFO',
  devConfigServer: 'http://localhost:3001'
});

Configuration Properties

bundleId (required)

  • Type: BundleId (string)
  • Description: Unique identifier for your application
  • Example: 'com.yourcompany.yourapp'

domain (required)

  • Type: string
  • Description: The root domain of the Asterisms ecosystem
  • Example: 'yourapp.com'

navigator (required)

  • Type: NavigationAdapter
  • Description: Navigation adapter for routing (SvelteKit, React Router, etc.)
  • Example: See Navigation Adapters

initialRoute (optional)

  • Type: string
  • Description: The URL the page began on, used for smart redirecting post-login
  • Example: '/dashboard'

persistence (optional)

  • Type: PersistenceAdapter
  • Description: Storage adapter for persistent data (defaults to localStorage)
  • Example: See Persistence Adapters

httpFactory (optional)

  • Type: HttpServiceAdapterFactory
  • Description: HTTP adapter factory for making requests (defaults to fetch)
  • Example: See HTTP Adapters

registrations (optional)

  • Type: AppRegistrations
  • Description: List of custom applications to register
  • Example: See Custom Applications

hydration (optional)

  • Type: AppHydration
  • Description: Data loaded during SSR to be injected into the SDK
  • Example: See SSR Hydration

extenders (optional)

  • Type: AsterismsResourceExtensionBuilder[]
  • Description: Custom resource extension builders
  • Example: See Resource Extensions

lightspeed (optional)

  • Type: LightspeedClientConfig
  • Description: Configuration for Lightspeed applications
  • Properties:
    • kid: string - Key ID for authentication
    • loginUrl: string - Login service URL
    • requiresAuth: boolean - Whether app requires authentication

loggerLevel (optional)

  • Type: LoggerLevel
  • Description: Default logging level
  • Values: 'DEBUG', 'INFO', 'WARN', 'ERROR'
  • Default: 'INFO'

devConfigServer (optional)

  • Type: string
  • Description: URL to local development configuration server
  • Example: 'http://localhost:3001'

Navigation Adapters

Navigation adapters provide routing functionality for different frameworks:

SvelteKit Navigation Adapter

import { createSvelteKitNavigationAdapter } from '@asterisms/svelte-ui';

const navigator = createSvelteKitNavigationAdapter({
  goto,
  page: { url, params }
});

React Router Navigation Adapter

import { createReactRouterNavigationAdapter } from '@asterisms/sdk';

const navigator = createReactRouterNavigationAdapter({
  navigate: useNavigate(),
  location: useLocation()
});

Custom Navigation Adapter

import type { NavigationAdapter } from '@asterisms/sdk';

const customNavigator: NavigationAdapter = {
  navigate(path: string, options: NavigationOptions) {
    // Implement navigation logic
    window.history.pushState(options.state, '', path);
  },

  resolve(path: string) {
    return {
      href: new URL(path, window.location.origin).href
    };
  },

  getLocationHistory() {
    return {
      pathname: window.location.pathname,
      search: window.location.search,
      hash: window.location.hash
    };
  }
};

Persistence Adapters

Persistence adapters handle data storage:

Default (localStorage)

import { createPersistence } from '@asterisms/sdk';

const persistence = createPersistence(); // Uses localStorage

Session Storage

import { createPersistence } from '@asterisms/sdk';

const persistence = createPersistence(sessionStorage);

In-Memory Storage

import { createPersistence, InMemoryDriver } from '@asterisms/sdk';

const persistence = createPersistence(new InMemoryDriver());

Custom Storage

import type { StorageDriver } from '@asterisms/sdk';

const customDriver: StorageDriver = {
  getItem(key: string) {
    // Custom get logic
    return customStorage.get(key);
  },

  setItem(key: string, value: string) {
    // Custom set logic
    customStorage.set(key, value);
  },

  removeItem(key: string) {
    // Custom remove logic
    customStorage.remove(key);
  },

  clear() {
    // Custom clear logic
    customStorage.clear();
  }
};

const persistence = createPersistence(customDriver);

HTTP Adapters

HTTP adapters handle network requests:

Axios Adapter

import axios from 'axios';
import { createAxiosAdapter } from '@asterisms/sdk';

const httpFactory = createAxiosAdapter(axios);

Fetch Adapter (Default)

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

const httpFactory = createFetchAdapter();

Custom HTTP Adapter

import type { HttpServiceAdapterFactory } from '@asterisms/sdk';

const customHttpFactory: HttpServiceAdapterFactory = {
  create(config) {
    // Return custom HTTP adapter implementation
    return {
      async request(config) {
        // Custom request logic
        return customHttpClient.request(config);
      }
    };
  }
};

SSR Hydration

For server-side rendering, you can provide hydration data:

import type { AppHydration } from '@asterisms/sdk';

const hydration: AppHydration = {
  account: currentAccount,
  profile: accountProfile,
  workspace: currentWorkspace,
  workspaceProfile: workspaceProfile,
  authorization: authResponse,
  tenancy: tenancyConfig,
  publicSupportedFeatures: featuresMap,
  productCatalog: products,
  ecosystem: ecosystemConfig
};

const sdk = asterismsFactory({
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator,
  hydration
});

Environment-Specific Configuration

Development Environment

const developmentConfig = {
  bundleId: 'com.yourcompany.yourapp.dev',
  domain: 'dev.yourapp.com',
  navigator: devNavigationAdapter,
  loggerLevel: 'DEBUG' as const,
  devConfigServer: 'http://localhost:3001'
};

Production Environment

const productionConfig = {
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator: prodNavigationAdapter,
  loggerLevel: 'ERROR' as const,
  persistence: createPersistence() // localStorage
};

Custom Applications

Register custom applications with the SDK:

import type { AppRegistrations } from '@asterisms/sdk';

const registrations: AppRegistrations = {
  'com.yourcompany.customapp': {
    name: 'Custom App',
    url: 'https://custom.yourapp.com',
    builder: customAppBuilder
  }
};

const sdk = asterismsFactory({
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator,
  registrations
});

Resource Extensions

Extend SDK resources with custom functionality:

import type { AsterismsResourceExtensionBuilder } from '@asterisms/sdk';

const customExtension: AsterismsResourceExtensionBuilder = {
  bundleId: 'com.yourcompany.extension',
  build(sdk) {
    return {
      customMethod() {
        // Custom functionality
      }
    };
  }
};

const sdk = asterismsFactory({
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator,
  extenders: [customExtension]
});
## Configuration Best Practices ### 1. Environment Variables Use environment variables for sensitive configuration: ```typescript const config = { bundleId: process.env.BUNDLE_ID || 'com.yourcompany.yourapp', domain: process.env.ASTERISMS_DOMAIN || 'yourapp.com', loggerLevel: (process.env.LOG_LEVEL || 'INFO') as LoggerLevel, devConfigServer: process.env.DEV_CONFIG_SERVER };

2. Type Safety

Use TypeScript for configuration validation:

import type { AsterismsSDKInitProps } from '@asterisms/sdk';

const config: AsterismsSDKInitProps = {
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator: myNavigationAdapter,
  loggerLevel: 'INFO' // TypeScript will enforce valid values
};

3. Configuration Factory

Create a configuration factory for reusability:

import type { AsterismsSDKInitProps, NavigationAdapter } from '@asterisms/sdk';

export function createSDKConfig(
  bundleId: string,
  domain: string,
  navigator: NavigationAdapter,
  options: {
    loggerLevel?: LoggerLevel;
    devMode?: boolean;
  } = {}
): AsterismsSDKInitProps {
  return {
    bundleId,
    domain,
    navigator,
    loggerLevel: options.loggerLevel || 'INFO',
    devConfigServer: options.devMode ? 'http://localhost:3001' : undefined
  };
}

4. Validation

Validate configuration at runtime:

import { z } from 'zod';

const ConfigSchema = z.object({
  bundleId: z.string().min(1),
  domain: z.string().min(1),
  loggerLevel: z.enum(['DEBUG', 'INFO', 'WARN', 'ERROR']).optional()
});

function validateConfig(config: unknown) {
  return ConfigSchema.parse(config);
}

Troubleshooting Configuration

Common Issues

  1. Invalid Bundle ID: Ensure bundle ID follows reverse domain notation
  2. Missing Navigator: Navigation adapter is required for routing
  3. Invalid Domain: Domain must be a valid hostname
  4. Persistence Errors: Check if storage is available in your environment

Debug Configuration

Enable debug logging to troubleshoot configuration issues:

const sdk = asterismsFactory({
  bundleId: 'com.yourcompany.yourapp',
  domain: 'yourapp.com',
  navigator,
  loggerLevel: 'DEBUG'
});

Related Documentation

// Enable runtime configuration validation
const sdk = createAsterismsSDK({
  ...config,
  enableConfigValidation: true,
  validationMode: 'strict' // 'strict' | 'warn' | 'silent'
});

Configuration Best Practices

1. Environment-Specific Configs

// config/index.ts
import development from './development';
import staging from './staging';
import production from './production';

const configs = {
  development,
  staging,
  production
};

export default configs[process.env.NODE_ENV || 'development'];

2. Type-Safe Configuration

interface AppConfig {
  bundleId: string;
  rootDomain: string;
  navigationAdapter: NavigationAdapter;
  logLevel: LogLevel;
  features: {
    enableNewFeature: boolean;
    maxUploadSize: number;
  };
}

const config: AppConfig = {
  bundleId: 'com.yourcompany.yourapp',
  rootDomain: 'yourapp.com',
  navigationAdapter: myAdapter,
  logLevel: LogLevel.INFO,
  features: {
    enableNewFeature: true,
    maxUploadSize: 100 * 1024 * 1024
  }
};

3. Configuration Merging

import { merge } from 'lodash';

const baseConfig = {
  bundleId: 'com.yourcompany.yourapp',
  logLevel: LogLevel.INFO
};

const environmentConfig = {
  development: {
    logLevel: LogLevel.DEBUG,
    enableDevTools: true
  },
  production: {
    logLevel: LogLevel.ERROR,
    enableDevTools: false
  }
};

const finalConfig = merge(baseConfig, environmentConfig[process.env.NODE_ENV]);

Next Steps

  • Examples - See configuration examples in action
  • Testing - Test different configurations
  • Migration - Migrate from old configuration formats
  • API Reference - Detailed configuration API documentation
ON THIS PAGE