# Settings.js Configuration Instructions

This file is the main configuration file for the ProjectZero Next.js application. All customizable settings are defined here.

## 📋 Table of Contents

- [Basic Structure](#basic-structure)
- [Available Settings](#available-settings)
- [Detailed Explanations](#detailed-explanations)
- [Example Configuration](#example-configuration)
- [Plugin Configuration](#plugin-configuration)
- [Important Notes](#important-notes)

## Basic Structure

```javascript
/** @type {import('@akinon/next/types').Settings} */
module.exports = {
  // Settings are defined here
};
```

## Available Settings

### 1. 🌐 Web Vitals
```javascript
webVitals: {
  enabled: true // Enables/disables web performance metrics
}
```

### 2. 🔗 Commerce URL
```javascript
commerceUrl: string // Backend API URL (taken from SERVICE_BACKEND_URL environment variable)
```

### 3. 🏷️ Product Attributes
```javascript
commonProductAttributes: [
  {
    translationKey: 'color', // Translation key
    key: 'color'             // Attribute key from API
  },
  {
    translationKey: 'size',
    key: 'size'
  }
]
```

### 4. 🌍 Localization Settings
```javascript
localization: {
  // Supported languages
  locales: [
    {
      label: 'EN',           // Display label
      value: 'en',           // Language code in ISO 639-1 format
      localePath: 'en',      // URL path
      apiValue: 'en-us',     // Value used for API
      rtl: false             // Right-to-left writing (true for Arabic, Hebrew)
    }
  ],
  
  // Supported currencies
  currencies: [
    {
      label: 'USD',          // Display label
      code: 'usd',           // Currency code in ISO 4217 format
      decimalScale: 2        // Number of decimal places (optional)
    }
  ],
  
  defaultLocaleValue: 'en',  // Default language
  localeUrlStrategy: LocaleUrlStrategy.HideDefaultLocale, // URL strategy
  redirectToDefaultLocale: true, // Redirect to default locale
  defaultCurrencyCode: 'usd', // Default currency
  
  // Dynamic currency determination (optional)
  getActiveCurrencyCode: ({ req, locale, defaultCurrencyCode }) => {
    // Custom currency determination logic
    return defaultCurrencyCode;
  },
  
  // Locale included pretty URL pattern (optional)
  localeIncludedPrettyUrlPattern: new RegExp('.+/pages/.+$')
}
```

#### Locale URL Strategies:
- `LocaleUrlStrategy.HideDefaultLocale`: Default language is hidden in URL
- `LocaleUrlStrategy.ShowAllLocales`: All languages are shown in URL
- `LocaleUrlStrategy.HideAllLocales`: No language is shown in URL

### 5. 🔄 URL Rewrites
```javascript
rewrites: [
  {
    source: '/auth',         // Source URL
    destination: '/auth'     // Destination URL
  }
]
```

### 6. ⚡ Redis Cache Settings
```javascript
redis: {
  defaultExpirationTime: 900 // Default cache duration (seconds)
}
```

### 7. 💳 Checkout Settings
```javascript
checkout: {
  // Payment options to exclude from iframe (deprecated)
  iframeExcludedPaymentOptions: ['payment-option-slug'],
  
  // Payment options to include in iframe
  iframeIncludedPaymentOptions: ['payment-option-slug'],
  
  // Additional payment types
  extraPaymentTypes: ['custom-payment-type'],
  
  // Masterpass JS URL
  masterpassJsUrl: 'https://example.com/masterpass.js'
}
```

### 8. ⚙️ Other Settings
```javascript
// Enable custom 404 page
customNotFoundEnabled: false,

// Use optimized translations
useOptimizedTranslations: true,

// Use pretty URL route
usePrettyUrlRoute: true,

// Plugin settings
plugins: {
  'plugin-name': {
    setting1: 'value1',
    setting2: 'value2'
  }
},

// Proxy headers - determines which headers should be passed to Commerce API
includedProxyHeaders: ['x-custom-header', 'x-forwarded-for', 'user-agent'],

// Commerce redirection ignore list
commerceRedirectionIgnoreList: ['/api/', '/_next/'],

// Reset basket when currency changes
resetBasketOnCurrencyChange: true,

// Frontend IDs used to pass x-frontend-id header to commerce
frontendIds: {
  'frontend-name': 123
}
```

## Detailed Explanations

### 🔒 includedProxyHeaders

This setting determines which HTTP headers should be passed in proxy requests from the Next.js application to the Commerce API.

#### How It Works?

1. **Default Behavior**: The system does not pass certain headers to the Commerce API by default
2. **Override Mechanism**: Headers specified in the `includedProxyHeaders` array are passed to the Commerce API even if they are in the excluded list

#### Why Is It Used?

- **🔐 Security**: Prevents headers containing sensitive information from being passed to the Commerce API
- **⚡ Performance**: Prevents unnecessary headers from being passed
- **🔧 Flexibility**: Allows specific headers to be passed for special cases

#### Usage Example

```javascript
includedProxyHeaders: [
  'x-forwarded-for',
  'user-agent', 
  'x-custom-header',
  'x-device-type'
]
```

### 🚫 commerceRedirectionIgnoreList

This setting determines which URL patterns should disable redirections (redirects) coming from the Commerce API.

#### How It Works?

1. **Middleware Process**: The `url-redirection.ts` middleware runs on every URL request
2. **Commerce Check**: The middleware sends the current URL to the Commerce API
3. **Redirect Check**: If a redirect response comes from the Commerce API, `commerceRedirectionIgnoreList` is checked
4. **Pattern Matching**: If the redirect URL matches one of the patterns in the ignore list, the redirect is not performed

#### Why Is It Used?

- Ensures that certain pages are not affected by Commerce redirects

#### Usage Example

```javascript
commerceRedirectionIgnoreList: ['/users/reset']
```

## Example Configuration

```javascript
const { LocaleUrlStrategy } = require('@akinon/next/localization');
const { ROUTES } = require('@theme/routes');

const commerceUrl = encodeURI(process.env.SERVICE_BACKEND_URL ?? 'default');

/** @type {import('@akinon/next/types').Settings} */
module.exports = {
  webVitals: {
    enabled: true
  },
  commerceUrl,
  commonProductAttributes: [
    { translationKey: 'color', key: 'color' },
    { translationKey: 'size', key: 'size' }
  ],
  localization: {
    locales: [
      {
        label: 'EN',
        value: 'en',
        localePath: 'en',
        apiValue: 'en-us',
        rtl: false
      },
      {
        label: 'TR',
        value: 'tr',
        localePath: 'tr',
        apiValue: 'tr-tr',
        rtl: false
      }
    ],
    currencies: [
      {
        label: 'USD',
        code: 'usd',
        decimalScale: 2
      },
      {
        label: 'TRY',
        code: 'try',
        decimalScale: 2
      }
    ],
    defaultLocaleValue: 'en',
    localeUrlStrategy: LocaleUrlStrategy.HideDefaultLocale,
    redirectToDefaultLocale: true,
    defaultCurrencyCode: 'usd'
  },
  rewrites: [
    {
      source: ROUTES.AUTH,
      destination: '/auth'
    }
  ],
  redis: {
    defaultExpirationTime: 900
  },
  customNotFoundEnabled: false
};
```

## Plugin Configuration

The `plugins` setting allows you to customize the behavior of plugins in the ProjectZero ecosystem.

### 🎛️ How It Works?

1. **Plugin System**: Plugins are loaded through the `PluginModule` component
2. **Settings Integration**: Each plugin gets its own settings through `settings.plugins[pluginName]`
3. **Dynamic Loading**: Plugins are loaded only when needed (lazy loading)
4. **Customization**: Each plugin has its own specific settings

### 🚀 Example: pz-akifast Plugin Configuration

```javascript
plugins: {
  'pz-akifast': {
    quickLogin: false,  // Hide quick login button
    pdp: false,         // Hide checkout button on product detail page
    basket: true        // Show checkout button on basket page
  }
}
```


### 💡 Plugin Usage Examples

#### Akifast Quick Login Button
```javascript
// settings.js
plugins: {
  'pz-akifast': {
    quickLogin: true  // Show button
  }
}
```

#### Akifast Checkout Button
```javascript
// settings.js
plugins: {
  'pz-akifast': {
    pdp: true,    // Show on product detail page
    basket: false // Hide on basket page
  }
}
```

### ⚠️ Things to Consider

1. **Plugin Names**: Plugin names must match exactly (e.g., `pz-akifast`)
5. **Performance**: Plugins are loaded only when needed

## Important Notes

1. **📝 TypeScript Support**: The file provides TypeScript support with `@type` comment
2. **🌐 Environment Variables**: Commerce URL is taken from `SERVICE_BACKEND_URL` environment variable
3. **📦 Imports**: Required modules must be imported at the beginning of the file
4. **✅ Validation**: All settings must comply with the Settings interface
5. **⚡ Performance**: Redis cache settings affect performance
6. **🌍 Localization**: Language and currency settings directly affect the e-commerce experience
7. **🔒 Proxy Headers**: The `includedProxyHeaders` setting is critical for security and performance
8. **🚫 Redirect Control**: The `commerceRedirectionIgnoreList` setting is important for protecting APIs and static files