Using Extensions in Your Project

Extensions are pre-built, reusable Django apps that add functionality to your project. This guide shows you how to use them as a Django-CFG user.

Concept: How Extensions Work

What Are Extensions?

Extensions are plug-and-play Django apps that:

• ✅ Configure themselves automatically
• ✅ Don’t clutter your main DjangoConfig
• ✅ Can be enabled/disabled with one line
• ✅ Work across multiple projects

Think of them like WordPress plugins or VS Code extensions - install once, configure simply, use everywhere.

Available Extensions

Your Django-CFG project comes with several built-in extensions:

Business Features:

• payments - Payment processing (Stripe, crypto providers)
• leads - Lead management and contact forms
• support - Support ticket system
• newsletter - Email campaigns
• knowbase - Knowledge base articles

Developer Tools:

• backup - Automated database backups
• maintenance - Maintenance mode
• agents - AI workflow automation

Utilities:

• currency - Multi-currency support
• analytics - Analytics tracking

Quick Start: Enable Your First Extension

Step 1: Check Available Extensions

List what’s already in your project:

ls extensions/apps/

You’ll see directories like payments, leads, support, etc.

Step 2: Enable an Extension

To enable the Payments extension, edit its config file:

# extensions/apps/payments/__cfg__.py
from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class PaymentsSettings(BaseExtensionSettings):
    # Override default settings
    crypto_api_key: str = env.payments_api_keys.crypto_api_key
    crypto_webhook_secret: str = env.payments_api_keys.crypto_webhook_secret
 
# This line enables the extension! ✨
settings = PaymentsSettings()

Step 3: Run Migrations

python manage.py migrate

Step 4: That’s It! 🎉

The extension is now:

• ✅ Added to INSTALLED_APPS
• ✅ URLs registered at /cfg/payments/
• ✅ Admin navigation added
• ✅ Background tasks scheduled
• ✅ Ready to use

Configuring Extensions

Understanding Extension Settings

Each extension has a __cfg__.py file in its directory:

extensions/apps/payments/
├── __cfg__.py          ← Configuration file
├── models.py
├── views.py
└── ...

The scanner supports both __cfg__.py (preferred) and __manifest__.py (legacy) for configuration. Extensions are loaded in dependency order using topological sorting. Each settings class must implement to_manifest() for the scanner.

The __cfg__.py file looks like this:

from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class PaymentsSettings(BaseExtensionSettings):
    # Your project-specific settings here
    crypto_api_key: str = env.payments_api_keys.crypto_api_key
 
settings = PaymentsSettings()  # Enable extension

Common Configuration Patterns

Pattern 1: Enable/Disable Extension

# Enable
settings = PaymentsSettings()
 
# Disable (comment out or remove)
# settings = PaymentsSettings()

Pattern 2: Environment Variables

class PaymentsSettings(BaseExtensionSettings):
    # Load from environment
    crypto_api_key: str = env.payments_api_keys.crypto_api_key
    crypto_webhook_secret: str = env.payments_api_keys.crypto_webhook_secret

Then in your .env:

PAYMENTS_API_KEYS__CRYPTO_API_KEY=your-api-key
PAYMENTS_API_KEYS__CRYPTO_WEBHOOK_SECRET=your-secret

Pattern 3: Override Defaults

class LeadsSettings(BaseExtensionSettings):
    # Override base settings
    telegram_enabled: bool = False  # Disable Telegram notifications
    email_enabled: bool = True      # Keep email enabled

Pattern 4: Feature Flags

class SupportSettings(BaseExtensionSettings):
    # Toggle features
    ticket_auto_assign: bool = True
    live_chat_enabled: bool = False
    sla_tracking_enabled: bool = True

Extension Types

Django-CFG has two kinds of extensions, each with its own base settings class:

App Extensions (BaseExtensionSettings)

For Django app extensions that live in extensions/apps/. These are full Django apps with models, views, and URL routing.

from django_cfg.extensions.configs.apps import BaseExtensionSettings
 
class PaymentsSettings(BaseExtensionSettings):
    admin_enabled: bool = True
    api_key: str = env.payments.api_key

Key fields on BaseExtensionSettings:

Module Extensions (BaseModuleSettings)

For utility module extensions that live in extensions/modules/. These are non-app Python modules (no models or URLs).

from django_cfg.extensions.configs.modules import BaseModuleSettings
 
class MyUtilitySettings(BaseModuleSettings):
    enabled: bool = True  # Can be toggled on/off
    some_option: str = "default"

The key difference: BaseModuleSettings has an enabled: bool = True field that lets you toggle the module on or off without removing the settings object.

Extension Configuration Reference

Core Settings

App extensions support these settings:

class MyExtensionSettings(BaseExtensionSettings):
    # Core settings
    admin_enabled: bool = True        # Show in admin interface
 
    # Your custom settings
    api_key: str = env.my_ext.api_key
    feature_x_enabled: bool = True

Accessing Settings in Code

Settings are available via the extension’s settings object:

from extensions.apps.payments.__cfg__ import settings
 
# Extension is enabled when the settings object exists
api_key = settings.crypto_api_key

Environment Configuration

Using .env Files

Extensions load settings from environment variables:

1. Define in __cfg__.py:

class PaymentsSettings(BaseExtensionSettings):
    crypto_api_key: str = env.payments_api_keys.crypto_api_key

2. Set in .env:

# Nested structure: payments_api_keys.crypto_api_key
PAYMENTS_API_KEYS__CRYPTO_API_KEY=your-key-here
PAYMENTS_API_KEYS__CRYPTO_WEBHOOK_SECRET=your-secret-here

3. Verify it works:

python manage.py shell
>>> from extensions.apps.payments.__cfg__ import settings
>>> settings.crypto_api_key
'your-key-here'

Environment-Specific Configs

Use different settings per environment:

# extensions/apps/payments/__cfg__.py
import os
 
class PaymentsSettings(BaseExtensionSettings):
    # Production: use real API
    # Development: use sandbox
    crypto_api_key: str = (
        env.payments.prod_key
        if os.getenv('ENVIRONMENT') == 'production'
        else env.payments.sandbox_key
    )

Troubleshooting

Extension Not Appearing

Problem: Extension doesn’t show up in admin or URLs don’t work

Solutions:

1. Check settings variable exists:

   # extensions/apps/myext/__cfg__.py
   settings = MyExtensionSettings()  # ← Must be present!

2. Check for import errors:

   python manage.py shell
   >>> from extensions.apps.myext.__cfg__ import settings
   # If this errors, fix the import

3. Restart Django:

   # Extensions are discovered at startup
   python manage.py runserver

Extension Enabled But Not Working

Problem: Extension is enabled but features don’t work

Solutions:

1. Run migrations:

   python manage.py migrate

2. Check extension settings:

   from extensions.apps.myext.__cfg__ import settings
   print(settings.enabled)  # Should be True
   print(settings.admin_enabled)  # Should be True

3. Check dependencies:

   # Install required pip packages
   pip install -r requirements.txt

Environment Variables Not Loading

Problem: env.something returns error or wrong value

Solutions:

1. Check .env file location:

   # Must be in project root
   ls -la .env

2. Check variable naming:

   # Use double underscores for nesting
   PAYMENTS_API_KEYS__CRYPTO_API_KEY=key  # ✅ Correct
   PAYMENTS_API_KEYS.CRYPTO_API_KEY=key   # ❌ Wrong

3. Reload environment:

   # Restart Django after .env changes
   python manage.py runserver

URL Conflicts

Problem: Extension URLs conflict with your app’s URLs

Solution: Extensions use /cfg/ prefix by default. Each extension can have multiple URL files, each mounted at a different sub-path:

/cfg/payments/          ← urls.py (main API)
/cfg/payments/admin/    ← urls_admin.py (admin API)
/cfg/payments/system/   ← urls_system.py (system API)
/cfg/payments/<custom>/ ← urls_<custom>.py (custom endpoints)

/api/                   ← Your app URLs (no conflict)
/admin/                 ← Django admin (no conflict)

You can override the path segment using url_prefix in extension settings, or change the namespace with url_namespace.

Migration Errors

Problem: python manage.py migrate fails for extension

Solutions:

1. Check app label:

   # Extensions use cfg_ prefix
   python manage.py migrate cfg_payments
   python manage.py migrate cfg_leads

2. Make migrations first:

   python manage.py makemigrations
   python manage.py migrate

3. Check for conflicts:

   # List all migrations
   python manage.py showmigrations

Best Practices

1. Keep Extension Configs in __cfg__.py

✅ Good:

# extensions/apps/payments/__cfg__.py
class PaymentsSettings(BaseExtensionSettings):
    crypto_api_key: str = env.payments.api_key

❌ Bad:

# api/config.py
class MyConfig(DjangoConfig):
    payments: PaymentsConfig = PaymentsConfig(...)  # Old way!

2. Use Environment Variables for Secrets

✅ Good:

api_key: str = env.payments.api_key  # Load from .env

❌ Bad:

api_key: str = "hardcoded-secret-key"  # Never do this!

3. Enable Only What You Need

# If not using Telegram notifications
class LeadsSettings(BaseExtensionSettings):
    telegram_enabled: bool = False  # Disable unused features

4. Document Your Customizations

class SupportSettings(BaseExtensionSettings):
    # Custom: We use 48-hour SLA instead of 24
    sla_hours: int = 48
 
    # Custom: Auto-assign disabled per team request
    ticket_auto_assign: bool = False

Common Use Cases

Use Case 1: Payment Processing

Goal: Accept cryptocurrency payments

Solution:

1. Enable payments extension:

   # extensions/apps/payments/__cfg__.py
   settings = PaymentsSettings()

2. Configure API keys:

   # .env
   PAYMENTS_API_KEYS__CRYPTO_API_KEY=your-key
   PAYMENTS_API_KEYS__CRYPTO_WEBHOOK_SECRET=your-secret

3. Done! Use at /cfg/payments/

Use Case 2: Lead Capture Forms

Goal: Add contact forms to your site

Solution:

1. Enable leads extension:

   # extensions/apps/leads/__cfg__.py
   settings = LeadsSettings()

2. Configure notifications:

   class LeadsSettings(BaseExtensionSettings):
       email_enabled: bool = True
       telegram_enabled: bool = True  # Get Telegram alerts

3. Forms available in admin + API endpoints ready

Use Case 3: Support Tickets

Goal: Add customer support system

Solution:

1. Enable support extension:

   # extensions/apps/support/__cfg__.py
   settings = SupportSettings()

2. Configure SLA tracking:

   class SupportSettings(BaseExtensionSettings):
       sla_tracking_enabled: bool = True
       sla_hours: int = 24
       ticket_auto_assign: bool = True

3. Support dashboard appears in admin

FAQ

Q: How do I know which extensions are available?

A: Check your extensions/apps/ directory:

ls extensions/apps/

Or check the Hub at /hub in your project.

Q: Can I use multiple extensions together?

A: Yes! Extensions work independently. Enable as many as you need:

# extensions/apps/payments/__cfg__.py
settings = PaymentsSettings()
 
# extensions/apps/leads/__cfg__.py
settings = LeadsSettings()
 
# extensions/apps/support/__cfg__.py
settings = SupportSettings()

Q: How do I disable an extension temporarily?

A: For app extensions, comment out the settings line:

# extensions/apps/payments/__cfg__.py
# settings = PaymentsSettings()  # Disabled

For module extensions, set enabled = False:

class MyModuleSettings(BaseModuleSettings):
    enabled: bool = False

Q: Do I need to restart Django after changing extension settings?

A: Yes, extensions are loaded at startup. After changing __cfg__.py:

# Restart Django
python manage.py runserver

Q: Where can I find extension documentation?

A: Each extension has:

1. Comments in its __cfg__.py file
2. Documentation in the Hub (/hub/{name})
3. README in the extension directory (if available)

Q: Can I modify extension code?

A: Yes, but better to:

1. Override settings in __cfg__.py (preferred)
2. Use extension hooks/signals (if provided)
3. Extend extension classes in your project apps

Modifying extension code directly makes updates harder.

Next Steps