{"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,"search_vec":"'18':34 '9.2.0':31 'activ':37 'analyt':10,68,108 'base':67 'browser':47 'cadenc':96 'catch':71 'central':62 'ci':66 'ci-bas':65 'cli':93 'client':11 'code':78 'compil':5,22 'compile-tim':21 'customiz':77 'deploy':75 'differenti':56 'distribut':89 'ensur':17 'event':26 'frequent':98 'generat':7,79 'includ':45,57 'instrument':72 'integr':58 'javascript':46,105 'key':55 'kotlin':51 'languag':44 'maintain':38 'minor':101 'mismatch':73 'multipl':43,100 'name':29 'nativ':54 'node':33,49 'oclif':92,106 'packag':83 'per':103 'plan':16,64 'prefixes/suffixes':81 'properti':28 'protocol':14 'react':53 'releas':95 'requir':32 'safeti':19 'segment':13,40,60,107 'ship':84 'strong':8 'support':42 'swift':50 'time':23 'tool':94 'track':15,63 'type':9,18,86 'typescript':85,109 'typewrit':1,2 'valid':24,69 'version':30,102 'year':104","created_at":"2026-05-01T13:50:36.673086+00:00","updated_at":"2026-05-01T13:50:36.673086+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"typewriter","cli_version":null,"type":"library","homepage":"https://segment.com/docs/protocols/typewriter/","github":"https://github.com/segmentio/typewriter","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/typewriter","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","testing","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}