From 382ddf9aa1bd7bfaf9816ba73578a99a57c1fefc Mon Sep 17 00:00:00 2001
From: Paul Valladares <85648028+dreyfus92@users.noreply.github.com>
Date: Thu, 2 Jul 2026 20:50:59 -0600
Subject: [PATCH 1/2] feat(preferred): add tar-fs to replacements

---
 docs/modules/tar-fs.md   | 29 +++++++++++++++++++++++++++++
 manifests/preferred.json | 11 +++++++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/modules/tar-fs.md

diff --git a/docs/modules/tar-fs.md b/docs/modules/tar-fs.md
new file mode 100644
index 00000000..4e94e358
--- /dev/null
+++ b/docs/modules/tar-fs.md
@@ -0,0 +1,29 @@
+---
+description: Lighter alternative to the tar-fs package for packing and extracting tar archives on the filesystem
+---
+
+# Replacements for `tar-fs`
+
+## `modern-tar`
+
+[`tar-fs`](https://github.com/mafintosh/tar-fs) provides filesystem bindings on top of [`tar-stream`](https://github.com/mafintosh/tar-stream). [`modern-tar`](https://github.com/ayuhito/modern-tar) covers the same workflows through [`modern-tar/fs`](https://github.com/ayuhito/modern-tar), with zero dependencies and built-in TypeScript types.
+
+Example:
+
+```js
+import tar from 'tar-fs' // [!code --]
+import { createReadStream, createWriteStream } from 'node:fs' // [!code ++]
+import { packTar, unpackTar } from 'modern-tar/fs' // [!code ++]
+import { pipeline } from 'node:stream/promises' // [!code ++]
+
+tar.pack('./my-directory').pipe(createWriteStream('my-tarball.tar')) // [!code --]
+await pipeline(packTar('./my-directory'), createWriteStream('my-tarball.tar')) // [!code ++]
+
+createReadStream('my-other-tarball.tar').pipe(
+  tar.extract('./my-other-directory')
+) // [!code --]
+await pipeline(
+  createReadStream('my-other-tarball.tar'),
+  unpackTar('./my-other-directory')
+) // [!code ++]
+```
diff --git a/manifests/preferred.json b/manifests/preferred.json
index 1311b946..bf0f41ac 100644
--- a/manifests/preferred.json
+++ b/manifests/preferred.json
@@ -2610,6 +2610,12 @@
       "replacements": ["util.stripVTControlCharacters", "Bun.stripANSI"],
       "url": {"type": "e18e", "id": "strip-ansi"}
     },
+    "tar-fs": {
+      "type": "module",
+      "moduleName": "tar-fs",
+      "replacements": ["modern-tar"],
+      "url": {"type": "e18e", "id": "tar-fs"}
+    },
     "teeny-request": {
       "type": "module",
       "moduleName": "teeny-request",
@@ -3311,6 +3317,11 @@
       "type": "documented",
       "replacementModule": "milliparsec"
     },
+    "modern-tar": {
+      "id": "modern-tar",
+      "type": "documented",
+      "replacementModule": "modern-tar"
+    },
     "mri": {"id": "mri", "type": "documented", "replacementModule": "mri"},
     "nano-staged": {
       "id": "nano-staged",

From 73b9874fd08cbd025c75c336efe88718619e98ab Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Fri, 3 Jul 2026 11:00:06 +0100
Subject: [PATCH 2/2] Update docs/modules/tar-fs.md

---
 docs/modules/tar-fs.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/modules/tar-fs.md b/docs/modules/tar-fs.md
index 4e94e358..27409c72 100644
--- a/docs/modules/tar-fs.md
+++ b/docs/modules/tar-fs.md
@@ -10,6 +10,7 @@ description: Lighter alternative to the tar-fs package for packing and extractin
 
 Example:
 
+<!-- prettier-ignore -->
 ```js
 import tar from 'tar-fs' // [!code --]
 import { createReadStream, createWriteStream } from 'node:fs' // [!code ++]
@@ -19,11 +20,11 @@ import { pipeline } from 'node:stream/promises' // [!code ++]
 tar.pack('./my-directory').pipe(createWriteStream('my-tarball.tar')) // [!code --]
 await pipeline(packTar('./my-directory'), createWriteStream('my-tarball.tar')) // [!code ++]
 
-createReadStream('my-other-tarball.tar').pipe(
-  tar.extract('./my-other-directory')
+createReadStream('my-other-tarball.tar').pipe( // [!code --]
+  tar.extract('./my-other-directory') // [!code --]
 ) // [!code --]
-await pipeline(
-  createReadStream('my-other-tarball.tar'),
-  unpackTar('./my-other-directory')
+await pipeline( // [!code ++]
+  createReadStream('my-other-tarball.tar'), // [!code ++]
+  unpackTar('./my-other-directory') // [!code ++]
 ) // [!code ++]
 ```