> ## 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.

# Configuration System

> Understanding EverShop configuration files, environment management, and extension registration

## 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)
```

<Note>
  Configuration files are **merged** in order: `default.json` → environment file → `.env` variables.
</Note>

## Configuration Structure

### Base Configuration (config/default.json)

Here's the actual configuration from the project:

```json config/default.json theme={null}
{
  "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"
  }
}
```

<Accordion title="Configuration Sections">
  <ResponseField name="shop" type="object">
    Store-level settings

    **Properties**:

    * `language` - Default store language (ISO 639-1 code)
    * `currency` - Currency code (ISO 4217)
  </ResponseField>

  <ResponseField name="system" type="object">
    System-level settings

    **Properties**:

    * `extensions` - Array of extension configurations
    * `theme` - Active theme name
  </ResponseField>
</Accordion>

### Development Configuration

```json config/development.json theme={null}
{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}
```

<Note>
  Development config typically includes:

  * Debug flags
  * Local database connections
  * Development-only extensions
  * Verbose logging
</Note>

### Production Configuration

```json config/production.json theme={null}
{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}
```

<Warning>
  Production config should:

  * Use environment variables for secrets
  * Enable caching
  * Disable debug logging
  * Use production database
</Warning>

## Extension Configuration

### Extension Object Structure

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

### Real Examples

<CodeGroup>
  ```json Product Catalog Extension theme={null}
  {
    "name": "productCatalog",
    "resolve": "extensions/productCatalog",
    "enabled": true
  }
  ```

  ```json Payment Extension theme={null}
  {
    "name": "offlinePayments",
    "resolve": "extensions/offlinePayments",
    "enabled": true
  }
  ```

  ```json Reviews Extension theme={null}
  {
    "name": "productReviews",
    "resolve": "extensions/productReviews",
    "enabled": true
  }
  ```
</CodeGroup>

### Adding New Extensions

To register a new extension:

<Steps>
  <Step title="Create Extension Directory">
    ```bash theme={null}
    mkdir -p extensions/myExtension/src
    ```
  </Step>

  <Step title="Update config/default.json">
    ```json theme={null}
    {
      "system": {
        "extensions": [
          {
            "name": "myExtension",
            "resolve": "extensions/myExtension",
            "enabled": true
          },
          // ... other extensions
        ]
      }
    }
    ```
  </Step>

  <Step title="Restart Development Server">
    ```bash theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Note>
  Extensions are loaded in the **order they appear** in the configuration array.
</Note>

## Theme Configuration

### Setting Active Theme

```json config/default.json theme={null}
{
  "system": {
    "theme": "anasuplements"
  }
}
```

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

### Switching Themes

<CodeGroup>
  ```json Development Theme theme={null}
  // config/development.json
  {
    "system": {
      "theme": "anasuplements"
    }
  }
  ```

  ```json Production Theme theme={null}
  // config/production.json
  {
    "system": {
      "theme": "anasuplements"
    }
  }
  ```
</CodeGroup>

<Warning>
  Changing themes requires a rebuild:

  ```bash theme={null}
  npm run build
  ```
</Warning>

## Shop Configuration

### Language Settings

```json theme={null}
{
  "shop": {
    "language": "es"
  }
}
```

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

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

### Currency Settings

```json theme={null}
{
  "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):

```bash .env theme={null}
# 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=...
```

<Warning>
  Always add `.env` to `.gitignore`:

  ```bash theme={null}
  # .gitignore
  .env
  .env.local
  .env.*.local
  ```
</Warning>

### Accessing Environment Variables

```typescript theme={null}
// 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:

<CodeGroup>
  ```json Development (config/development.json) theme={null}
  {
    "system": {
      "extensions": [
        {
          "name": "devTools",
          "resolve": "extensions/devTools",
          "enabled": true  // Only in development
        }
      ]
    }
  }
  ```

  ```json Production (config/production.json) theme={null}
  {
    "system": {
      "extensions": [
        {
          "name": "devTools",
          "resolve": "extensions/devTools",
          "enabled": false  // Disabled in production
        }
      ]
    }
  }
  ```
</CodeGroup>

### Extension-Specific Configuration

Extensions can read custom config:

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

```typescript extensions/emailNotifications/src/bootstrap.ts theme={null}
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

<AccordionGroup>
  <Accordion title="1. Never Hardcode Secrets">
    ❌ **Bad**:

    ```json theme={null}
    {
      "database": {
        "password": "mypassword123"
      }
    }
    ```

    ✅ **Good**:

    ```bash theme={null}
    # .env
    DB_PASSWORD=mypassword123
    ```
  </Accordion>

  <Accordion title="2. Use Environment-Specific Overrides">
    Keep `default.json` minimal and override in environment files:

    ```json config/default.json theme={null}
    {
      "shop": {
        "language": "es",
        "currency": "USD"
      }
    }
    ```

    ```json config/production.json theme={null}
    {
      "shop": {
        "language": "es",
        "currency": "USD"
      },
      "cache": {
        "enabled": true
      }
    }
    ```
  </Accordion>

  <Accordion title="3. Document Extension Dependencies">
    If extensions depend on each other, document the required load order:

    ```json theme={null}
    {
      "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 }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="4. Version Control Strategy">
    ```bash theme={null}
    # Commit to Git
    config/default.json         ✅
    config/development.json     ✅
    config/production.json      ✅

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

    # Provide template
    .env.example                ✅
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Extension Not Loading

<Steps>
  <Step title="Check Configuration">
    Verify extension is registered in `config/default.json`:

    ```json theme={null}
    {
      "system": {
        "extensions": [
          {
            "name": "myExtension",
            "resolve": "extensions/myExtension",
            "enabled": true
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Verify Path">
    Ensure the `resolve` path is correct:

    ```bash theme={null}
    ls extensions/myExtension/src/
    ```
  </Step>

  <Step title="Check Enabled Flag">
    Make sure `"enabled": true`
  </Step>

  <Step title="Rebuild">
    ```bash theme={null}
    npm run build
    npm run start
    ```
  </Step>
</Steps>

### Theme Not Applying

<Steps>
  <Step title="Check Theme Name">
    ```json theme={null}
    {
      "system": {
        "theme": "anasuplements"  // Must match directory name
      }
    }
    ```
  </Step>

  <Step title="Verify Theme Directory">
    ```bash theme={null}
    ls themes/anasuplements/src/
    ```
  </Step>

  <Step title="Rebuild Theme">
    ```bash theme={null}
    npm run build
    ```
  </Step>
</Steps>

### Configuration Not Merging

<Note>
  Config files merge using **deep merge**:

  ```json theme={null}
  // default.json
  { "shop": { "language": "es", "currency": "USD" } }

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

  // Result in production:
  { "shop": { "language": "es", "currency": "EUR" } }
  ```
</Note>

## Configuration API

### Reading Configuration in Code

```typescript theme={null}
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

```typescript theme={null}
import config from 'config';

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

<Warning>
  Programmatic changes are **not persisted** to disk. They only exist during the current process.
</Warning>

## Example Configurations

### Minimal Setup

```json config/default.json theme={null}
{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "theme": "anasuplements"
  }
}
```

### Full Production Setup

```json config/production.json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="System Architecture" icon="sitemap" href="/architecture/overview">
    Learn how extensions and themes work together
  </Card>

  <Card title="Create Extension" icon="puzzle-piece" href="/guides/creating-extensions">
    Build your first extension
  </Card>
</CardGroup>