Root export is not Worker/browser-safe because it eagerly imports Node-only file storage

[husayt]

TanStack AI version

0.1.3

Framework/Library version

@tanstack/ai-code-mode-skills

Describe the bug and the steps to reproduce it

@tanstack/ai-code-mode-skills v0.1.3 appears to be unsafe to import from Cloudflare Worker / browser-oriented builds, even when only using non-file-storage APIs such as createSkillManagementTools or createSkillsSystemPrompt.

The package root export (@tanstack/ai-code-mode-skills) eagerly imports createFileSkillStorage, which pulls in node:fs and node:path. In worker/browser bundlers this causes the build to fail before runtime.

Reproduction

In a Nuxt app targeting Cloudflare Pages / Workers, import a non-storage API from the package root:

import {
  createSkillManagementTools,
  createSkillsSystemPrompt,
} from "@tanstack/ai-code-mode-skills"

Then build for Cloudflare Pages:

nuxt build --preset=cloudflare_pages

Actual result

Build fails with:

RollupError: .../@tanstack/ai-code-mode-skills/dist/esm/storage/file-storage.js (2:9):
"join" is not exported by "__vite-browser-external", imported by
".../storage/file-storage.js"

1: import { rm, mkdir, writeFile, readFile } from "node:fs/promises";
2: import { join } from "node:path";
           ^
3: import { existsSync } from "node:fs";

Expected result

Importing non-Node APIs like createSkillManagementTools and createSkillsSystemPrompt from the package root should not force bundlers to include Node-only storage code.

At minimum, there should be a public worker/browser-safe subpath that exposes the non-storage helpers without pulling in node:fs / node:path.

Likely cause

The root entry eagerly imports createFileSkillStorage:

// dist/esm/index.js
import { createFileSkillStorage } from "./storage/file-storage.js";

And file-storage.js imports Node-only modules:

import { rm, mkdir, writeFile, readFile } from "node:fs/promises";
import { join } from "node:path";
import { existsSync } from "node:fs";

So even consumers that do not use file storage still get a root entry that is not safe for Worker/browser bundlers.

Suggested fixes

Any of these would help:

1. Remove Node-only storage exports from the root entry.
2. Expose worker-safe/public subpaths for non-storage APIs.
3. Use conditional exports (node vs browser / worker-safe entrypoints).
4. Keep file storage behind @tanstack/ai-code-mode-skills/storage only, without re-exporting it from ..

Environment

• @tanstack/ai-code-mode-skills: 0.1.3
• @tanstack/ai-code-mode: 0.1.3
• @tanstack/ai: 0.10.3
• Nuxt: 4.4.2
• Vite: 7.3.1
• Target: Cloudflare Pages / Workers
• Build preset: cloudflare_pages

Notes

This seems especially relevant for frameworks that build server code through Worker-compatible bundlers, where Node built-ins are externalized or shimmed for browser-like environments.

Your Minimal, Reproducible Example - (Sandbox Highly Recommended)

see description

Screenshots or Videos (Optional)

No response

Do you intend to try to help solve this bug with your own PR?

None

Terms & Code of Conduct

• I agree to follow this project's Code of Conduct
• I understand that if my bug cannot be reliable reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.