Typewriter

9.2.0 verified Fri May 01 auth: no javascript

Typewriter is a compiler that generates strongly typed analytics clients from Segment Protocols tracking plans, ensuring type safety and compile-time validation for event and property names. Version 9.2.0 requires Node >=18 and is actively maintained by Segment. It supports multiple languages including JavaScript (browser and Node), Swift, Kotlin, and React Native. Key differentiators include integration with Segment's centralized tracking plans, CI-based analytics validation to catch instrumentation mismatches before deployment, and customizable code generation with prefixes/suffixes. The package ships TypeScript types and is distributed as an oclif CLI tool. Release cadence is frequent with multiple minor versions per year.

Common errors

error npx typewriter build: Error: Could not find typewriter.yml in current or parent directories ↓

cause No typewriter.yml configuration file exists or command run from wrong directory.

fix

Run npx typewriter init first in your project root to generate the config, then run build from the same directory.

error TypeError: Cannot read properties of undefined (reading 'properties') ↓

cause Generated client TypeScript error when event properties are undefined in tracking plan (common in older versions).

fix

Upgrade to typewriter >=8.0.5. If fixed, regenerate the client with npx typewriter build.

error Error: You must provide a Public API Token. Use --token flag or TYPEWRITER_TOKEN environment variable. ↓

cause Missing or invalid API token; v9+ requires Public API Token.

fix

Obtain a Public API Token from Segment workspace settings and pass via --token flag or TYPEWRITER_TOKEN env variable.

error Error: /dev/tty is not available. Interactive prompts require a TTY. ↓

cause Running in CI or non-interactive shell without a TTY.

fix

Use non-interactive mode with npx typewriter build --token YOUR_TOKEN --path plan.json. Add --no-interactive if available.

Warnings

breaking v8.0.0 dropped support for analytics-ios and analytics-android. Migrate to analytics-swift and analytics-kotlin. ↓

fix Use npx typewriter@7 build for legacy support; update to supported Segment SDKs.

breaking v9.0.0 replaced analytics SDKs with @segment/analytics-next and @segment/analytics-node. Existing generated clients break. ↓

fix Regenerate clients with npx typewriter build after upgrading to v9.

deprecated API token authentication is deprecated; use Public API Token instead (v9.0.0+). ↓

fix Replace Segment Config API Token with a Public API Token in typewriter.yml or environment.

gotcha Typewriter CLI uses interactive prompts. In CI environments, ensure TTY availability or use non-interactive flags. ↓

fix Use npx typewriter build --token <PUBLIC_TOKEN> --path <PLAN_PATH> for non-interactive mode (requires v9.1.0+).

gotcha Generated client may have TypeScript errors if using strict mode due to 'object is possibly undefined' in event properties (fixed in v8.0.5). ↓

fix Upgrade to v8.0.5 or later to resolve the issue.

breaking v8.0.0 changed the generated file structure and type naming conventions. Existing custom code referencing old paths will break. ↓

fix Re-run typewriter init and adapt imports to new paths; custom prefixes/suffixes can be configured in typewriter.yml.

Install

npm install typewriter

yarn add typewriter

pnpm add typewriter

Imports

typewriter
wrong
```
npm install typewriter && node node_modules/.bin/typewriter
```
correct
```
npx typewriter init
```
CLI tool; use npx to run without installing globally. For automation, install locally and run via package.json scripts.
typewriter build
wrong
```
typewriter build --token MY_TOKEN
```
correct
```
npx typewriter build
```
Use npx for local installs. Flags like --token were added in v9.1.0; previous versions required environment variables.
typewriter.yml
wrong
```
Manually creating typewriter.yml from scratch
```
correct
```
npx typewriter init
```
The config file is auto-generated by init command. Manual creation is error-prone and unsupported.

Quickstart

Initialize a new Typewriter project, configure with a Segment tracking plan, and generate a typed analytics client using npx.

npx typewriter init
# Follow prompts to configure tracking plan and generate client
npx typewriter build
# Generated client will be in ./typewriter/