Configuration System

Overview

EverShop uses a JSON-based configuration system with environment-specific overrides. Configuration files control extensions, themes, shop settings, and system behavior.

Configuration Files

File Hierarchy

config/
├── default.json          # Base configuration (always loaded)
├── development.json      # Dev overrides (NODE_ENV=development)
├── production.json       # Production overrides (NODE_ENV=production)
└── .env                  # Secrets (database, API keys)

Configuration files are merged in order: default.json → environment file → .env variables.

Configuration Structure

Base Configuration (config/default.json)

Here’s the actual configuration from the project:

config/default.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "extensions": [
      {
        "name": "offlinePayments",
        "resolve": "extensions/offlinePayments",
        "enabled": true
      },
      {
        "name": "productCatalog",
        "resolve": "extensions/productCatalog",
        "enabled": true
      },
      {
        "name": "productReviews",
        "resolve": "extensions/productReviews",
        "enabled": true
      }
    ],
    "theme": "anasuplements"
  }
}

Configuration Sections

shop

object

Store-level settingsProperties:

language - Default store language (ISO 639-1 code)
currency - Currency code (ISO 4217)

system

object

System-level settingsProperties:

extensions - Array of extension configurations
theme - Active theme name

Development Configuration

config/development.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}

Development config typically includes:

Debug flags
Local database connections
Development-only extensions
Verbose logging

Production Configuration

config/production.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}

Production config should:

Use environment variables for secrets
Enable caching
Disable debug logging
Use production database

Extension Configuration

Extension Object Structure

{
  "name": "extensionName",        // Unique identifier
  "resolve": "path/to/extension", // Relative path from root
  "enabled": true                  // Enable/disable flag
}

Real Examples

{
  "name": "productCatalog",
  "resolve": "extensions/productCatalog",
  "enabled": true
}

Adding New Extensions

To register a new extension:

Create Extension Directory

mkdir -p extensions/myExtension/src

Update config/default.json

{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      },
      // ... other extensions
    ]
  }
}

Restart Development Server

npm run dev

Extensions are loaded in the order they appear in the configuration array.

Theme Configuration

Setting Active Theme

config/default.json

{
  "system": {
    "theme": "anasuplements"
  }
}

This tells EverShop to load components from themes/anasuplements/.

Switching Themes

// config/development.json
{
  "system": {
    "theme": "anasuplements"
  }
}

Changing themes requires a rebuild:

npm run build

Shop Configuration

Language Settings

{
  "shop": {
    "language": "es"
  }
}

This sets Spanish as the default language. Translation files should exist at:

translations/
└── es/
    ├── common.json
    └── products.json

Currency Settings

{
  "shop": {
    "currency": "USD"
  }
}

Supported currencies:

USD - US Dollar
EUR - Euro
GBP - British Pound
CAD - Canadian Dollar
And more…

Environment Variables

.env File

Sensitive configuration goes in .env (never commit this file):

.env

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=evershop
DB_USER=postgres
DB_PASSWORD=secretpassword

# Session
SESSION_SECRET=your-secret-key-here

# Admin
ADMIN_USER=admin@example.com
ADMIN_PASSWORD=adminpassword

# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# Payment Gateways
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

# Storage
S3_BUCKET=my-bucket
S3_ACCESS_KEY=AKIA...
S3_SECRET_KEY=...

Always add .env to .gitignore:

# .gitignore
.env
.env.local
.env.*.local

Accessing Environment Variables

// In your extension code
const dbHost = process.env.DB_HOST;
const dbPassword = process.env.DB_PASSWORD;

Advanced Configuration

Conditional Extension Loading

You can enable/disable extensions per environment:

{
  "system": {
    "extensions": [
      {
        "name": "devTools",
        "resolve": "extensions/devTools",
        "enabled": true  // Only in development
      }
    ]
  }
}

Extension-Specific Configuration

Extensions can read custom config:

config/default.json

{
  "system": {
    "extensions": [
      {
        "name": "emailNotifications",
        "resolve": "extensions/emailNotifications",
        "enabled": true,
        "config": {
          "sender": "noreply@example.com",
          "templates": "templates/email"
        }
      }
    ]
  }
}

extensions/emailNotifications/src/bootstrap.ts

import config from 'config';

export default function () {
  const extensions = config.get('system.extensions');
  const emailConfig = extensions.find(e => e.name === 'emailNotifications');
  
  console.log('Email sender:', emailConfig.config.sender);
}

Configuration Best Practices

1. Never Hardcode Secrets

❌ Bad:

{
  "database": {
    "password": "mypassword123"
  }
}

✅ Good:

# .env
DB_PASSWORD=mypassword123

2. Use Environment-Specific Overrides

Keep default.json minimal and override in environment files:

config/default.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  }
}

config/production.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "cache": {
    "enabled": true
  }
}

3. Document Extension Dependencies

If extensions depend on each other, document the required load order:

{
  "system": {
    "extensions": [
      // Must load first (provides base types)
      { "name": "productCatalog", "resolve": "extensions/productCatalog", "enabled": true },
      // Depends on productCatalog
      { "name": "productReviews", "resolve": "extensions/productReviews", "enabled": true }
    ]
  }
}

4. Version Control Strategy

# Commit to Git
config/default.json         ✅
config/development.json     ✅
config/production.json      ✅

# Do NOT commit
.env                        ❌
.env.local                  ❌

# Provide template
.env.example                ✅

Troubleshooting

Extension Not Loading

Check Configuration

Verify extension is registered in config/default.json:

{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      }
    ]
  }
}

Verify Path

Ensure the resolve path is correct:

ls extensions/myExtension/src/

Check Enabled Flag

Make sure "enabled": true

Rebuild

npm run build
npm run start

Theme Not Applying

Check Theme Name

{
  "system": {
    "theme": "anasuplements"  // Must match directory name
  }
}

Verify Theme Directory

ls themes/anasuplements/src/

Rebuild Theme

npm run build

Configuration Not Merging

Config files merge using deep merge:

// default.json
{ "shop": { "language": "es", "currency": "USD" } }

// production.json
{ "shop": { "currency": "EUR" } }

// Result in production:
{ "shop": { "language": "es", "currency": "EUR" } }

Configuration API

Reading Configuration in Code

import config from 'config';

// Get shop language
const language = config.get('shop.language'); // "es"

// Get all extensions
const extensions = config.get('system.extensions');

// Get theme
const theme = config.get('system.theme'); // "anasuplements"

// Check if value exists
if (config.has('shop.currency')) {
  console.log('Currency:', config.get('shop.currency'));
}

Setting Configuration Programmatically

import config from 'config';

// Only for runtime changes (not persisted)
config.util.setModuleDefaults('myModule', {
  setting1: 'value1',
  setting2: 'value2'
});

Programmatic changes are not persisted to disk. They only exist during the current process.

Example Configurations

Minimal Setup

config/default.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}

Full Production Setup

config/production.json

{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "extensions": [
      { "name": "productCatalog", "resolve": "extensions/productCatalog", "enabled": true },
      { "name": "productReviews", "resolve": "extensions/productReviews", "enabled": true },
      { "name": "offlinePayments", "resolve": "extensions/offlinePayments", "enabled": true },
      { "name": "emailNotifications", "resolve": "extensions/emailNotifications", "enabled": true },
      { "name": "analytics", "resolve": "extensions/analytics", "enabled": true }
    ],
    "theme": "anasuplements"
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  },
  "logging": {
    "level": "error"
  }
}

Overview

Configuration Files

File Hierarchy

Configuration Structure

Base Configuration (config/default.json)

Development Configuration

Production Configuration

Extension Configuration

Extension Object Structure

Real Examples

Adding New Extensions

Theme Configuration

Setting Active Theme

Switching Themes

Shop Configuration

Language Settings

Currency Settings

Environment Variables

.env File

Accessing Environment Variables

Advanced Configuration

Conditional Extension Loading

Extension-Specific Configuration

Configuration Best Practices

Troubleshooting

Extension Not Loading

Theme Not Applying

Configuration Not Merging

Configuration API

Reading Configuration in Code

Setting Configuration Programmatically

Example Configurations

Minimal Setup

Full Production Setup

Next Steps

System Architecture

Create Extension

​Overview

​Configuration Files

​File Hierarchy

​Configuration Structure

​Base Configuration (config/default.json)

​Development Configuration

​Production Configuration

​Extension Configuration

​Extension Object Structure

​Real Examples

​Adding New Extensions

​Theme Configuration

​Setting Active Theme

​Switching Themes

​Shop Configuration

​Language Settings

​Currency Settings

​Environment Variables

​.env File

​Accessing Environment Variables

​Advanced Configuration

​Conditional Extension Loading

​Extension-Specific Configuration

​Configuration Best Practices

​Troubleshooting

​Extension Not Loading

​Theme Not Applying

​Configuration Not Merging

​Configuration API

​Reading Configuration in Code

​Setting Configuration Programmatically

​Example Configurations

​Minimal Setup

​Full Production Setup

​Next Steps

System Architecture

Create Extension

Overview

Configuration Files

File Hierarchy

Configuration Structure

Base Configuration (config/default.json)

Development Configuration

Production Configuration

Extension Configuration

Extension Object Structure

Real Examples

Adding New Extensions

Theme Configuration

Setting Active Theme

Switching Themes

Shop Configuration

Language Settings

Currency Settings

Environment Variables

.env File

Accessing Environment Variables

Advanced Configuration

Conditional Extension Loading

Extension-Specific Configuration

Configuration Best Practices

Troubleshooting

Extension Not Loading

Theme Not Applying

Configuration Not Merging

Configuration API

Reading Configuration in Code

Setting Configuration Programmatically

Example Configurations

Minimal Setup

Full Production Setup

Next Steps