Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Antony-Figueroa/my-evershop-app/llms.txt

Use this file to discover all available pages before exploring further.

​
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"
  }
}
​
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:
1

Create Extension Directory

mkdir -p extensions/myExtension/src
2

Update config/default.json

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

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

❌ Bad:
{
  "database": {
    "password": "mypassword123"
  }
}
✅ Good:
# .env
DB_PASSWORD=mypassword123
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
  }
}
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 }
    ]
  }
}

# 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

1

Check Configuration

Verify extension is registered in config/default.json:
{
  "system": {
    "extensions": [
      {
        "name": "myExtension",
        "resolve": "extensions/myExtension",
        "enabled": true
      }
    ]
  }
}
2

Verify Path

Ensure the resolve path is correct:
ls extensions/myExtension/src/
3

Check Enabled Flag

Make sure "enabled": true
4

Rebuild

npm run build
npm run start

​
Theme Not Applying

1

Check Theme Name

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

Verify Theme Directory

ls themes/anasuplements/src/
3

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"
  }
}

​
Next Steps

System Architecture

Learn how extensions and themes work together

Create Extension

Build your first extension

Build docs developers (and LLMs) love

Get started for freeTalk to us