Configuration

Complete guide to SDK configuration options for different environments and use cases.

Basic Configuration

Minimum Required Config

import { AetherSDK } from '@aether-official/sites-sdk';

const sdk = new AetherSDK({
  siteId: 'your-site-id',
  organizationId: 'your-org-id',
  editorOrigin: 'https://app.aether.com',
});

Recommended Config

const sdk = new AetherSDK({
  siteId: process.env.PUBLIC_AETHER_SITE_ID,
  organizationId: process.env.PUBLIC_AETHER_ORG_ID,
  editorOrigin: process.env.PUBLIC_AETHER_EDITOR_URL,
  debug: process.env.NODE_ENV === 'development',
  autoInit: true,
});

Configuration Options

siteId (required)

Your site’s unique identifier from Aether.

Type: string Example: 'clqx1234abcd5678efgh'

Where to find:

1. Navigate to Sites in Aether
2. Click your site
3. Copy the Site ID from settings

organizationId (required)

Your organization’s unique identifier.

Type: string Example: 'org_abc123xyz789'

Where to find:

1. Open your organization settings
2. Copy the Organization ID

editorOrigin (required)

The origin URL of the Aether editor for postMessage security.

Type: string Default: None Example: 'https://app.aether.com'

Common values:

• Production: 'https://app.aether.com'
• Staging: 'https://staging.aether.com'
• Local development: 'http://localhost:3000'

Security

This must match exactly the origin where your visual editor runs. Invalid origins will be rejected for security.

debug (optional)

Enable verbose console logging.

Type: boolean Default: false Example: true

When to use:

• Development: Enable to see SDK lifecycle events
• Production: Disable to reduce console noise

debug: process.env.NODE_ENV === 'development'

editableSelector (optional)

Custom CSS selector for editable elements.

Type: string Default: '[data-aether-field]' Example: '[data-edit]'

When to use:

• Custom attribute names
• Avoiding conflicts with other libraries

editableSelector: '[data-cms-field]'

autoInit (optional)

Automatically initialize SDK on construction.

Type: boolean Default: true Example: false

When to set false:

• Manual initialization control
• Conditional initialization

const sdk = new AetherSDK({
  ...config,
  autoInit: false,
});

// Later, when ready
await sdk.initialize();

Environment-Specific Configs

Development

.env.development

PUBLIC_AETHER_SITE_ID=test-site-dev
PUBLIC_AETHER_ORG_ID=test-org-dev
PUBLIC_AETHER_EDITOR_URL=http://localhost:3000
AETHER_API_URL=http://localhost:3000/api/trpc

const sdk = new AetherSDK({
  siteId: import.meta.env.PUBLIC_AETHER_SITE_ID,
  organizationId: import.meta.env.PUBLIC_AETHER_ORG_ID,
  editorOrigin: import.meta.env.PUBLIC_AETHER_EDITOR_URL,
  debug: true, // Always true in development
});

Staging

.env.staging

PUBLIC_AETHER_SITE_ID=staging-site-id
PUBLIC_AETHER_ORG_ID=staging-org-id
PUBLIC_AETHER_EDITOR_URL=https://staging.aether.com
AETHER_API_URL=https://staging.aether.com/api/trpc

Production

.env.production

PUBLIC_AETHER_SITE_ID=prod-site-id
PUBLIC_AETHER_ORG_ID=prod-org-id
PUBLIC_AETHER_EDITOR_URL=https://app.aether.com
AETHER_API_URL=https://app.aether.com/api/trpc
AETHER_API_TOKEN=aether_prod_token_xxxxx

const sdk = new AetherSDK({
  siteId: import.meta.env.PUBLIC_AETHER_SITE_ID,
  organizationId: import.meta.env.PUBLIC_AETHER_ORG_ID,
  editorOrigin: import.meta.env.PUBLIC_AETHER_EDITOR_URL,
  debug: false, // Never true in production
});

Content Fetching Config

Server-Side Config

import { fetchSection } from '@aether-official/sites-sdk';

const config = {
  apiUrl: process.env.AETHER_API_URL,
  apiToken: process.env.AETHER_API_TOKEN,
};

const section = await fetchSection('hero-123', config);

Client-Side Config with Caching

import { createContentManager } from '@aether-official/sites-sdk';

const content = createContentManager({
  apiUrl: 'https://app.aether.com/api/trpc',
  apiToken: process.env.AETHER_API_TOKEN,

  // Cache configuration
  cacheTTL: 5 * 60 * 1000, // 5 minutes
  cacheEnabled: true,

  // Debug
  debug: false,
});

Astro Build-Time Config

---
import { getConfig } from '@aether-official/sites-sdk/astro';

// Auto-extracts from environment
const config = getConfig(import.meta.env);

// Manual config
const manualConfig = {
  apiUrl: import.meta.env.AETHER_API_URL,
  apiToken: import.meta.env.AETHER_API_TOKEN,
  siteId: import.meta.env.PUBLIC_AETHER_SITE_ID,
  organizationId: import.meta.env.PUBLIC_AETHER_ORG_ID,
};
---

Framework-Specific Configs

Astro Integration Config

The Astro integration accepts additional configuration options:

astro.config.mjs

import { defineConfig } from 'astro/config';
import aetherSites from '@aether-official/sites-sdk/astro';

export default defineConfig({
  integrations: [
    aetherSites({
      // Required
      siteId: process.env.PUBLIC_AETHER_SITE_ID || process.env.AETHER_SITE_ID,
      organizationId: process.env.PUBLIC_AETHER_ORGANIZATION_ID || process.env.AETHER_ORGANIZATION_ID,
      editorOrigin: process.env.PUBLIC_AETHER_EDITOR_ORIGIN || 'http://localhost:3000',

      // Optional
      enabled: process.env.PUBLIC_AETHER_EDITOR_ENABLED === 'true' || true,
      debug: process.env.NODE_ENV === 'development',
      autoMiddleware: true,
    })
  ],
});

enabled (optional)

Enable or disable the SDK integration entirely.

Type: boolean Default: true Example: process.env.PUBLIC_AETHER_EDITOR_ENABLED === 'true'

When to use:

• Conditionally enable SDK based on environment
• Disable for production builds if not needed
• Feature flag for gradual rollout

// Only enable in development and staging
enabled: process.env.NODE_ENV !== 'production'

// Enable via environment variable
enabled: process.env.PUBLIC_AETHER_EDITOR_ENABLED === 'true'

autoMiddleware (optional)

Automatically inject middleware for CSP headers and visual editor support.

Type: boolean Default: true Example: true

When to set false:

• Custom middleware configuration needed
• Manual control over middleware order
• Using custom CSP headers

// Disable auto-middleware for custom setup
autoMiddleware: false

If disabled, manually create src/middleware.ts:

import { onRequest as aetherMiddleware } from '@aether-official/sites-sdk/middleware';

export const onRequest = aetherMiddleware;

debug (optional)

Enable verbose SDK logging.

Type: boolean Default: false Example: process.env.NODE_ENV === 'development'

Recommended pattern:

// Auto-enable in development
debug: process.env.NODE_ENV === 'development'

Complete Astro Example

astro.config.mjs

import { defineConfig } from 'astro/config';
import aetherSites from '@aether-official/sites-sdk/astro';

export default defineConfig({
  integrations: [
    aetherSites({
      // Required - fallback from both public and private env vars
      siteId: process.env.PUBLIC_AETHER_SITE_ID || process.env.AETHER_SITE_ID,
      organizationId:
        process.env.PUBLIC_AETHER_ORGANIZATION_ID ||
        process.env.AETHER_ORGANIZATION_ID,
      editorOrigin: process.env.PUBLIC_AETHER_EDITOR_ORIGIN || 'http://localhost:3000',

      // Optional - enable based on environment variable or default to true
      enabled: process.env.PUBLIC_AETHER_EDITOR_ENABLED === 'true' || true,

      // Optional - debug in development only
      debug: process.env.NODE_ENV === 'development',

      // Optional - auto-inject middleware (recommended)
      autoMiddleware: true,
    })
  ],

  vite: {
    define: {
      'import.meta.env.PUBLIC_AETHER_SITE_ID': JSON.stringify(
        process.env.PUBLIC_AETHER_SITE_ID
      ),
    },
  },
});

Next.js

next.config.js

module.exports = {
  env: {
    NEXT_PUBLIC_AETHER_SITE_ID: process.env.NEXT_PUBLIC_AETHER_SITE_ID,
    NEXT_PUBLIC_AETHER_ORG_ID: process.env.NEXT_PUBLIC_AETHER_ORG_ID,
    NEXT_PUBLIC_AETHER_EDITOR_URL: process.env.NEXT_PUBLIC_AETHER_EDITOR_URL,
  },
};

Vite

vite.config.js

export default {
  define: {
    'import.meta.env.PUBLIC_AETHER_SITE_ID': JSON.stringify(
      process.env.PUBLIC_AETHER_SITE_ID
    ),
  },
};

Security Best Practices

Environment Variables

# ✅ Good - Separate public and private
PUBLIC_AETHER_SITE_ID=site-123      # Exposed to browser
AETHER_API_TOKEN=aether_secret_xxx  # Server-only

# ❌ Bad - Exposing secrets
PUBLIC_AETHER_API_TOKEN=xxx  # Never make tokens public!

Token Management

// ✅ Server-side only
const serverConfig = {
  apiUrl: process.env.AETHER_API_URL,
  apiToken: process.env.AETHER_API_TOKEN, // Not exposed to browser
};

// ❌ Never in client-side code
const clientConfig = {
  apiToken: 'aether_token_xxx', // Exposed in browser!
};

Origin Validation

// ✅ Strict origin matching
editorOrigin: 'https://app.aether.com'

// ❌ Wildcards or multiple origins not supported
editorOrigin: '*' // Not allowed

Troubleshooting

”SDK not initializing”

Cause: Missing or incorrect configuration

Solution:

// Check all required fields are present
const sdk = new AetherSDK({
  siteId: process.env.PUBLIC_AETHER_SITE_ID,      // ✅ Required
  organizationId: process.env.PUBLIC_AETHER_ORG_ID, // ✅ Required
  editorOrigin: process.env.PUBLIC_AETHER_EDITOR_URL, // ✅ Required
  debug: true, // Enable logging to see errors
});

“PostMessage origin mismatch”

Cause: editorOrigin doesn’t match actual editor URL

Solution:

// Must match exactly (including protocol and port)
editorOrigin: 'https://app.aether.com'  // Not http or www

“API token invalid”

Cause: Token not set or expired

Solution:

1. Regenerate token in Aether dashboard
2. Update environment variable
3. Restart development server

Validation

Config Validator

import { AetherSDK } from '@aether-official/sites-sdk';

function validateConfig(config: any): boolean {
  const required = ['siteId', 'organizationId', 'editorOrigin'];

  for (const field of required) {
    if (!config[field]) {
      console.error(`Missing required field: ${field}`);
      return false;
    }
  }

  // Validate editorOrigin format
  try {
    new URL(config.editorOrigin);
  } catch {
    console.error('Invalid editorOrigin URL');
    return false;
  }

  return true;
}

const config = {
  siteId: process.env.PUBLIC_AETHER_SITE_ID,
  organizationId: process.env.PUBLIC_AETHER_ORG_ID,
  editorOrigin: process.env.PUBLIC_AETHER_EDITOR_URL,
};

if (validateConfig(config)) {
  const sdk = new AetherSDK(config);
}

Advanced Configuration

Custom Event Handlers

const sdk = new AetherSDK(config);

// Custom ready handler
sdk.on('ready', () => {
  console.log('SDK ready - custom initialization');
  // Custom setup logic
});

// Error handler
sdk.on('error', (error) => {
  // Send to error tracking service
  console.error('SDK Error:', error);
});

Conditional Initialization

// Only initialize in editor mode
const params = new URLSearchParams(window.location.search);
const isEditorMode = params.get('aether-editor') === 'true';

if (isEditorMode) {
  const sdk = new AetherSDK({
    siteId: import.meta.env.PUBLIC_AETHER_SITE_ID,
    organizationId: import.meta.env.PUBLIC_AETHER_ORG_ID,
    editorOrigin: import.meta.env.PUBLIC_AETHER_EDITOR_URL,
  });
}

Next Steps

• Content Fetching - Fetch content from Aether
• Visual Editor - Enable inline editing
• Astro Integration - Complete Astro guide