Configuration reference

Snowtype reads its settings from a configuration file in your project root. The file is created when you run snowtype init, and you can edit it directly at any time.

Keep the configuration file in the root of your project, and include it in your version control system.

Terminology

We originally called tracking plans "data products". You'll still find the old term used in some existing APIs and CLI commands.

Configuration file structure

The configuration file is a JSON, JavaScript, or TypeScript object. You can choose format which to use during initialization. As JSON, it has the following structure:

jsonsnowtype.config.json
{
    "organizationId": "a654321b-c111-33d3-e321-1f123456789g",
    "tracker": "@snowplow/browser-tracker",
    "language": "typescript",
    "outpath": "./src/snowtype",
    "eventSpecificationIds": [
        "a123456b-c222-11d1-e123-1f123456789g"
    ],
    "dataProductIds": [
        "a123456b-c222-11d1-e123-1f12345678dp"
    ],
    "dataStructures": [
        "iglu:com.myorg/custom_web_page/jsonschema/1-1-0"
    ],
    "igluCentralSchemas": [
        "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0"
    ],
    "repositories": ["../data-structures"],
    "namespace": "Snowtype",
    "options": {
        "commands": {
            "generate": {
                "instructions": true,
                "validations": true,
                "disallowDevSchemas": true
            },
            "update": {
                "maximumBump": "minor",
                "showOnlyProdUpdates": true
            },
            "patch": {
                "regenerateOnPatch": false
            }
        }
    }
}

Property	Type	Description	Required
`organizationId`	`string`	Your Snowplow account organization ID. Used to fetch tracking plans, event specifications, or data structures from Console. Not required if you're only generating code from a local repository.	✅/❌
`tracker`	`string`	The Snowplow tracker to generate code for. This determines the structure of the generated code and which tracker it will work with.	✅
`language`	`string`	The programming language to generate code in.	✅
`outpath`	`string`	The output path where Snowtype writes the generated code, relative to the current working directory when running the script.	✅
`dataProductIds`	`string[]`	An array of tracking plan IDs to generate code for.	✅
`eventSpecificationIds`	`string[]`	An array of event specification IDs to generate code for.	✅
`dataStructures`	`string[]`	An array of schema URIs for data structures published in Console to generate code for.	✅
`igluCentralSchemas`	`string[]`	An array of schema URIs for Iglu Central schemas to generate code for.	❌
`repositories`	`string[]`	An array of paths to local Snowplow CLI schema repositories to generate code for.	❌
`namespace`	`string`	Swift tracker only: a namespace prefix for the generated code. For other trackers it will trigger an error.	❌
`options`	`object`	Additional settings related to Snowtype behavior. See details below.	❌

To find your organization ID, go to Console > Settings > Manage organization.

File formats

Most of the examples in this documentation show the configuration file in JSON format, but you can also use JavaScript or TypeScript if you prefer. The filename must start with snowtype.config — for example, snowtype.config.json, snowtype.config.js, or snowtype.config.ts.

JavaScript
TypeScript

javascriptsnowtype.config.js
const config = {
    "organizationId": "a654321b-c111-33d3-e321-1f123456789g",
    "tracker": "@snowplow/browser-tracker",
    "language": "typescript",
    "outpath": "./src/snowtype",
    "eventSpecificationIds": [
        "a123456b-c222-11d1-e123-1f123456789g"
    ],
    "dataProductIds": [
        "a123456b-c222-11d1-e123-1f12345678dp"
    ],
    "dataStructures": [
        "iglu:com.myorg/custom_web_page/jsonschema/1-1-0"
    ],
    "igluCentralSchemas": [
        "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0"
    ],
    "repositories": ["../data-structures"],
    "namespace": "Snowtype",
    "options": {
        "commands": {
            "generate": {
                "instructions": true,
                "validations": true,
                "disallowDevSchemas": true
            },
            "update": {
                "maximumBump": "minor",
                "showOnlyProdUpdates": true
            },
            "patch": {
                "regenerateOnPatch": false
            }
        }
    }
};

module.exports = config;

typescriptsnowtype.config.ts
const config = {
    organizationId: "a654321b-c111-33d3-e321-1f123456789g",
    tracker: "@snowplow/browser-tracker" as const,
    language: "typescript" as const,
    outpath: "./src/snowtype",
    eventSpecificationIds: [
        "a123456b-c222-11d1-e123-1f123456789g"
    ],
    dataProductIds: [
        "a123456b-c222-11d1-e123-1f12345678dp"
    ],
    dataStructures: [
        "iglu:com.myorg/custom_web_page/jsonschema/1-1-0"
    ],
    igluCentralSchemas: [
        "iglu:com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0"
    ],
    repositories: ["../data-structures"],
    namespace: "Snowtype",
    options: {
        commands: {
            generate: {
                instructions: true,
                validations: true,
                disallowDevSchemas: true
            },
            update: {
                maximumBump: "minor",
                showOnlyProdUpdates: true
            },
            patch: {
                regenerateOnPatch: false
            }
        }
    }
};

export default config;

Supported trackers and languages

Set tracker and language to a valid combination from this table:

Tracker	`tracker`	`language`
Browser	`@snowplow/browser-tracker`	`javascript`, `typescript`
JavaScript	`@snowplow/javascript-tracker`	`javascript`
iOS	`snowplow-ios-tracker`	`swift`
Android	`snowplow-android-tracker`	`kotlin`
React Native	`@snowplow/react-native-tracker`	`typescript`
Flutter	`snowplow-flutter-tracker`	`dart`
Node.js	`@snowplow/node-tracker`	`javascript`, `typescript`
Go	`snowplow-golang-tracker`	`go`
Java	`snowplow-java-tracker`	`java`
Google Tag Manager	`google-tag-manager`	`javascript-gtm`

Command options

The options object configures the behavior of specific Snowtype commands. You can set these in the configuration file so they apply on every run, or override them with CLI flags. See the commands reference for more details on the flags.

Flag priority

CLI flags take precedence over values set in the configuration file.

`generate`

The generate options apply when running snowtype generate, which creates the initial code based on your configuration and schemas.

Option	Type	Default	Description	Equivalent flag
`instructions`	`boolean`	`false`	Generate a Markdown file with implementation instructions for each event specification	`--instructions`
`validations`	`boolean`	`false`	Include runtime client-side validation code in the output	`--validations`
`disallowDevSchemas`	`boolean`	`false`	Fail generation if any schema is only deployed to the development environment	`--disallowDevSchemas`
`deprecateOnlyOnProdAvailableUpdates`	`boolean`	`false`	Only show deprecation warnings for schemas that have a newer version deployed to production	`--deprecateOnlyOnProdAvailableUpdates`

jsonExample
{
    "options": {
        "commands": {
            "generate": {
                "instructions": true,
                "validations": true,
                "disallowDevSchemas": true
            }
        }
    }
}

`update`

The update options apply when running snowtype update, which checks for new schema versions and regenerates code if needed.

Option	Type	Default	Description
`regenerateOnUpdate`	`boolean`	`true`	Automatically regenerate code after accepting updates.
`maximumBump`	`"major"` \| `"minor"` \| `"patch"`	`"major"`	The highest SchemaVer bump level to include in update checks. For example, setting this to `"minor"` hides major version updates.
`showOnlyProdUpdates`	`boolean`	`false`	Only show updates for data structures that have been deployed to the production environment.

jsonExample
{
    "options": {
        "commands": {
            "update": {
                "maximumBump": "minor",
                "showOnlyProdUpdates": true
            }
        }
    }
}

`patch`

The patch option applies when running snowtype patch, which adds new sources to your configuration file and optionally regenerates code.

Option	Type	Default	Description
`regenerateOnPatch`	`boolean`	`true`	Automatically regenerate code after adding new schemas with `snowtype patch`.

jsonExample
{
    "options": {
        "commands": {
            "patch": {
                "regenerateOnPatch": false
            }
        }
    }
}

Swift namespace

The namespace option applies only when generating Swift code. It adds a prefix to all generated classes, which helps avoid naming conflicts in your project.

For example, setting namespace to "Snowtype":

jsonsnowtype.config.json
{
    "tracker": "snowplow-ios-tracker",
    "language": "swift",
    "outpath": "./Sources/Tracking",
    "namespace": "Snowtype"
}

This results in classes accessed with the Snowtype prefix:

swift
let data = Snowtype.AccountConfirmed(
    companyCountry: "US",
    companyName: "Acme Corp"
)

Setting a namespace when generating code for a non-Swift tracker will trigger an error.

Full configuration type

For TypeScript users, this is the complete type definition for the configuration file:

typescript
type SnowtypeConfig = {
    tracker:
        | "@snowplow/browser-tracker"
        | "@snowplow/javascript-tracker"
        | "@snowplow/node-tracker"
        | "@snowplow/react-native-tracker"
        | "snowplow-android-tracker"
        | "snowplow-ios-tracker"
        | "snowplow-golang-tracker"
        | "snowplow-flutter-tracker"
        | "snowplow-java-tracker";
    language:
        | "typescript"
        | "javascript"
        | "kotlin"
        | "swift"
        | "go"
        | "dart"
        | "java";
    outpath: string;
    organizationId?: string;
    eventSpecificationIds?: string[];
    dataProductIds?: string[];
    dataStructures?: string[];
    igluCentralSchemas?: string[];
    repositories?: string[];
    namespace?: string;
    options?: {
        commands: {
            generate?: {
                instructions?: boolean;
                validations?: boolean;
                disallowDevSchemas?: boolean;
                deprecateOnlyOnProdAvailableUpdates?: boolean;
            };
            update?: {
                regenerateOnUpdate?: boolean;
                maximumBump?: "major" | "minor" | "patch";
                showOnlyProdUpdates?: boolean;
            };
            patch?: {
                regenerateOnPatch?: boolean;
            };
        };
    };
};

Configuration file structure​

File formats​

Supported trackers and languages​

Command options​

generate​

update​

patch​

Swift namespace​

Full configuration type​

Want to see a custom demo?