StructuredMerge TypeScript provides npm packages for editor integrations, web-hosted tools, Node services, and other JavaScript runtimes that need portable structured-merge behavior.
The workspace includes the core AST/review contracts, parser substrate support, format-specific merge packages, binary/ZIP planning helpers, provider adapters, and a TypeScript packaging recipe package.
Project links:
- Website: https://structuredmerge.org
- Implementations: https://structuredmerge.org/implementations.html
- Specification: https://github.com/structuredmerge/structuredmerge-spec
- Shared fixtures: https://github.com/structuredmerge/structuredmerge-fixtures
StructuredMerge TypeScript is a layered npm package family. The lower layers provide parser, range, AST, merge, and template contracts; format packages apply those contracts to specific languages and data formats; provider packages bind a format family to a parser or serializer; workflow packages package TypeScript project maintenance and Git-driver behavior.
Each package README keeps this section short and links here. This root guide is the implementation inventory for TypeScript users who need to choose packages, understand backend coverage, or wire a focused backend into a test suite.
The family is intentionally layered:
@structuredmerge/tree-haverprovides parser portability, backend discovery, byte ranges, and runtime capability reporting.@structuredmerge/ast-mergeprovides the cross-format merge substrate: shared contracts, diagnostics, review state, and execution reports.- Family packages such as
@structuredmerge/markdown-merge,@structuredmerge/yaml-merge, and@structuredmerge/toml-mergeown parser-neutral behavior for one format family. - Provider packages such as
@structuredmerge/markdown-it-merge,@structuredmerge/js-yaml-merge, and@structuredmerge/peggy-toml-mergebind those families to concrete JavaScript parser libraries.
| Package | Layer | What it provides |
|---|---|---|
@structuredmerge/tree-haver |
Parser substrate | Parser backend registry, byte ranges, node wrappers, source locations, and binary tree contracts. |
@structuredmerge/ast-merge |
Merge substrate | AST merge contracts, diagnostics, planning, review, replay, and nested merge vocabulary. |
@structuredmerge/ast-template |
Template substrate | Template/session transport contracts. |
@structuredmerge/ast-crispr |
Structured edits | AST edit recipes for generated blocks and template-owned regions. |
@structuredmerge/ast-merge-git |
Git integration | Merge-driver, diff-driver, conflict inspection, and language registry plumbing for smorg-ts. |
@structuredmerge/plain-merge |
Text | Plain-text fallback contracts. |
@structuredmerge/json-merge |
JSON and JSONC | Object/array-aware JSON merge behavior. |
@structuredmerge/yaml-merge |
YAML | YAML-family merge contracts. |
@structuredmerge/toml-merge |
TOML | TOML-family merge contracts. |
@structuredmerge/markdown-merge |
Markdown | Markdown-family merge contracts. |
@structuredmerge/ruby-merge |
Ruby source | Ruby source merge contracts. |
@structuredmerge/go-merge |
Go source | Go source merge contracts. |
@structuredmerge/javascript-merge |
JavaScript source | JavaScript source merge contracts. |
@structuredmerge/c-merge |
C source | C source merge contracts. |
@structuredmerge/cpp-merge |
C++ source | C++ source merge contracts. |
@structuredmerge/csharp-merge |
C# source | C# source merge contracts. |
@structuredmerge/java-merge |
Java source | Java source merge contracts. |
@structuredmerge/python-merge |
Python source | Python source merge contracts. |
@structuredmerge/rust-merge |
Rust source | Rust source merge contracts. |
@structuredmerge/typescript-merge |
TypeScript source | TypeScript source merge contracts. |
@structuredmerge/binary-merge |
Binary | Binary tree planning contracts. |
@structuredmerge/zip-merge |
Archives | ZIP archive planning helpers. |
@structuredmerge/js-yaml-merge |
YAML provider | Uses js-yaml as the YAML parser/emitter provider path. |
@structuredmerge/peggy-toml-merge |
TOML provider | Uses Peggy generated parser code as the TOML provider path. |
@structuredmerge/markdown-it-merge |
Markdown provider | Uses markdown-it as the Markdown parser provider path. |
@structuredmerge/typescript-compiler-merge |
TypeScript provider | Uses the TypeScript compiler API provider path. |
@structuredmerge/kettle-nodule |
Recipe tooling | npm workspace maintenance and package recipe helpers. |
Install the packages your tool needs:
pnpm add @structuredmerge/ast-merge @structuredmerge/json-mergeThe packages are published under the @structuredmerge npm scope.
The TypeScript implementation ships the implementation-specific smorg-ts
command. Use that name in git configuration unless a package manager or local
install has provided a smorg symlink.
Package-manager formulas may expose the selected implementation as smorg.
For a local user-created symlink:
ln -s "$(command -v smorg-ts)" ~/.local/bin/smorggit config merge.smorg-ts.driver 'smorg-ts merge-driver %O %A %B %P'
git config diff.smorg-ts.command 'smorg-ts diff-driver'
smorg-ts conflicts diff path/to/file-with-conflicts.go
smorg-ts languages --gitattributesmerge-driver updates Git's %A file by default, or writes to --output when
used outside git. diff-driver accepts both the two-argument local form and the
seven- or nine-argument forms Git passes to external diff commands.
conflicts diff reports conflict-marker regions in a file that already contains
Git conflict markers.
Semantic merge-driver coverage is fixture-backed for JSON. Other language and format paths are git-compatible command surfaces without semantic driver coverage.
Core:
@structuredmerge/tree-haver- parser substrate, byte ranges, backend adapters, and binary tree contracts.@structuredmerge/ast-merge- AST merge contracts, diagnostics, planning, review, replay, and nested-merge vocabulary.@structuredmerge/ast-template- template/session transport contracts.
Format libraries:
@structuredmerge/plain-merge@structuredmerge/json-merge@structuredmerge/yaml-merge@structuredmerge/toml-merge@structuredmerge/markdown-merge@structuredmerge/ruby-merge@structuredmerge/go-merge@structuredmerge/javascript-merge@structuredmerge/c-merge@structuredmerge/cpp-merge@structuredmerge/csharp-merge@structuredmerge/java-merge@structuredmerge/python-merge@structuredmerge/rust-merge@structuredmerge/typescript-merge@structuredmerge/binary-merge@structuredmerge/zip-merge
Provider and recipe packages:
@structuredmerge/js-yaml-merge@structuredmerge/peggy-toml-merge@structuredmerge/markdown-it-merge@structuredmerge/typescript-compiler-merge@structuredmerge/kettle-nodule
The TypeScript packages are developed against the shared StructuredMerge fixtures. Those fixtures define the cross-language behavior expected from the Go, TypeScript, Rust, and Ruby implementations. Conformance checks live in package tests and in the shared spec/fixture tooling rather than in a static status document.
Common checks:
mise run checkpnpm run checkpnpm test