Best Practices

Follow these guidelines to create maintainable and user-friendly settings.

---

Naming Conventions

Use Descriptive IDs

IDs should be clear and avoid conflicts with other expansions.

// ✅ Good - Descriptive and namespaced
{ id: "my-expansion-api-key", label: "API Key" }
{ id: "my-expansion-enable-sync", label: "Enable Sync" }
{ id: "my-expansion-max-items", label: "Maximum Items" }

// ❌ Bad - Generic and prone to conflicts
{ id: "key", label: "API Key" }
{ id: "enabled", label: "Enable Sync" }
{ id: "max", label: "Maximum Items" }

Follow Naming Patterns

Be consistent across your extension.

// ✅ Good - Consistent pattern
"expansion-api-key"
"expansion-api-endpoint"
"expansion-api-timeout"

// ❌ Bad - Inconsistent
"expansionAPIKey"
"api_endpoint"
"timeout-expansion"

---

Default Values

Always Provide Defaults

Every setting should have a sensible default value.

// ✅ Good
{
  id: "max-items",
  label: "Maximum Items",
  type: "number",
  min: 1,
  max: 1000,
  default: 100 // Clear default
}

// ❌ Bad
{
  id: "max-items",
  label: "Maximum Items",
  type: "number",
  min: 1,
  max: 1000
  // No default - will be undefined
}

Choose Sensible Defaults

Defaults should work well for most users.

// ✅ Good - Safe defaults
{ id: "enable-feature", type: "checkbox", default: false } // Opt-in
{ id: "cache-size", type: "number", default: 100 } // Moderate size
{ id: "log-level", type: "dropdown", default: "info" } // Standard logging

// ❌ Bad - Risky defaults
{ id: "delete-all-data", type: "checkbox", default: true } // Dangerous!
{ id: "cache-size", type: "number", default: 99999 } // Too large

---

User Experience

Add Helpful Descriptions

Help users understand what each setting does.

// ✅ Good - Clear description
{
  id: "cache-duration",
  label: "Cache Duration (minutes)",
  type: "number",
  description: "How long to cache data. Lower values use more bandwidth but provide fresher data.",
  min: 1,
  max: 1440,
  default: 60
}

// ❌ Bad - No context
{
  id: "cache-duration",
  label: "Cache Duration",
  type: "number"
}

Use Appropriate Element Types

Choose the right element for the data type.

// ✅ Good
{ type: "checkbox" }      // For true/false
{ type: "dropdown" }      // For predefined options
{ type: "slider" }        // For numeric ranges with UI
{ type: "color" }         // For colors
{ type: "textarea" }      // For multi-line text
{ type: "number" }        // For numeric values

// ❌ Bad
{ type: "text" }          // For true/false
{ type: "text" }          // For colors
{ type: "text" }          // For large predefined lists

Add Validation

Prevent invalid input with constraints.

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

{
  id: "email",
  label: "Email",
  type: "text",
  pattern: "^[^@]+@[^@]+\\.[^@]+$",
  placeholder: "[e-mail]"
}

// ❌ Bad - No validation
{
  id: "port",
  label: "Port Number",
  type: "number" // Could be negative or > 65535
}

---

Organization

Use Categories

Group related settings under category headers.

// ✅ Good - Organized
api.nexomaker.postProjectSettingsTab({
  type: "category",
  title: "MY EXPANSION",
  id: "expansion-category",
  order: 50
});

api.nexomaker.postProjectSettingsTab({
  id: "expansion-general",
  title: "General",
  type: "settings",
  order: 51,
  elements: [/* general settings */]
});

api.nexomaker.postProjectSettingsTab({
  id: "expansion-advanced",
  title: "Advanced",
  type: "settings",
  order: 52,
  elements: [/* advanced settings */]
});

Use Separators

Add visual breaks between logical groups.

// ✅ Good
elements: [
  { id: "basic-setting-1", /* ... */ },
  { id: "basic-setting-2", /* ... */ },
  { type: "separator" }, // Visual break
  { id: "advanced-setting-1", /* ... */ },
  { id: "advanced-setting-2", /* ... */ }
]

Order Logically

Place most important/common settings first.

// ✅ Good - Common first, advanced last
elements: [
  { id: "enabled", label: "Enable Feature", type: "checkbox" },
  { id: "mode", label: "Mode", type: "dropdown" },
  { type: "separator" },
  { id: "debug-level", label: "Debug Level", type: "dropdown" },
  { id: "custom-config", label: "Custom Config", type: "textarea" }
]

---

Error Handling

Provide Fallback Values

Always handle missing or invalid settings.

// ✅ Good
function getConfig() {
  const settings = api.nexomaker.getAppSettings();
  return {
    apiKey: settings['api-key'] || '',
    maxItems: settings['max-items'] || 100,
    enabled: settings['enabled'] ?? true // Use ?? for booleans
  };
}

// ❌ Bad
function getConfig() {
  const settings = api.nexomaker.getAppSettings();
  return {
    apiKey: settings['api-key'], // Could be undefined
    maxItems: settings['max-items'], // Could be undefined
    enabled: settings['enabled'] // undefined vs false issue
  };
}

Handle Async Errors

Properly handle errors when reading project settings.

// ✅ Good
async function loadConfig(projectId) {
  try {
    const response = await api.nexomaker.yaml.read({
      projectID: projectId,
      yamlKey: 'configs'
    });
    
    if (!response.success) {
      console.error('Failed to load config:', response.message);
      return getDefaultConfig();
    }
    
    return response.data;
  } catch (error) {
    console.error('Error loading config:', error);
    return getDefaultConfig();
  }
}

// ❌ Bad
async function loadConfig(projectId) {
  const response = await api.nexomaker.yaml.read({
    projectID: projectId,
    yamlKey: 'configs'
  });
  
  return response.data; // No error handling!
}

---

Performance

Cache Settings

Don't read settings repeatedly in loops.

// ✅ Good - Read once
const settings = api.nexomaker.getAppSettings();
const apiKey = settings['api-key'];

for (let item of items) {
  processItem(item, apiKey);
}

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

Use Event Listeners

React to changes instead of polling.

// ✅ Good - Event-driven
let currentConfig = api.nexomaker.getAppSettings();

window.addEventListener('app-settings-changed', (event) => {
  currentConfig = event.detail.settings;
  updateFeatures(currentConfig);
});

// ❌ Bad - Polling
setInterval(() => {
  const newConfig = api.nexomaker.getAppSettings();
  // Check if changed...
}, 1000);

---

Security

Don't Expose Sensitive Data

Be careful with API keys and credentials.

// ✅ Good
{
  id: "api-key",
  label: "API Key",
  type: "text", // Will be displayed as text input
  description: "Your API key (keep this secret!)",
  placeholder: "Enter your API key..."
}

// Consider using password type for very sensitive data
// (Note: Still stored in localStorage as plain text)

// ❌ Bad
console.log('API Key:', settings['api-key']); // Logging sensitive data

Validate Input

Don't trust user input blindly.

// ✅ Good
function getPort(settings) {
  const port = parseInt(settings['port']) || 8080;
  return Math.max(1, Math.min(65535, port)); // Constrain to valid range
}

// ❌ Bad
function getPort(settings) {
  return settings['port']; // Could be anything!
}

---

Documentation

Add Placeholders

Show expected format in placeholders.

// ✅ Good
{
  id: "webhook-url",
  label: "Webhook URL",
  type: "text",
  placeholder: "https://example.com/webhook",
  description: "The URL where webhook events will be sent"
}

{
  id: "api-key",
  label: "API Key",
  type: "text",
  placeholder: "XXXX-XXXX-XXXX-XXXX"
}

Use Hints

Provide additional context with hints.

// ✅ Good
{
  id: "cache-size",
  label: "Cache Size (MB)",
  type: "number",
  min: 10,
  max: 1000,
  default: 100,
  hint: "Larger caches improve performance but use more memory"
}

Document Complex Settings

For advanced settings, provide clear explanations.

// ✅ Good
{
  id: "custom-config",
  label: "Custom Configuration",
  type: "textarea",
  description: "Advanced YAML configuration. Use with caution!",
  hint: "Example:\nkey: value\nlist:\n  - item1\n  - item2",
  placeholder: "Enter YAML configuration..."
}

---

Testing

Test Default Values

Ensure defaults work correctly.

// Test with no saved settings
const freshSettings = api.nexomaker.getAppSettings();
console.assert(freshSettings['max-items'] || 100 === 100, 'Default should be 100');

Test Edge Cases

Validate behavior with unusual inputs.

// Test with invalid values
const config = {
  port: -1,
  maxItems: 99999,
  apiKey: null
};

// Should handle gracefully
const validPort = Math.max(1, Math.min(65535, config.port || 8080));
const validMax = Math.max(1, Math.min(1000, config.maxItems || 100));
const validKey = config.apiKey || '';

---

Common Mistakes to Avoid

❌ Not Providing Defaults

// Wrong
const maxItems = settings['max-items'];
if (!maxItems) { // Will be true for 0!
  maxItems = 100;
}

// Right
const maxItems = settings['max-items'] ?? 100; // Use ?? for numbers

❌ Hardcoding Values

// Wrong
if (mode === 'advanced') {
  // Hardcoded behavior
}

// Right
const modes = settings['available-modes'] || ['simple', 'advanced'];
if (modes.includes(mode)) {
  // Configurable behavior
}

❌ Ignoring Types

// Wrong
const enabled = settings['enabled']; // Could be string "false"
if (enabled) { // "false" is truthy!
  // ...
}

// Right
const enabled = settings['enabled'] === true; // Explicit check

❌ Not Validating Input

// Wrong
const port = settings['port'];
server.listen(port); // Could crash!

// Right
const port = parseInt(settings['port']) || 8080;
if (port < 1 || port > 65535) {
  console.error('Invalid port:', port);
  port = 8080;
}
server.listen(port);

---

Quick Checklist

Before publishing your settings:

• All settings have descriptive IDs

• All settings have default values

• All settings have descriptions

• Appropriate element types are used

• Validation is added where needed

• Settings are organized with categories

• Fallback values are provided when reading

• Sensitive data is handled carefully

• Error handling is implemented

• Settings are documented

---

Next Steps

• See complete examples →

• Learn about custom elements →

• Read API methods reference →