Skip to main content

Custom Configuration

Overview​

The configuration system is arguably the most important element built into GA4Dataform. With a proper configuration, you can manage variables, modularize features, and control your data transformation pipeline without modifying core SQLX files. Think of the configuration as a control panel of JavaScript variables that determine what the final SQL output will look like.

You can customize elements such as:

  • Start date for data processing
  • User properties to extract
  • Event and item parameters to unnest
  • Events to filter out
  • URL parameters to capture
  • User stitching 💎
  • Session totals 💎
  • Session-level custom parameters 💎
  • Support for fresh and intraday tables 💎
  • ... and many more!

This approach enables distribution of the same Dataform repository without hardcoded variables, making your implementation portable and maintainable.

Configuration Architecture​

GA4Dataform uses a module-based configuration system with three layers of configuration files organized per module:

Module-Based Structure​

Configurations are organized by module under the includes/ directory:

includes/
├── core/
│   └── modules/
│       └── ga4/
│           ├── config.js           # Default config created by Superform Labs team
│           └── helpers.js          # Module-specific helpers
└── custom/
    └── modules/
        └── ga4/
            └── config.js           # Your custom overrides

Configuration Layers​

GA4Dataform uses a two-layer configuration system that allows you to customize without modifying core files:

1. Core Configuration​

Location: includes/core/modules/ga4/config.js

  • Contains all default values and settings
  • Includes standard event parameters and click IDs
  • Provides fallback variables to prevent compilation errors
  • Should not be modified by users (will be overwritten during updates)

2. Custom Configuration​

Location: includes/custom/modules/ga4/config.js

  • Your customization layer
  • Takes precedence over core configuration
  • Safe from updates and overwrites
  • Where all your specific settings should be defined
  • Created with the structure in place but variables set to empty arrays/defaults

Configuration File Formats​

Configuration files can be in any of these formats:

  • JavaScript (.js) - Allows dynamic logic and helper functions
  • JSON (.json) - Simple key-value configuration
  • YAML (.yaml) - Human-readable structured format that allows comments

The system automatically detects and handles the appropriate format.

Configuration Merging​

When you request a module's configuration, GA4Dataform merges the core and custom configurations using a spread operator that prioritizes your custom settings:

const getModuleConfig = (moduleName) => {
  const coreConfig = getConfigByType(moduleName, "core");
  const customConfig = getConfigByType(moduleName);
  return { ...coreConfig, ...customConfig };
};

Usage in your SQLX files:

const config = helpers.getModuleConfig('ga4');

Your values in includes/custom/modules/ga4/config.js will always take precedence over the core configuration, ensuring your customizations are preserved during updates.

Multi-Module Support​

The module system allows for multiple independent modules (e.g., ga4, google_ads, gcp_cost), each with their own configuration:

includes/custom/modules/
├── ga4/
│   └── config.js
├── google_ads/
│   └── config.yaml
└── gcp_cost/
    └── config.json

Each module can be enabled/disabled and configured independently through its respective configuration file.

All configuration variables and detailed instructions on how to use them available at the configuration variable page!