Configuration
Complete guide to configuring the TypeScript SDK for different environments and use cases
The StorefrontSDK provides extensive configuration options to fit any environment or use case, from simple prototyping to complex production deployments.
Basic Configuration
Minimal Setup
Production Setup
Configuration Options
Core Configuration
Your unique store identifier from the Commerce Engine dashboard.
API key for authentication endpoints. Required for anonymous authentication and initial token acquisition.
Environment Management
Target environment for API requests. Controls which API endpoints are used.
Available Environments:
Environment.Production
→https://prod.api.commercengine.io/api/v1/{storeId}/storefront
Environment.Staging
→https://staging.api.commercengine.io/api/v1/{storeId}/storefront
Custom base URL that overrides the environment setting. Useful for on-premise deployments or custom endpoints.
When baseUrl
is provided, the environment
setting is ignored. Ensure your custom URL follows the correct API path structure.
Token Management
Initial access token for manual token management or as a starting token for automatic management.
Behavior:
- With tokenStorage: Used as initial token, then managed automatically
- Without tokenStorage: Used for manual token management
Initial refresh token. Only used when tokenStorage
is provided for automatic token management.
Token storage implementation for automatic token management. See Token Management for detailed information.
Request Configuration
Request timeout in milliseconds. When not set, uses the default fetch timeout behavior.
Recommended timeouts:
- Development: 30000ms (30 seconds) for easier debugging
- Production: 10000ms (10 seconds) for better user experience
- Server-side: 5000ms (5 seconds) for API routes
Default headers applied to all API requests. These can be overridden at the method level.
Supported Headers:
customer_group_id
: Used for customer-specific pricing, promotions, and subscription rates
Debugging & Logging
Enable detailed request/response logging for development and troubleshooting.
Debug Information Includes:
- Request URLs, methods, headers, and bodies
- Response status, headers, and bodies
- Token refresh attempts and results
- Network errors and retry attempts
Custom logger function for debug information. If not provided and debug is enabled, uses console.log
.
Logger Interface:
Framework-Specific Configurations
For detailed framework integration patterns including token storage, context setup, and best practices, see our dedicated guides:
Next.js Integration
SSR/SSG compatible configuration with universal token storage
React Integration
Client-side configuration with context providers and hooks
Node.js Integration
Server-side configuration for API routes and background jobs
Token Management
Complete guide to automatic token management and storage options
Quick Examples
Basic configuration examples for different environments:
Advanced Configuration Patterns
Multi-Tenant Configuration
Configuration Factory
Best Practices
✅ Configuration Recommendations
Environment Variables
Always use environment variables for sensitive configuration like API keys and store IDs
Secure Defaults
Use secure cookie settings in production with appropriate SameSite and Secure flags
Timeout Tuning
Set appropriate timeouts for your environment - longer for development, shorter for production
Debug Control
Enable debugging in development but disable in production for performance and security
Security Checklist
Use Environment Variables
Secure Cookie Configuration
Environment-Specific Settings
Never commit API keys or sensitive configuration to version control. Use environment variables and .env
files that are excluded from your repository.
Configuration Summary: The SDK’s flexible configuration system allows you to adapt to any environment while maintaining security and performance. Use automatic token management with appropriate storage for your platform, and always follow security best practices for production deployments.