App Settings

App Settings are application-wide settings that apply globally across all projects. They are stored in localStorage under the key app-settings.

---

Overview

Storage Location

• Storage: localStorage['app-settings']

• Format: JSON object with key-value pairs

• Persistence: Persists across sessions

• Scope: Global to the application

---

When to Use App Settings

✅ Use App Settings for:

• API keys and credentials

• Global preferences (theme, language, etc.)

• Application behavior settings

• License keys

• Update preferences

• User-wide configurations

❌ Don't Use App Settings for:

• Project-specific configuration

• Per-project data

• Temporary state

• Session-specific data

---

Creating App Settings

Basic Example

api.nexomaker.postAppSettingsTab({
  id: "my-expansion",
  title: "My Expansion",
  description: "Global settings for My Expansion",
  order: 100,
  elements: [
    {
      id: "api-key",
      label: "API Key",
      type: "text",
      placeholder: "Enter your API key",
      default: "",
      required: true
    },
    {
      id: "enabled",
      label: "Enable Feature",
      type: "checkbox",
      default: true
    }
  ]
});

Complete Example

api.nexomaker.postAppSettingsTab({
  id: "expansion-global",
  expansionId: "my_expansion",
  title: "My Expansion",
  description: "Global expansion settings",
  order: 100,
  elements: [
    {
      id: "api-key",
      label: "API Key",
      type: "text",
      placeholder: "XXXX-XXXX-XXXX-XXXX",
      description: "Your API key for external services",
      default: "",
      required: true
    },
    {
      id: "auto-update",
      label: "Automatic Updates",
      type: "checkbox",
      description: "Automatically check for updates",
      default: true
    },
    {
      id: "update-channel",
      label: "Update Channel",
      type: "dropdown",
      options: [
        { value: "stable", label: "Stable" },
        { value: "beta", label: "Beta" },
        { value: "dev", label: "Development" }
      ],
      default: "stable"
    },
    {
      id: "cache-size",
      label: "Cache Size (MB)",
      type: "number",
      min: 10,
      max: 1000,
      default: 100
    }
  ]
});

---

Reading App Settings

Method 1: Using API

const settings = api.nexomaker.getAppSettings();
const apiKey = settings['api-key'];
const autoUpdate = settings['auto-update'];

Method 2: Direct localStorage Access

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:

window.addEventListener('app-settings-changed', (event) => {
  const { settings } = event.detail;
  console.log('Settings updated:', settings);
  
  // React to changes
  if (settings['auto-update']) {
    checkForUpdates();
  }
});

---

Best Practices

1. Always Provide Defaults

// ✅ Good
const apiKey = settings['api-key'] || '';
const cacheSize = settings['cache-size'] || 100;

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

2. Use Descriptive IDs

// ✅ Good
{ id: "expansion-api-key" }
{ id: "expansion-enable-sync" }

// ❌ Bad
{ id: "key" }
{ id: "enabled" }

3. Add Helpful Descriptions

{
  id: "cache-duration",
  label: "Cache Duration",
  type: "number",
  description: "How long to cache data in minutes. Lower values use more bandwidth.",
  default: 60
}

4. Validate Inputs

{
  id: "port",
  label: "Port Number",
  type: "number",
  min: 1,
  max: 65535,
  default: 8080,
  description: "Port must be between 1 and 65535"
}

---

Common Patterns

API Configuration

elements: [
  {
    id: "api-endpoint",
    label: "API Endpoint",
    type: "text",
    placeholder: "https://api.example.com",
    default: "https://api.example.com"
  },
  {
    id: "api-key",
    label: "API Key",
    type: "text",
    placeholder: "Your API key",
    required: true
  },
  {
    id: "api-timeout",
    label: "Request Timeout (seconds)",
    type: "number",
    min: 1,
    max: 60,
    default: 10
  }
]

User Preferences

elements: [
  {
    id: "theme",
    label: "Theme",
    type: "dropdown",
    options: [
      { value: "auto", label: "Auto (System)" },
      { value: "light", label: "Light" },
      { value: "dark", label: "Dark" }
    ],
    default: "auto"
  },
  {
    id: "language",
    label: "Language",
    type: "dropdown",
    options: [
      { value: "en", label: "English" },
      { value: "es", label: "Spanish" },
      { value: "fr", label: "French" }
    ],
    default: "en"
  }
]

Feature Toggles

elements: [
  {
    id: "enable-analytics",
    label: "Enable Analytics",
    type: "checkbox",
    description: "Send anonymous usage data to help improve the app",
    default: true
  },
  {
    id: "enable-beta-features",
    label: "Enable Beta Features",
    type: "checkbox",
    description: "Access experimental features (may be unstable)",
    default: false
  }
]

---

Troubleshooting

Settings Not Persisting

Problem: Settings reset when app restarts.

Solutions:

1. Check that localStorage is accessible

2. Verify browser doesn't clear localStorage on exit

3. Check for errors in browser console

4. Ensure element IDs match when reading

Settings Not Updating

Problem: Changes don't reflect immediately.

Solutions:

1. Use the app-settings-changed event listener

2. Check that you're reading the latest settings

3. Verify the correct key is being used

---

Next Steps

• Learn about Element Types →

• See complete examples →

• Read about best practices →