Onboarding: mattboldt/typed.js

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mattboldt/typed.js shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 18 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mattboldt/typed.js repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mattboldt/typed.js.

What it runs against: a local clone of mattboldt/typed.js — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mattboldt/typed.js | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 131 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>mattboldt/typed.js</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mattboldt/typed.js. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mattboldt/typed.js.git
#   cd typed.js
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mattboldt/typed.js and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mattboldt/typed.js(\\.git)?\\b" \\
  && ok "origin remote is mattboldt/typed.js" \\
  || miss "origin remote is not mattboldt/typed.js (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "src/typed.js" \\
  && ok "src/typed.js" \\
  || miss "missing critical file: src/typed.js"
test -f "src/initializer.js" \\
  && ok "src/initializer.js" \\
  || miss "missing critical file: src/initializer.js"
test -f "src/html-parser.js" \\
  && ok "src/html-parser.js" \\
  || miss "missing critical file: src/html-parser.js"
test -f "src/defaults.js" \\
  && ok "src/defaults.js" \\
  || miss "missing critical file: src/defaults.js"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 131 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~101d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mattboldt/typed.js"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Typed.js is a JavaScript library that animates text typing and backspacing effects in the DOM. It takes an array of strings and sequentially types them character-by-character at a configurable speed, then backspeaces and types the next string, creating a typewriter effect. The core lives in src/typed.js and is built with microbundle into three distribution formats (CJS, ESM, UMD) for use in browsers, Node.js, and modern frameworks like React. Single-file source architecture: src/typed.js is the entire library implementation, bundled by microbundle into three formats in dist/ (typed.cjs, typed.module.js, typed.umd.js). Documentation lives in docs/ (API.md), examples in assets/demos.js/css, and distribution includes TypeScript types (index.d.ts). The package exports CommonJS, ESM, and UMD to support legacy script tags, modern build tools, and React/Node.js environments simultaneously.

Who it's for

Web developers building portfolio sites, landing pages, and interactive web experiences who want to add engaging typewriter animations without writing animation logic. React developers, vanilla JS developers, and designers using CDN script tags all use this library. Contributors tend to be frontend engineers focused on UX animations.

Maturity & risk

Production-ready and actively maintained at v3.0.0. The project has explicit licensing tiers (GPL-3.0 free, paid commercial licenses available via Stripe), TypeScript definitions (index.d.ts), and multi-format builds (CJS/ESM/UMD). However, the codebase is relatively lean (~29KB of JavaScript) and build config relies on microbundle as a single build tool with no visible CI/CD pipeline file (only .travis.yml stub), suggesting moderate rather than enterprise-grade maintenance.

Single-maintainer risk under mattboldt; the dependency tree is minimal (only microbundle in devDeps) which reduces supply-chain exposure but also means build tooling updates are infrequent. No visible test suite in the file list (no test/ or tests/ directories), only demo files in assets/ and docs/, raising confidence concerns for refactoring. The .travis.yml file presence without visible recent CI logs suggests testing infrastructure may be dormant. Breaking changes between major versions are possible given the GPL/commercial licensing model.

Active areas of work

Version 3.0.0 is current. The repo structure shows maturity (commercial licensing, TypeScript definitions, multi-format builds) but visible file state suggests focus on stability rather than feature development. No open PRs or milestones are visible in the provided data, and the GitHub templates (.github/ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md, stale.yml) indicate a lightweight contribution workflow.

Get running

git clone https://github.com/mattboldt/typed.js.git
cd typed.js
npm install
npm run dev

This will start the microbundle watcher in development mode. Build for production with npm run build. The library exports from src/typed.js and generates dist/ bundles.

Daily commands: Development: npm run dev (watches src/typed.js with microbundle). Production build: npm run build (outputs dist/typed.{cjs,module.js,umd.js} and source maps). Documentation generation: npm run docs (uses documentation CLI to build HTML from JSDoc comments). No dev server is configured; examples are static HTML files in assets/.

Map of the codebase

• src/typed.js — Core typing animation engine—entry point for all initialization and animation logic; all contributors must understand the main state machine and lifecycle.
• src/initializer.js — Parses user options and sets up Typed instance configuration; critical for understanding how user input flows into the core engine.
• src/html-parser.js — Extracts and interprets HTML markup and special commands from input strings; essential for understanding how complex text sequences are handled.
• src/defaults.js — Defines all configuration defaults and their types; required reading for understanding valid options and their defaults.
• package.json — Build configuration with microbundle; defines module exports (CJS, ESM, UMD) and TypeScript types location.
• index.d.ts — TypeScript type definitions for public API; critical for developers integrating typed.js with TypeScript projects.
• docs/API.md — Complete public API documentation; required reference for understanding all configuration options, methods, and callbacks.

Components & responsibilities

• Typed (typed.js) (JavaScript class, requestAnimationFrame, DOM API) — Main state machine; manages typing/backspacing index, string queue, lifecycle callbacks, and RAF loop coordination.
  • Failure mode: If state variables (currentStringIndex, stringsIndex, etc.) become corrupt, animation stutters or resets unexpectedly.
• Initializer (initializer.js) (JavaScript, object/array manipulation) — Validates user options against defaults, extracts strings from DOM/array, parses HTML, and binds event listeners.
  • Failure mode: If options merge fails or HTML parsing crashes, instance never initializes; errors propagate to user.
• HTMLParser (html-parser.js) (Regex, DOM traversal, string manipulation) — Extracts text content and special commands (<speed>, <pause>, <class>, etc.) from user strings; executes commands during animation.
  • Failure mode: Malformed HTML tags cause silent skipping or incorrect command execution; edge cases in escaping may corrupt output.
• RAF Loop (typed-using-raf.js or typed.js) (requestAnimationFrame, timing calculations) — Calculates delta time, updates character index, dispatches DOM updates, handles pause logic, and detects string completion.
  • Failure mode: If delta time calculation is wrong, typing speed deviates; if loop never cancels, memory leaks occur (e.g., on page unload).
• DOM Interface (DOM API (textContent, classList, querySelectorAll)) — Renders typed text via textContent or HTML updates; applies class changes for styling hooks.
  • Failure mode: If target element is removed or becomes detached, updates silently fail or throw errors; XSS risk if user strings contain untrusted HTML.

Data flow

• User input (options object) → Initializer — Options (strings, speed, delay, etc.) are passed to Typed constructor and validated against defaults.

How to make changes

Add a new animation callback hook

1. Add the callback option name and type to src/defaults.js in the options object with validation rules (src/defaults.js)
2. Import and initialize the callback in src/initializer.js's setupEventListeners() or similar method (src/initializer.js)
3. Invoke the callback at the appropriate lifecycle point in src/typed.js (e.g., in typeLoop(), backspace(), or at completion) (src/typed.js)
4. Document the new callback in docs/API.md with signature, parameters, and usage example (docs/API.md)
5. Add type definition to index.d.ts in the Typed class or options interface (index.d.ts)

Add support for a new HTML command or tag

1. Add parsing logic for the new command/tag in src/html-parser.js parseHtmlTag() or similar method (src/html-parser.js)
2. Handle command execution in src/typed.js within the main animation loop where parsed HTML is processed (src/typed.js)
3. Add examples and documentation to docs/API.md under the HTML commands section (docs/API.md)
4. Update index.d.ts if the command introduces new configuration options or return types (index.d.ts)

Modify animation timing or easing behavior

1. Add timing-related option to src/defaults.js with description and default value (src/defaults.js)
2. Update src/initializer.js to validate and store the timing option on the instance (src/initializer.js)
3. Modify animation calculations in src/typed-using-raf.js or the typeLoop() in src/typed.js to apply the new timing logic (src/typed-using-raf.js)
4. Update docs/API.md with examples of the new timing behavior (docs/API.md)

Why these technologies

• requestAnimationFrame (RAF) — Ensures smooth 60fps typing animation synchronized with browser refresh cycles; avoids setTimeout jank and improves perceived performance.
• HTML parsing and special commands — Allows users to embed pauses, class changes, and other directives inline with text, enabling rich animation narratives without JavaScript.
• Microbundle for multi-format output — Single source generates CJS, ESM, and UMD builds, maximizing compatibility across CommonJS, ES modules, and legacy browser globals.
• TypeScript definitions (index.d.ts) — Provides first-class IDE autocomplete and compile-time type checking for TypeScript users without requiring a full TypeScript rewrite.

Trade-offs already made

• State machine in typed.js with string queue instead of promise-based async/await

  • Why: Simpler control flow for legacy browser support and smaller bundle size; easier to reason about concurrent typing operations.
  • Consequence: Developers must use callbacks (onComplete, onStringTyped, etc.) instead of awaiting; less modern async ergonomics but better backwards compatibility.

• Single-character-at-a-time DOM updates in typeLoop()

  • Why: Provides granular control over timing and allows per-character callbacks; simple to reason about.
  • Consequence: High DOM churn on fast typing speeds; potential performance bottleneck with very large strings (100k+ chars), though rare in practice.

• Inline HTML command parsing (e.g., <speed=50>, <pause=500>) instead of JSX or data attributes

  • Why: No build step or React dependency required; users define animations purely in strings.
  • Consequence: Syntax less discoverable than APIs; escaping HTML characters in typed strings requires additional care.

Non-goals (don't propose these)

• Real-time multi-user typing synchronization or collaborative editing
• Support for non-Latin scripts with complex text layout (RTL, combining diacritics)
• Server-side rendering or static HTML generation
• Accessibility features beyond semantic HTML (screen reader testing is not in scope)
• Mobile touch gesture recognition for controlling animation

Traps & gotchas

No visible test suite means manual testing and demo validation are the only quality gates; new contributors should test changes against assets/demos.html. The .travis.yml file exists but appears unused—check GitHub Actions or other CI if adding features. The library uses no runtime dependencies, so breaking changes to DOM APIs or timing behavior could affect older browser support silently. Commercial licensing (LIMITED_COMMERCIAL_LICENSE.md, UNLIMITED_COMMERCIAL_LICENSE.md) exists alongside GPL-3.0, so understand the dual-licensing implications before suggesting AGPL or proprietary code. The 'type: "module"' in package.json forces ESM-first syntax; CommonJS require() users depend on the dist/typed.cjs transpile output.

Architecture

Concepts to learn

• RequestAnimationFrame (rAF) scheduling — Typed.js likely uses rAF or setTimeout internally to schedule character rendering at the correct framerate; understanding frame-sync timing is essential for diagnosing jank, stutter, or backspacing speed issues
• DOM string sanitization and HTML escaping — The library accepts strings with HTML tags (e.g., '<i>First</i> sentence.') and XSS-unsafe content (e.g., '&'); understanding how src/typed.js parses, escapes, and renders these safely (or unsafely) is critical for security audits
• Multi-format module distribution (CJS/ESM/UMD) — The package.json exports field routes require(), import, and <script> tag consumers to different bundles; understanding bundler resolution and why all three formats are needed for backward compatibility and modern tooling is key to modifying build config
• TypeScript declaration file authoring (index.d.ts) — The library is JavaScript but ships with TypeScript definitions; contributors must keep index.d.ts in sync with src/typed.js API changes, and understand generic types for the options object and Typed class
• String tokenization and character-by-character iteration — The core animation depends on breaking strings into individual characters, handling multi-byte Unicode, HTML tag boundaries, and escape sequences; off-by-one errors here break typing accuracy for emoji or non-Latin scripts
• Event emitter pattern (if used internally) — The library likely uses custom events or callback patterns to notify users of typing lifecycle events (start, complete, reset); understanding how events are registered, fired, and cleaned up prevents memory leaks and ensures proper React integration
• Dual open-source licensing (GPL + Commercial) — The repo publishes under GPL-3.0 free (open-source projects) but offers paid Limited and Unlimited Commercial Licenses via Stripe; contributors must understand GPL copyleft implications and ensure new code is compatible with all three license tiers

Related repos

• BrianWangila/typing-effect — Alternative typing animation library using CSS animations instead of JavaScript character-by-character updates; solves the same problem with different performance tradeoffs
• sveltejs/svelte — Complementary framework that includes built-in animation directives; developers integrating Typed.js with Svelte need these patterns for proper lifecycle cleanup and reactivity
• vercel/next.js — Next.js is the dominant meta-framework for React; Typed.js users building server-side-rendered or static-exported sites need Next.js-specific integration patterns (useEffect cleanup, SSR safety)
• prettier/prettier — The repo uses .prettierrc; understanding Prettier's configuration and integration is necessary for contributing code that passes the project's formatting checks
• ecomfe/gsap-docs — GSAP is the industry standard for advanced JavaScript animations; developers familiar with Typed.js often upgrade to GSAP for more complex choreography, making cross-library pattern knowledge valuable

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit test suite for src/typed.js and related modules

The repo has no visible test directory or test scripts in package.json. With a typing animation library, core functionality like character-by-character typing, backspacing, timing, callback execution, and HTML parsing (src/html-parser.js) need regression coverage. This prevents bugs in animation loops and timing logic that affect user experience.

• [ ] Create tests/ directory with test runner (e.g., Vitest or Jest configured for ES modules)
• [ ] Add test script to package.json (e.g., 'test': 'vitest')
• [ ] Write tests for src/typed.js covering: initialization, start(), stop(), destroy(), typing speed variations
• [ ] Write tests for src/html-parser.js covering HTML tag parsing and sanitization
• [ ] Write tests for src/initializer.js covering configuration merging and defaults
• [ ] Add pre-commit hook or CI workflow to run tests on PR (since .travis.yml suggests CI was previously used)
• [ ] Document testing approach in .github/CONTRIBUTING.md

Add GitHub Actions workflow for continuous integration and automated releases

.travis.yml suggests the repo used Travis CI but modern typed.js should use GitHub Actions for free CI/CD. No workflow files exist in .github/workflows/. This should include: linting, building dist files, running tests, and automated npm releases on version bumps.

• [ ] Create .github/workflows/ci.yml for: npm install, npm run build, npm run docs, npm test (once tests exist)
• [ ] Create .github/workflows/release.yml triggered on version tag push to automatically publish to npm
• [ ] Ensure build step verifies dist/ files are up-to-date (catch out-of-sync builds)
• [ ] Add status badge to README.md linking to GitHub Actions
• [ ] Document release process in .github/CONTRIBUTING.md

Add TypeScript definitions validation and complete JSDoc/type coverage for src/

The repo exports index.d.ts TypeScript definitions but no visible validation that they match actual source code. With typed.js being a popular library, type safety matters. Additionally, src/typed.js, src/html-parser.js, and src/initializer.js should have complete JSDoc annotations that match the generated docs in docs/ and can be validated.

• [ ] Add dtslint or type-checking script (e.g., 'tsc --noEmit') to validate index.d.ts against src/typed.js
• [ ] Add full JSDoc comments to src/typed.js methods (setup, start, stop, destroy, reset, etc.) matching docs/API.md
• [ ] Add JSDoc comments to src/html-parser.js methods and parameters
• [ ] Add JSDoc comments to src/initializer.js for option object structure
• [ ] Integrate type-checking into CI workflow to catch type drift on PRs
• [ ] Update .github/CONTRIBUTING.md to require JSDoc comments on new features

Good first issues

• Add unit test suite for src/typed.js: The repository has no visible test/ directory or test files. Adding Jest or Vitest with test coverage for core functions (character typing, backspacing, string cycling, event emission) would improve confidence in refactoring and catch regressions. Start with happy-path tests for the constructor and basic typing lifecycle.
• Document all callback/event types in index.d.ts and docs/API.md: The file list shows docs/API.md exists but JSDoc comments in src/typed.js may not document all lifecycle callbacks (e.g., onStringTyped, onComplete, onReset). Audit the source code for undocumented events and add TypeScript overloads and markdown examples to the API docs for clarity.
• Add ESLint config and fix linting issues: No .eslintrc or linting tool is configured. Adding ESLint with a modern preset (e.g., eslint-config-standard or Google's style guide) and running it across src/typed.js and assets/demos.js would catch potential bugs and enforce consistency. Start with a basic config and fix any auto-fixable issues.

Top contributors

• @mattboldt — 77 commits
• @coliff — 3 commits
• @Orlandster — 3 commits
• @dfabreguette — 2 commits
• @seifsg — 2 commits

Recent commits

• b2d6a7d — Update README.md (mattboldt)
• 35580c9 — added logo (mattboldt)
• dfb2576 — update readme (mattboldt)
• 8d3156f — readme updates (mattboldt)
• d2a135a — upgraded packages (mattboldt)
• 4484fd7 — Added commercial license links (mattboldt)
• 6b83c47 — Added new GPL3 license (mattboldt)
• e3a49bb — Added latest docs (mattboldt)
• 025be26 — Append strings working (mattboldt)
• a6acab8 — WIP, appending strings during typing or after last string finished (mattboldt)

Security observations

The typed.js library has a moderate security posture with one significant concern: potential DOM-based XSS vulnerabilities inherent to a library that types user-supplied strings into the DOM. The codebase lacks production dependencies (positive) but has minimal security hardening. Critical areas of concern include input sanitization, supply chain management, and clear security guidance for users. The GPL-3.0 licensing model may create compliance risks for commercial users. Recommended actions: implement strict input validation/sanitization, establish a security vulnerability disclosure policy, add security headers to documentation sites, and provide explicit security guidance in the README.

• High · DOM-based XSS Risk in Typing Animation Library — src/typed.js, src/html-parser.js. A typing animation library that manipulates DOM content based on user input strings is inherently vulnerable to XSS attacks. If user-controlled strings are typed into the DOM without proper sanitization, malicious HTML/JavaScript can be injected and executed. The library name 'typed.js' suggests it types strings into elements, which typically involves innerHTML or similar DOM manipulation. Fix: Implement strict input validation and sanitization. Use textContent instead of innerHTML where possible. If HTML content must be supported, use a robust HTML sanitization library (e.g., DOMPurify). Provide clear security guidelines in documentation warning users about XSS risks when accepting user input.
• Medium · Minimal Dependency Management — package.json. The project has only one dev dependency (microbundle@^0.15.1) with a caret range (^), which allows minor and patch updates automatically. While microbundle is a reputable tool, the caret range could introduce unexpected changes. Additionally, there are no production dependencies specified, which is good, but the lack of package-lock.json or yarn.lock in the file list suggests potential supply chain risks. Fix: Use exact versions or tighter version constraints (e.g., ~0.15.1 instead of ^0.15.1) for dependencies. Ensure package-lock.json or yarn.lock is committed to version control. Regularly audit dependencies using 'npm audit' and keep microbundle updated.
• Medium · GPL-3.0 License Compliance Risk — LICENSE.txt, LIMITED_COMMERCIAL_LICENSE.md, package.json (license field). The project uses GPL-3.0 license with additional commercial licensing options. GPL-3.0 has copyleft requirements that can affect downstream users. The presence of LIMITED_COMMERCIAL_LICENSE.md suggests users may be unaware of licensing implications, and improper use could create legal issues. Fix: Ensure clear license headers in source files. Provide explicit licensing guidance in README. Clarify when commercial licenses are required. Document the implications of GPL-3.0 copyleft provisions for users.
• Low · Source Maps in Distribution — dist/typed.*.map files. The dist folder contains .map files (typed.cjs.map, typed.module.js.map, typed.umd.js.map), which expose source code in production. While convenient for debugging, source maps can aid attackers in finding vulnerabilities. Fix: Consider whether source maps are necessary in production builds. If they must be included, serve them separately with restricted access, or exclude them from npm packages. Use 'files' field in package.json to exclude .map files if not needed by users.
• Low · Missing Security Headers Configuration — .travis.yml, docs/assets/site.js. No evidence of security headers configuration (e.g., CSP, X-Frame-Options) in the codebase. This is relevant for the demo website and documentation. Fix: Configure security headers for the documentation and demo websites. Implement Content-Security-Policy headers to prevent XSS attacks. Add X-Frame-Options, X-Content-Type-Options, and other standard security headers.
• Low · No CHANGELOG or Security Policy — Repository root. No visible SECURITY.md file or documented security vulnerability disclosure process. Users have no clear channel to report security issues responsibly. Fix: Create a SECURITY.md file with instructions for reporting security vulnerabilities privately. Consider using GitHub's security advisory feature. Maintain a CHANGELOG documenting security fixes.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.