Reading Settings

Learn how to access and use settings values in your expansions.

---

App Settings

App settings are stored in localStorage and accessible globally.

Method 1: Using API

Recommended method - Simple and consistent.

const settings = api.nexomaker.getAppSettings();
const apiKey = settings['api-key'] || '';
const enabled = settings['enable-feature'] || false;

Method 2: Direct localStorage

Direct access to localStorage for advanced use cases.

const settingsJson = localStorage.getItem('app-settings');
const settings = JSON.parse(settingsJson || '{}');
const apiKey = settings['api-key'] || '';

Method 3: Event Listener

Listen for real-time changes to react immediately.

window.addEventListener('app-settings-changed', (event) => {
  const { settings } = event.detail;
  console.log('Settings updated:', settings);
  
  // React to specific changes
  if (settings['enable-auto-sync']) {
    startAutoSync(settings['sync-interval']);
  } else {
    stopAutoSync();
  }
});

---

Project Settings

Project settings are stored in YAML files and specific to each project.

Reading from YAML

async function getProjectSettings(projectId) {
  try {
    const response = await api.nexomaker.yaml.read({
      projectID: projectId,
      yamlKey: 'configs' // or 'environment', 'serverProperties'
    });
    
    if (response.success) {
      return response.data;
    }
  } catch (error) {
    console.error('Failed to read project settings:', error);
  }
  
  return null;
}

// Usage
const config = await getProjectSettings(currentProject.id);
const expansionMode = config['expansion-mode'] || 'normal';
const maxItems = config['max-custom-items'] || 100;

Reading from Different YAML Keys

// Read from configs
const configs = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'configs'
});

// Read from environment
const env = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'environment'
});

// Read from serverProperties
const serverProps = await api.nexomaker.yaml.read({
  projectID: projectId,
  yamlKey: 'serverProperties'
});

---

Best Practices

1. Always Provide Fallback Values

Settings might not exist yet, so always provide defaults.

// ✅ Good
const apiKey = settings['api-key'] || '';
const maxItems = settings['max-items'] || 100;
const enabled = settings['enabled'] ?? true; // Use ?? for boolean defaults

// ❌ Bad
const apiKey = settings['api-key']; // Could be undefined

2. Use Consistent Key Names

Keep key naming consistent between registration and reading.

// Registration
{
  id: "api-key",
  label: "API Key",
  type: "text"
}

// Reading
const apiKey = settings['api-key']; // ✅ Matches
const apiKey = settings['apiKey'];  // ❌ Different key

3. Handle Async Operations

Project settings are async, so use async/await or promises.

// ✅ Good
async function init() {
  const config = await getProjectSettings(projectId);
  if (config) {
    useConfig(config);
  }
}

// ❌ Bad
function init() {
  const config = getProjectSettings(projectId); // Returns Promise, not config!
  useConfig(config); // Won't work
}

4. Cache Settings When Appropriate

Avoid reading settings repeatedly in loops.

// ✅ Good
const settings = api.nexomaker.getAppSettings();
for (let item of items) {
  processItem(item, settings['api-key']);
}

// ❌ Bad
for (let item of items) {
  const settings = api.nexomaker.getAppSettings(); // Reading every iteration!
  processItem(item, settings['api-key']);
}

5. Listen for Changes

React to settings changes in real-time.

window.addEventListener('app-settings-changed', (event) => {
  const { settings } = event.detail;
  
  // Update your expansion configuration
  updateConfig(settings);
});

---

Common Patterns

Initialize on Load

(function initExpansion(api) {
  // Read settings on load
  const appSettings = api.nexomaker.getAppSettings();
  
  if (!appSettings['expansion-enabled']) {
    console.log('Expansion is disabled');
    return;
  }
  
  // Initialize with settings
  initWithConfig({
    apiKey: appSettings['api-key'],
    debug: appSettings['debug-mode']
  });
  
  // Listen for changes
  window.addEventListener('app-settings-changed', (event) => {
    updateConfig(event.detail.settings);
  });
})(api);

Project-Specific Logic

async function setupProject(project) {
  const config = await api.nexomaker.yaml.read({
    projectID: project.id,
    yamlKey: 'configs'
  });
  
  if (!config.success) {
    console.error('Failed to load project config');
    return;
  }
  
  // Use project-specific settings
  if (config.data['expansion-enabled']) {
    const mode = config.data['expansion-mode'] || 'normal';
    setupExpansion(project, mode);
  }
}

Combining App and Project Settings

async function getFullConfig(projectId) {
  // Get global app settings
  const appSettings = api.nexomaker.getAppSettings();
  
  // Get project-specific settings
  const projectResponse = await api.nexomaker.yaml.read({
    projectID: projectId,
    yamlKey: 'configs'
  });
  
  // Combine them
  return {
    // Global settings
    apiKey: appSettings['api-key'],
    debugMode: appSettings['debug-mode'],
    
    // Project settings
    enabled: projectResponse.data?.['expansion-enabled'] ?? true,
    mode: projectResponse.data?.['expansion-mode'] || 'normal',
    maxItems: projectResponse.data?.['max-items'] || 100
  };
}

// Usage
const config = await getFullConfig(currentProject.id);
if (config.enabled) {
  initExpansion(config);
}

Conditional Feature Activation

function checkFeatureAvailability() {
  const settings = api.nexomaker.getAppSettings();
  
  return {
    premium: settings['license-key'] !== '',
    beta: settings['enable-beta-features'] === true,
    analytics: settings['enable-analytics'] === true
  };
}

// Usage
const features = checkFeatureAvailability();
if (features.premium) {
  enablePremiumFeatures();
}
if (features.beta) {
  loadBetaFeatures();
}

---

Examples

Simple App Settings

// Register settings
api.nexomaker.postAppSettingsTab({
  id: "my-settings",
  title: "My Extension",
  elements: [
    { id: "api-key", label: "API Key", type: "text", default: "" },
    { id: "enabled", label: "Enabled", type: "checkbox", default: true }
  ]
});

// Read settings
function getConfig() {
  const settings = api.nexomaker.getAppSettings();
  return {
    apiKey: settings['api-key'] || '',
    enabled: settings['enabled'] ?? true
  };
}

// Use settings
const config = getConfig();
if (config.enabled && config.apiKey) {
  connectToAPI(config.apiKey);
}

Project Settings with Validation

async function loadProjectConfig(projectId) {
  const response = await api.nexomaker.yaml.read({
    projectID: projectId,
    yamlKey: 'configs'
  });
  
  if (!response.success) {
    console.error('Failed to load config');
    return null;
  }
  
  const config = response.data;
  
  // Validate and provide defaults
  return {
    enabled: config['enabled'] ?? true,
    mode: ['simple', 'advanced'].includes(config['mode']) 
      ? config['mode'] 
      : 'simple',
    maxItems: Math.min(Math.max(config['max-items'] || 100, 1), 1000)
  };
}

---

Troubleshooting

Settings Return Undefined

Problem: Reading settings returns undefined.

Solutions:

1. Check that settings tab is registered first

2. Verify key names match exactly

3. Provide fallback values: settings['key'] || 'default'

Changes Don't Reflect

Problem: Updated settings don't show.

Solutions:

1. For app settings: Check if using event listener

2. For project settings: Re-read YAML after changes

3. Clear cache if caching settings

Async Issues

Problem: Project settings return promises.

Solutions:

1. Use async/await

2. Add .then() handlers

3. Don't use project settings in synchronous code

---

Next Steps

• Learn about best practices →

• See complete examples →

• Create custom elements →