{"id":26558,"library":"typewriter","title":"Typewriter","description":"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.","status":"active","version":"9.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/segmentio/typewriter","tags":["javascript","oclif","segment","analytics","typescript"],"install":[{"cmd":"npm install typewriter","lang":"bash","label":"npm"},{"cmd":"yarn add typewriter","lang":"bash","label":"yarn"},{"cmd":"pnpm add typewriter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for generating browser analytics clients since v9.0.0","package":"@segment/analytics-next","optional":false},{"reason":"Required for generating Node.js analytics clients since v9.0.0","package":"@segment/analytics-node","optional":false}],"imports":[{"note":"CLI tool; use npx to run without installing globally. For automation, install locally and run via package.json scripts.","wrong":"npm install typewriter && node node_modules/.bin/typewriter","symbol":"typewriter","correct":"npx typewriter init"},{"note":"Use npx for local installs. Flags like --token were added in v9.1.0; previous versions required environment variables.","wrong":"typewriter build --token MY_TOKEN","symbol":"typewriter build","correct":"npx typewriter build"},{"note":"The config file is auto-generated by init command. Manual creation is error-prone and unsupported.","wrong":"Manually creating typewriter.yml from scratch","symbol":"typewriter.yml","correct":"npx typewriter init"}],"quickstart":{"code":"npx typewriter init\n# Follow prompts to configure tracking plan and generate client\nnpx typewriter build\n# Generated client will be in ./typewriter/\n","lang":"typescript","description":"Initialize a new Typewriter project, configure with a Segment tracking plan, and generate a typed analytics client using npx."},"warnings":[{"fix":"Use npx typewriter@7 build for legacy support; update to supported Segment SDKs.","message":"v8.0.0 dropped support for analytics-ios and analytics-android. Migrate to analytics-swift and analytics-kotlin.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Regenerate clients with npx typewriter build after upgrading to v9.","message":"v9.0.0 replaced analytics SDKs with @segment/analytics-next and @segment/analytics-node. Existing generated clients break.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Replace Segment Config API Token with a Public API Token in typewriter.yml or environment.","message":"API token authentication is deprecated; use Public API Token instead (v9.0.0+).","severity":"deprecated","affected_versions":">=9.0.0"},{"fix":"Use npx typewriter build --token <PUBLIC_TOKEN> --path <PLAN_PATH> for non-interactive mode (requires v9.1.0+).","message":"Typewriter CLI uses interactive prompts. In CI environments, ensure TTY availability or use non-interactive flags.","severity":"gotcha","affected_versions":">=8.0.0"},{"fix":"Upgrade to v8.0.5 or later to resolve the issue.","message":"Generated client may have TypeScript errors if using strict mode due to 'object is possibly undefined' in event properties (fixed in v8.0.5).","severity":"gotcha","affected_versions":">=8.0.0 <8.0.5"},{"fix":"Re-run typewriter init and adapt imports to new paths; custom prefixes/suffixes can be configured in typewriter.yml.","message":"v8.0.0 changed the generated file structure and type naming conventions. Existing custom code referencing old paths will break.","severity":"breaking","affected_versions":">=8.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npx typewriter init` first in your project root to generate the config, then run build from the same directory.","cause":"No typewriter.yml configuration file exists or command run from wrong directory.","error":"npx typewriter build: Error: Could not find typewriter.yml in current or parent directories"},{"fix":"Upgrade to typewriter >=8.0.5. If fixed, regenerate the client with `npx typewriter build`.","cause":"Generated client TypeScript error when event properties are undefined in tracking plan (common in older versions).","error":"TypeError: Cannot read properties of undefined (reading 'properties')"},{"fix":"Obtain a Public API Token from Segment workspace settings and pass via `--token` flag or `TYPEWRITER_TOKEN` env variable.","cause":"Missing or invalid API token; v9+ requires Public API Token.","error":"Error: You must provide a Public API Token. Use --token flag or TYPEWRITER_TOKEN environment variable."},{"fix":"Use non-interactive mode with `npx typewriter build --token YOUR_TOKEN --path plan.json`. Add `--no-interactive` if available.","cause":"Running in CI or non-interactive shell without a TTY.","error":"Error: /dev/tty is not available. Interactive prompts require a TTY."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}