V4 worker pipeline package

packages/transformers-webworker/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+types
+coverage
+*.log
+.DS_Store

packages/transformers-webworker/README.md

@@ -0,0 +1,110 @@
+# @huggingface/transformers-webworker
+
+Web Worker utilities for Transformers.js - a lightweight package designed to be used in Web Workers.
+
+## Installation
+
+You need to install both this package and the main transformers package:
+
+```bash
+npm install @huggingface/transformers @huggingface/transformers-webworker
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @huggingface/transformers @huggingface/transformers-webworker
+```
+
+## Usage
+
+This package provides utilities for using Transformers.js pipelines in Web Workers.
+
+### In Your Main Thread
+
+Use `webWorkerPipeline` to communicate with a Web Worker running a pipeline:
+
+```typescript
+import { webWorkerPipeline } from '@huggingface/transformers-webworker';
+
+// Create your worker
+const worker = new Worker('./worker.js');
+
+// Initialize the pipeline with options
+const classifier = await webWorkerPipeline(
+  worker,
+  'sentiment-analysis',
+  'Xenova/distilbert-base-uncased-finetuned-sst-2-english',
+  {
+    // Options like progress_callback are supported via callback bridge
+    progress_callback: (progress) => {
+      console.log('Progress:', progress);
+    }
+  }
+);
+
+// Use it like a regular pipeline
+const result = await classifier('I love this!');
+console.log(result);
+```
+
+### In Your Web Worker
+
+Use `webWorkerPipelineHandler` to handle pipeline requests:
+
+```typescript
+// worker.js
+import { webWorkerPipelineHandler } from '@huggingface/transformers-webworker';
+
+const handler = webWorkerPipelineHandler();
+self.onmessage = handler.onmessage;
+```
+
+> **Note:** The handler internally uses `pipeline` from `@huggingface/transformers` to create and cache pipeline instances.
+
+## Options and Limitations
+
+### Function Callbacks
+
+Function callbacks like `progress_callback` are automatically handled via a callback bridge and will execute in the main thread:
+
+```typescript
+const pipe = await webWorkerPipeline(worker, 'text-generation', 'model', {
+  progress_callback: (progress) => {
+    console.log('Loading:', progress);
+  }
+});
+```
+
+### GPU Acceleration
+
+Use the `device` parameter to enable GPU acceleration. The worker will handle GPU context creation:
+
+```typescript
+// ✅ Correct: Use device parameter
+await webWorkerPipeline(worker, 'text-generation', 'model', {
+  device: 'webgpu'  // or 'webnn'
+});
+
+// ❌ Incorrect: Don't pass GPU objects in session_options
+await webWorkerPipeline(worker, 'text-generation', 'model', {
+  session_options: {
+    executionProviders: [{ name: 'webgpu', device: gpuDevice }]  // Won't work!
+  }
+});
+```
+
+**Note:** `session_options` cannot contain GPU devices, WebNN contexts, or typed arrays as these are not serializable across worker boundaries.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Development mode with watch
+pnpm dev
+```

packages/transformers-webworker/jest.config.mjs

@@ -0,0 +1,34 @@
+/*
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+export default {
+  clearMocks: true,
+  collectCoverage: true,
+  coverageDirectory: "coverage",
+  coveragePathIgnorePatterns: ["node_modules", "tests"],
+  coverageProvider: "v8",
+  roots: ["./tests/"],
+  preset: "ts-jest/presets/default-esm",
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+        tsconfig: {
+          moduleResolution: "node",
+          esModuleInterop: true,
+          skipLibCheck: true,
+          isolatedModules: true,
+        },
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "mjs"],
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+};

packages/transformers-webworker/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@huggingface/transformers-webworker",
+  "version": "0.0.1",
+  "description": "Web Worker utilities for Transformers.js",
+  "main": "./dist/index.js",
+  "types": "./types/src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/src/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "format": "prettier --write . --ignore-path ../../.prettierignore",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore",
+    "typegen": "tsc --build",
+    "dev": "node scripts/dev.mjs",
+    "build": "node scripts/build.mjs && pnpm typegen",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huggingface/transformers.js.git"
+  },
+  "keywords": [
+    "transformers",
+    "transformers.js",
+    "webworker",
+    "huggingface",
+    "machine learning"
+  ],
+  "author": "Hugging Face",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/huggingface/transformers.js/issues"
+  },
+  "homepage": "https://github.com/huggingface/transformers.js#readme",
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.0.0"
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "workspace:*",
+    "@jest/globals": "^30.2.0",
+    "@types/jest": "^30.0.0",
+    "esbuild": "^0.27.2",
+    "jest": "^30.2.0",
+    "jest-environment-node": "^30.2.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "5.9.3"
+  },
+  "files": [
+    "src",
+    "dist",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/transformers-webworker/scripts/build.mjs

@@ -0,0 +1,25 @@
+import { OUT_DIR } from "./build/constants.mjs";
+import prepareOutDir from "../../../scripts/prepareOutDir.mjs";
+import { colors, createLogger } from "../../../scripts/logger.mjs";
+import { buildAll } from "./build/buildAll.mjs";
+
+const log = createLogger("transformers-webworker");
+
+log.section("BUILD");
+log.info("Building transformers-webworker with esbuild...\n");
+
+const startTime = performance.now();
+
+try {
+  prepareOutDir(OUT_DIR);
+
+  await buildAll(log);
+
+  const endTime = performance.now();
+  const duration = (endTime - startTime).toFixed(2);
+  log.success(`All builds completed in ${colors.bright}${duration}ms${colors.reset}\n`);
+} catch (error) {
+  log.error(`Build failed: ${error.message}`);
+  console.error(error);
+  process.exit(1);
+}

packages/transformers-webworker/scripts/build/buildAll.mjs

@@ -0,0 +1,44 @@
+import { build as esbuild } from "esbuild";
+import path from "node:path";
+import { OUT_DIR, ROOT_DIR, getEsbuildProdConfig } from "./constants.mjs";
+import { reportSize } from "../../../../scripts/reportSize.mjs";
+import { colors } from "../../../../scripts/logger.mjs";
+import { BUILD_TARGETS } from "./targets.mjs";
+
+/**
+ * Helper function to create build configurations.
+ */
+async function buildTarget({ name = "", suffix = ".js", format = "esm", externalModules = [] }, log) {
+  const regularFile = `index${name}${suffix}`;
+  const minFile = `index${name}.min${suffix}`;
+
+  log.build(`Building ${colors.bright}${regularFile}${colors.reset}...`);
+  await esbuild({
+    ...getEsbuildProdConfig(ROOT_DIR),
+    format,
+    outfile: path.join(OUT_DIR, regularFile),
+    external: externalModules,
+  });
+  reportSize(path.join(OUT_DIR, regularFile), log);
+
+  log.build(`Building ${colors.bright}${minFile}${colors.reset}...`);
+  await esbuild({
+    ...getEsbuildProdConfig(ROOT_DIR),
+    format,
+    outfile: path.join(OUT_DIR, minFile),
+    minify: true,
+    external: externalModules,
+    legalComments: "none",
+  });
+  reportSize(path.join(OUT_DIR, minFile), log);
+}
+
+/**
+ * Build all targets for production
+ */
+export async function buildAll(log) {
+  for (const target of BUILD_TARGETS) {
+    log.section(target.name);
+    await buildTarget(target.config, log);
+  }
+}

packages/transformers-webworker/scripts/build/buildAllWithWatch.mjs

@@ -0,0 +1,44 @@
+import { context } from "esbuild";
+import path from "node:path";
+import { rebuildPlugin } from "../../../../scripts/rebuildPlugin.mjs";
+import { OUT_DIR, ROOT_DIR, getEsbuildDevConfig } from "./constants.mjs";
+import { BUILD_TARGETS } from "./targets.mjs";
+
+/**
+ * Create an esbuild context for a single build target
+ */
+async function createBuildContext(targetName, targetConfig, log) {
+  const { name, suffix, format, externalModules } = targetConfig;
+  const outputFile = `index${name}${suffix}`;
+
+  const plugins = [rebuildPlugin(targetName, log)];
+
+  return context({
+    ...getEsbuildDevConfig(ROOT_DIR),
+    format,
+    outfile: path.join(OUT_DIR, outputFile),
+    external: externalModules,
+    plugins,
+  });
+}
+
+/**
+ * Build all targets in watch mode for development
+ * @returns {Promise<Array>} Array of esbuild contexts that can be disposed later
+ */
+export async function buildAllWithWatch(log) {
+  log.dim("Creating build contexts...\n");
+
+  // Create contexts for all targets
+  const contexts = await Promise.all(BUILD_TARGETS.map((target) => createBuildContext(target.name, target.config, log)));
+
+  log.dim("Starting initial build...\n");
+
+  // Wait for the initial builds to complete
+  await Promise.all(contexts.map((ctx) => ctx.rebuild()));
+
+  // Start watching all targets
+  await Promise.all(contexts.map((ctx) => ctx.watch()));
+
+  return contexts;
+}

packages/transformers-webworker/scripts/build/constants.mjs

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DIST_FOLDER = "dist";
+export const EXTERNAL_MODULES = ["@huggingface/transformers"];
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const ROOT_DIR = path.join(__dirname, "../..");
+export const OUT_DIR = path.join(ROOT_DIR, DIST_FOLDER);
+
+export const getEsbuildDevConfig = (rootDir) => ({
+  bundle: true,
+  treeShaking: true,
+  logLevel: "info",
+  entryPoints: [path.join(rootDir, "src/index.ts")],
+  platform: "browser",
+  format: "esm",
+  sourcemap: true,
+});
+
+export const getEsbuildProdConfig = (rootDir) => ({
+  ...getEsbuildDevConfig(rootDir),
+  logLevel: "warning",
+  sourcemap: false,
+});

packages/transformers-webworker/scripts/build/targets.mjs

@@ -0,0 +1,17 @@
+import { EXTERNAL_MODULES } from "./constants.mjs";
+
+/**
+ * Build target configuration
+ * Each target defines a specific build variant
+ */
+export const BUILD_TARGETS = [
+  {
+    name: "Web Worker Build (ESM)",
+    config: {
+      name: "",
+      suffix: ".js",
+      format: "esm",
+      externalModules: EXTERNAL_MODULES,
+    },
+  },
+];