# analytics-sdk-generator

> Generates an SDK from an analytics descriptor file

Latest version **0.2.7** (published 2026-08-15) · GPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install analytics-sdk-generator
pnpm add analytics-sdk-generator
yarn add analytics-sdk-generator
bun add analytics-sdk-generator
```

Provides the command `analytics-sdk-generator`.

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.7 |
| Published | 2026-08-15 |
| First published | 2021-09-23 |
| Weekly downloads | 0 |
| License | GPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 94.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | leprechaun |
| Maintainers | leprechaun |
| Keywords | analytics, validation, json-schema, segment, rudderstack, AST, code-generation |

## Links

- npm: https://www.npmjs.com/package/analytics-sdk-generator
- Repository: https://github.com/leprechaun/analytics-sdk-generator
- Homepage: https://github.com/leprechaun/analytics-sdk-generator#readme
- Issues: https://github.com/leprechaun/analytics-sdk-generator/issues
- npm.io page: https://npm.io/package/analytics-sdk-generator

## Dependencies (2)

- [yaml](https://npm.io/package/yaml.md) ^2.0.0
- [yargs](https://npm.io/package/yargs.md) ^17.1.1

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 0.2.7 (latest) — 2026-08-15
- 0.1.21-f1c20c85 (beta) — 2023-09-09
- 0.1.20-f1c20c85 — 2023-09-09
- 0.1.19-f1c20c85 — 2023-09-09
- 0.1.18-f1c20c85 — 2023-09-09
- 0.1.17-f1c20c85 — 2023-09-09
- 0.1.16-f1c20c85 — 2023-09-09
- 0.1.15-f1c20c85 — 2023-09-09
- 0.1.14-f38d5beb — 2023-09-09
- 0.1.13-b78f81c7 — 2023-09-09
- 0.1.12-0f85c4cb — 2023-09-02
- 0.1.11-91b7a086 — 2023-09-02
- 0.1.10-f92cdf91 — 2023-09-02
- 0.1.9-ac1ed8a6 — 2023-09-02
- 0.1.8-8a0e80d0 — 2023-09-02
- … 48 more at https://npm.io/package/analytics-sdk-generator/versions

## README

# Analytics-SDK Generator

[![Maintainability](https://api.codeclimate.com/v1/badges/f17aec547af3af22902c/maintainability)](https://codeclimate.com/github/leprechaun/analytics-sdk-generator/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/f17aec547af3af22902c/test_coverage)](https://codeclimate.com/github/leprechaun/analytics-sdk-generator/test_coverage) [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fleprechaun%2Fanalytics-sdk-generator%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/leprechaun/analytics-sdk-generator/master) [![npm version](https://badge.fury.io/js/analytics-sdk-generator.svg)](https://www.npmjs.com/package/analytics-sdk-generator)

This project is a convenience for developers, data analysts and engineers alike.

It takes in a yaml file describing a mobile application and the analytics events that should be sent, and generates a corresponding type-checked SDK.

## Try it out

### Installing

```
yarn add analytics-sdk-generator
yarn analytics-sdk-generator transliterate --output ./output --input ./src/example/example-schema.yml
```

### Locally

```
# git clone ...
yarn install
yarn ts-node src/bin/cli.ts transliterate \
  --input src/example/example-schema.yml \
  --output ./output \
  --methodsAsync (true|false) \
  --implementation ./src/example/example-implementation
yarn ts-node src/example/example-client.ts
```

The transliterate command parses your analytics schema in `./src/example/example-schema.yml`, generates the code, and writes it to `./output`. Specifying `--implementation` is meant to specify a file whose default export is your analytics reporter implementation; by default, itonly does `console.log(...)`. `--methodsAsync true|false` will mark all methods as asynchronous and await the implementation.

## Schema format

The format was designed to expose as much json-schema as possible, while reducing verbosity. Any event property, trait, or shared definition is intended to be full json-schema 2019-09, but implementation is incomplete.

### Supported Types

#### String

```
type: string
enum: [...]
format: $format
```

##### Enum

Enums with only one option will be treated as a constant.

##### Format

For now, only `date-time` is supported.

#### Number

```
type: number | integer
```

Because javascript doesnt' really distinguish between numbers and integers, they are effectively aliases. Downstream validation tooling can support that distinction, though.

`min`, `max`, `multipleOf` and other constraints are not supported, but it could be done downstream.

#### Array

```
type: array
items: $TypeDefinition
```

Arrays can point to any supported type.

`minItems`, `maxItems` is not supported. Perhaps it both `min` and `max` are supported, one could define a typescript tuple.

#### Object

```
type: object
required: []
properties:
  someprop: $TypeDefinition
additionalProperties: false
```

There is basic support for objects. Properties can point to any supported typedefinition. AdditionalProperties is always assumed false, for the time being. Newer json-schema features on objects are not supported.

#### OneOf

```
oneOf:
  - TypeDefinition1
  - TypeDefinition2
```

One of create a union type between any supported data type. Unions of only one type will result in only that one type.

## File sections

The file is divided in 4 sections.

### Header

```
application:
  name: My Application
  version: 1.2.3
```

### $defs

JSON-Schema 2019-09 changed `definitions` to `$defs`. Any type defined here can be reused throughout the schema file using the usual `$ref: "#/$defs/YourThing"`

```
$defs:
  AnotherThing:
    type: string
    format: uuid

  YourThing:
    type: object
    properties:
      key1:
        type: string
      key2:
        $ref: "#/$defs/AnotherThing"
```

### Traits

Traits are key values set on a per-user basis, not on events.

```
traits:
  user_type:
    type: string
    enum:
    - manager
    - owner
    - end_user
  users_thing:
    $ref: "#/$defs/YourThing"
```

### Screens

Screens (and Tracks) are the two main event types, and as such are first class citizens.

```
screens:
  Welcome:
    name: welcome screen
    features:
    - Onboarding
    description: |
      This screen is the first screens users see when using the app.
    properties:
      is_first_open:
        description: Wether this is the first time the user opens the app
        type: boolean
      another_property:
        type: boolean
    required:
      - another_property
    tracks:
    - SomeTrack
    links:
    - AnotherScreen
```

`Welcome` is the event key. It will be used as the function names, and should be a valid javascript variable name.

`name: welcome` is the event name. The default is to re-use the event key.

`features` is a list of features this event is associated with.

`description` allows you to describe this event in free text. It will be included as a comment in the code, potentially displayed by your IDEs auto-suggestion.

`properties` are the properties this event is expected to have. All properties are expressed in json-schema form.

`required` is the list of property names that must be present in the event. It defaults to empty. Any property listed will be non-optional in the property types generated.

`tracks` is a list of `track` type events associated to this screen. Each event listed here will also result in an additional function in the screen function files.

`links` is a list of `screen` type events associated with this screen, typically screens a user can navigate to from here.

### Tracks

Tracks are events that can be emitted based on user interactions with your app that are not navigation based. The format is identical, except there are no `links`.

```
tracks:
  SomeTrack:
    features:
    - Onboarding
    description: |
      This event is emitted when something happens
    properties:
      some_property:
        description: Wether this is the first time the user opens the app
        type: boolean
```


## Using the code

Look at `./src/examples/example-client.ts`.

All `screen` events will result in a file in `./$outputDirectory/screens/$EventKey.ts`. The default export will be the analytics function that emits that screen event.

All `track` events associated with this screen will also be included in this file, exported by name.

```
import screen, * as tracks from './$outputDirectory/screens/Welcome'

//  emit type: screen, name: welcome screen, {is_first_open,another_property}
screen({is_first_open: true, another_property: "some string"})

//  emit type: track, name: SomeTrack, {some_property}
tracks.SomeTrack({some_property: "another property"})
```

---
_Source: https://npm.io/package/analytics-sdk-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._