typewriter

library9.2.0jsnpmunverified

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.

serialization testing devops

npm install typewriter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPEWRITER

typewriter

serializationjavascriptv9.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

typewriter

✓ npx typewriter init

✗ npm install typewriter && node node_modules/.bin/typewriter

CLI tool; use npx to run without installing globally. For automation, install locally and run via package.json scripts.

typewriter build

✓ npx typewriter build

✗ typewriter build --token MY_TOKEN

Use npx for local installs. Flags like --token were added in v9.1.0; previous versions required environment variables.

typewriter.yml

✓ npx typewriter init

✗ Manually creating typewriter.yml from scratch

The config file is auto-generated by init command. Manual creation is error-prone and unsupported.

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/

typewriter --version

Debug

Known issues

breakingv8.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.

affects: >=8.0.0

breakingv9.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.

affects: >=9.0.0

deprecatedAPI 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.

affects: >=9.0.0

gotchaTypewriter 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+).

affects: >=8.0.0

gotchaGenerated 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.

affects: >=8.0.0 <8.0.5

breakingv8.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.

affects: >=8.0.0

Errors

Common errors & fixes

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

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.

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

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: You must provide a Public API Token. Use --token flag or TYPEWRITER_TOKEN environment variable.

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: /dev/tty is not available. Interactive prompts require a TTY.

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.

Upgrade

Version history

9.2.0latest on npm

Audit

Dependencies

@segment/analytics-nextrequiredRequired for generating browser analytics clients since v9.0.0

@segment/analytics-noderequiredRequired for generating Node.js analytics clients since v9.0.0

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/segmentio/typewriter ↗

packagehttps://www.npmjs.com/package/typewriter ↗

homepagehttps://segment.com/docs/protocols/typewriter/ ↗