---
description: Essential naming conventions and structural patterns that apply to all files
alwaysApply: true
---

# Core Conventions

## File Naming
- Use kebab-case for all JavaScript files: `mixpanel-core.js`, `mixpanel-queue.js`
- Prefix all internal modules with `mixpanel-` for consistency
- Use descriptive names reflecting single responsibility

## Variable Naming
- camelCase for standard variables: `mixpanelImpl`, `trackAutomaticEvents`
- SCREAMING_SNAKE_CASE for constants: `DEFAULT_OPT_OUT`, `PARAMS.TOKEN`
- Leading underscore for private variables: `_queues`, `_shouldLog`

## Function Naming
- Verb-first naming: `initialize`, `track`, `flush`, `addToMixpanelQueue`
- Boolean predicates: `isValidAndSerializable`, `hasOptedOutTracking`
- Event handlers: `handleBatchError`

## Import Organization (REQUIRED)
```javascript
// 1. External dependencies first (with consistent spacing)
import { Platform } from "react-native";
import packageJson from "./package.json";

// 2. Internal modules second, grouped by purpose
import { MixpanelCore } from "./mixpanel-core";
import { MixpanelType } from "./mixpanel-constants";
import { MixpanelConfig } from "./mixpanel-config";

// ⚠️ Style Note [Updated: 2025-05-30]: Use consistent destructuring with spaces
// ✅ Correct: import { MixpanelCore } from "./mixpanel-core";
// ❌ Incorrect: import {MixpanelCore} from "./mixpanel-core";
```

## Export Patterns
- Named exports for utilities: `export class MixpanelLogger`
- Default exports for main classes: `export default class MixpanelMain`
- Factory function exports: `export const MixpanelCore = (storage) => {...}`

## Token-Based Architecture (CRITICAL)
- EVERY operation MUST include token as first parameter
- ALL storage keys MUST be token-scoped: `MIXPANEL_${token}_${type}_${field}`
- ALL configuration MUST be per-token for multi-project support

Example function signatures:
```javascript
const flush = async (token) => { /* ... */ };
const track = async (token, eventName, properties) => { /* ... */ };
```

## Logging Patterns (REQUIRED)
- ALL logs MUST include token context
- ALL logs MUST use [Mixpanel] prefix for filtering
- ALL logs MUST respect per-token logging settings

```javascript
MixpanelLogger.log(token, `Track '${eventName}' with properties`, properties);
```