@farm.js/partytown 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,114 @@
+# `@farm.js/partytown`
+
+Run explicitly opted-in third-party scripts in a web worker with
+[Partytown](https://partytown.qwik.dev/), while Farm owns the development and production asset
+setup.
+
+## Install
+
+```bash
+pnpm add @farm.js/partytown
+```
+
+The Partytown runtime is included. Applications do not need to install `@qwik.dev/partytown`
+separately.
+
+## Use
+
+Create one typed bridge that can be imported by both the Farm config and browser components:
+
+```ts
+// src/lib/analytics.ts
+import { defineForward } from "@farm.js/partytown/client";
+
+export const track =
+  defineForward<
+    (event: string, options?: { props?: Record<string, string | number | boolean> }) => void
+  >("plausible");
+```
+
+```ts
+// farm.config.ts
+import { defineConfig } from "@farm.js/core";
+import { partytown } from "@farm.js/partytown";
+import { track } from "./src/lib/analytics";
+
+export default defineConfig({
+  plugins: [partytown({ forward: [track] })],
+});
+```
+
+Mark only the vendor scripts that should move to the worker:
+
+```tsx
+// src/app/layout.tsx
+import type { LayoutProps } from "@farm.js/core";
+
+export default function RootLayout({ children }: LayoutProps) {
+  return (
+    <>
+      <script
+        type="text/partytown"
+        defer
+        data-domain="yourdomain.com"
+        src="https://plausible.io/js/script.js"
+      />
+      <main>{children}</main>
+    </>
+  );
+}
+```
+
+```tsx
+"use client";
+
+import { track } from "../lib/analytics";
+
+export function UpgradeButton() {
+  return <button onClick={() => track("Upgrade", { props: { plan: "pro" } })}>Upgrade</button>;
+}
+```
+
+`defineForward()` is fire-and-forget. It preserves the argument types supplied by the application,
+but its return type is always `void` because a worker call cannot synchronously return a vendor SDK
+result.
+
+## Options
+
+```ts
+partytown({
+  forward: [track, "dataLayer.push"],
+  debug: false,
+  fallbackTimeout: 4_000,
+  strictProxyHas: true,
+});
+```
+
+- `forward` lists only the global calls the browser must queue and send to the worker.
+- `debug` defaults to `true` in development and `false` in production.
+- `fallbackTimeout` controls how long Partytown waits before running opted-in scripts on the main
+  thread. Use `0` to disable that fallback.
+- `strictProxyHas` is an escape hatch for scripts that rely on strict JavaScript `in` behavior.
+
+Pass `{ preserveBehavior: true }` to `defineForward()` only when an existing main-thread function
+must also run:
+
+```ts
+const push = defineForward<(event: Record<string, unknown>) => number>("dataLayer.push", {
+  preserveBehavior: true,
+});
+```
+
+The typed caller still returns `void`.
+
+## Behavior and limits
+
+- Farm serves the Partytown bootstrap and worker files from the app's own `~partytown` path in
+  development and copies them into the correct Nitro public output for production and `basePath`.
+- The bootstrap is an external same-origin script, so the plugin does not add plugin-owned inline
+  JavaScript. Vendor origins may still need to be allowed by the application's CSP.
+- Scripts remain on the main thread unless the application marks them with `type="text/partytown"`.
+- DOM-heavy widgets, consent UIs, and SDK methods that synchronously return values may not be good
+  worker candidates. Leave those as normal scripts.
+- Injecting the required head bootstrap uses Farm's final HTML transform, so enabling this plugin
+  buffers the rendered document instead of preserving streamed HTML delivery.

package/dist/build.d.ts

@@ -0,0 +1,26 @@
+import type { ResolvedPartytownOptions } from "./config.js";
+export declare const PARTYTOWN_DIRECTORY = "~partytown";
+export declare const PARTYTOWN_BOOTSTRAP = "farm-partytown.js";
+export interface PartytownBuildInput {
+    outputDir: string;
+    publicDir?: string;
+    preset: string;
+    basePath: string;
+    options: ResolvedPartytownOptions;
+}
+export interface PartytownBuildResult {
+    assetsDir: string;
+    bootstrapPath: string;
+    bootstrapUrl: string;
+}
+export declare function writePartytownBuildArtifacts(input: PartytownBuildInput): Promise<PartytownBuildResult>;
+export declare function createPartytownBootstrap(options: ResolvedPartytownOptions, basePath: string, isDev: boolean): string;
+export declare function injectPartytownBootstrap(html: string, bootstrapUrl: string): string;
+export declare function readPartytownDevAsset(pathname: string, basePath: string, options: ResolvedPartytownOptions): Promise<{
+    body: Buffer | string;
+    contentType: string;
+} | undefined>;
+export declare function normalizeBasePath(value: string | undefined): string;
+export declare function partytownAssetUrl(file: string, basePath: string): string;
+export declare function resolvePartytownPublicDir(outputDir: string, preset: string): string;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE5D,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAChD,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAgB/B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,MAAM,CAeR;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAMnF;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CA8BrE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAUnE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIxE;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnF"}

package/dist/build.js

@@ -0,0 +1,117 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { partytownSnippet } from "@qwik.dev/partytown/integration";
+import { copyLibFiles, libDirPath } from "@qwik.dev/partytown/utils";
+export const PARTYTOWN_DIRECTORY = "~partytown";
+export const PARTYTOWN_BOOTSTRAP = "farm-partytown.js";
+export async function writePartytownBuildArtifacts(input) {
+    const publicDir = input.publicDir ?? resolvePartytownPublicDir(input.outputDir, input.preset);
+    const basePath = normalizeBasePath(input.basePath);
+    const relativeAssetsDir = path.posix.join(basePath.slice(1), PARTYTOWN_DIRECTORY);
+    const assetsDir = path.join(publicDir, ...relativeAssetsDir.split("/"));
+    const debug = input.options.debug ?? false;
+    await copyLibFiles(assetsDir, { debugDir: debug });
+    const bootstrapPath = path.join(assetsDir, PARTYTOWN_BOOTSTRAP);
+    await writeFile(bootstrapPath, createPartytownBootstrap(input.options, basePath, false), "utf8");
+    return {
+        assetsDir,
+        bootstrapPath,
+        bootstrapUrl: partytownAssetUrl(PARTYTOWN_BOOTSTRAP, basePath),
+    };
+}
+export function createPartytownBootstrap(options, basePath, isDev) {
+    const config = {
+        lib: partytownAssetUrl("", basePath),
+        debug: options.debug ?? isDev,
+    };
+    const forward = options.forward.map(({ path: forwardPath, preserveBehavior }) => preserveBehavior
+        ? [forwardPath, { preserveBehavior: true }]
+        : forwardPath);
+    if (forward.length > 0)
+        config.forward = forward;
+    if (options.fallbackTimeout !== undefined)
+        config.fallbackTimeout = options.fallbackTimeout;
+    if (options.strictProxyHas !== undefined)
+        config.strictProxyHas = options.strictProxyHas;
+    return `${partytownSnippet(config)}\n`;
+}
+export function injectPartytownBootstrap(html, bootstrapUrl) {
+    if (html.includes("data-farm-partytown"))
+        return html;
+    const closingHead = html.search(/<\/head\s*>/i);
+    if (closingHead < 0)
+        return html;
+    const tag = `<script src="${escapeHtmlAttribute(bootstrapUrl)}" data-farm-partytown></script>`;
+    return `${html.slice(0, closingHead)}${tag}${html.slice(closingHead)}`;
+}
+export async function readPartytownDevAsset(pathname, basePath, options) {
+    const prefix = partytownAssetUrl("", basePath);
+    if (!pathname.startsWith(prefix))
+        return undefined;
+    let relativePath;
+    try {
+        relativePath = decodeURIComponent(pathname.slice(prefix.length));
+    }
+    catch {
+        return undefined;
+    }
+    if (!relativePath || relativePath.includes("\\"))
+        return undefined;
+    if (relativePath === PARTYTOWN_BOOTSTRAP) {
+        return {
+            body: createPartytownBootstrap(options, basePath, true),
+            contentType: "text/javascript; charset=utf-8",
+        };
+    }
+    const libraryDir = path.resolve(libDirPath());
+    const assetPath = path.resolve(libraryDir, relativePath);
+    if (!assetPath.startsWith(`${libraryDir}${path.sep}`))
+        return undefined;
+    try {
+        return {
+            body: await readFile(assetPath),
+            contentType: contentTypeFor(relativePath),
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export function normalizeBasePath(value) {
+    if (!value || value === "/")
+        return "/";
+    if (!value.startsWith("/") || /[<>"'?#\\]/.test(value)) {
+        throw new TypeError("partytown requires basePath to be a safe absolute URL path");
+    }
+    const segments = value.split("/").filter(Boolean);
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new TypeError("partytown requires basePath without dot path segments");
+    }
+    return `/${segments.join("/")}`;
+}
+export function partytownAssetUrl(file, basePath) {
+    const base = normalizeBasePath(basePath);
+    const prefix = base === "/" ? "" : base;
+    return `${prefix}/${PARTYTOWN_DIRECTORY}/${file}`;
+}
+export function resolvePartytownPublicDir(outputDir, preset) {
+    return path.join(outputDir, preset.startsWith("vercel") ? "static" : "public");
+}
+function contentTypeFor(file) {
+    if (file.endsWith(".js"))
+        return "text/javascript; charset=utf-8";
+    if (file.endsWith(".html"))
+        return "text/html; charset=utf-8";
+    if (file.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    return "application/octet-stream";
+}
+function escapeHtmlAttribute(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import { type PartytownForward, type PartytownForwardOptions } from "./shared.js";
+export type { PartytownForward, PartytownForwardOptions };
+/**
+ * Create a typed caller for a global function forwarded to Partytown.
+ * The same value can be passed to `partytown({ forward: [...] })` and called
+ * from browser code without declaring a vendor global on `window`.
+ */
+export declare function defineForward<T extends (...args: any[]) => unknown>(path: string, options?: PartytownForwardOptions): PartytownForward<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EACjE,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAAC,CAAC,CAAC,CA4BrB"}

package/dist/client.js

@@ -0,0 +1,36 @@
+import { markPartytownForward, validateForwardPath, } from "./shared.js";
+/**
+ * Create a typed caller for a global function forwarded to Partytown.
+ * The same value can be passed to `partytown({ forward: [...] })` and called
+ * from browser code without declaring a vendor global on `window`.
+ */
+export function defineForward(path, options = {}) {
+    const resolvedPath = validateForwardPath(path);
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw new TypeError("partytown forward options must be an object");
+    }
+    if (options.preserveBehavior !== undefined && typeof options.preserveBehavior !== "boolean") {
+        throw new TypeError("partytown forward preserveBehavior must be boolean");
+    }
+    const preserveBehavior = options.preserveBehavior ?? false;
+    const segments = resolvedPath.split(".");
+    const forward = (...args) => {
+        if (typeof window === "undefined")
+            return;
+        let owner = window;
+        for (let index = 0; index < segments.length - 1; index += 1) {
+            if ((typeof owner !== "object" && typeof owner !== "function") || owner === null)
+                return;
+            owner = Reflect.get(owner, segments[index]);
+        }
+        if ((typeof owner !== "object" && typeof owner !== "function") || owner === null)
+            return;
+        const callable = Reflect.get(owner, segments.at(-1));
+        if (typeof callable === "function")
+            Reflect.apply(callable, owner, args);
+    };
+    return markPartytownForward(forward, {
+        path: resolvedPath,
+        preserveBehavior,
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+import type { PartytownForward } from "./shared.js";
+export type PartytownForwardInput = string | PartytownForward<(...args: any[]) => unknown>;
+export interface PartytownOptions {
+    /** Global calls that should be forwarded from the main thread to the worker. */
+    forward?: readonly PartytownForwardInput[];
+    /** Use Partytown's debug runtime. Defaults to true in development and false in production. */
+    debug?: boolean;
+    /** Milliseconds before Partytown falls back to the main thread. Set to 0 to disable fallback. */
+    fallbackTimeout?: number;
+    /** Use strict proxy `has` behavior for scripts that require it. */
+    strictProxyHas?: boolean;
+}
+export interface ResolvedPartytownForward {
+    path: string;
+    preserveBehavior: boolean;
+}
+export interface ResolvedPartytownOptions {
+    forward: ResolvedPartytownForward[];
+    debug?: boolean;
+    fallbackTimeout?: number;
+    strictProxyHas?: boolean;
+}
+export declare function resolvePartytownOptions(options: PartytownOptions): ResolvedPartytownOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,gBAAgB,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,CAAC;AAE3F,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,8FAA8F;IAC9F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,wBAAwB,CA0C3F"}

package/dist/config.js

@@ -0,0 +1,41 @@
+import { readPartytownForward, validateForwardPath } from "./shared.js";
+export function resolvePartytownOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("partytown options must be an object");
+    }
+    if ("enabled" in options) {
+        throw new TypeError("partytown does not accept enabled; remove partytown() from plugins to disable it");
+    }
+    assertBoolean(options.debug, "debug");
+    assertBoolean(options.strictProxyHas, "strictProxyHas");
+    if (options.fallbackTimeout !== undefined &&
+        (!Number.isInteger(options.fallbackTimeout) || options.fallbackTimeout < 0)) {
+        throw new TypeError("partytown fallbackTimeout must be a non-negative integer");
+    }
+    if (options.forward !== undefined && !Array.isArray(options.forward)) {
+        throw new TypeError("partytown forward must be an array");
+    }
+    const forwards = new Map();
+    for (const input of options.forward ?? []) {
+        const descriptor = readPartytownForward(input) ?? {
+            path: validateForwardPath(input),
+            preserveBehavior: false,
+        };
+        const previous = forwards.get(descriptor.path);
+        if (previous && previous.preserveBehavior !== descriptor.preserveBehavior) {
+            throw new TypeError(`partytown forward path ${JSON.stringify(descriptor.path)} has conflicting preserveBehavior settings`);
+        }
+        forwards.set(descriptor.path, descriptor);
+    }
+    return {
+        forward: [...forwards.values()],
+        debug: options.debug,
+        fallbackTimeout: options.fallbackTimeout,
+        strictProxyHas: options.strictProxyHas,
+    };
+}
+function assertBoolean(value, key) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError(`partytown ${key} must be boolean`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { type PartytownForwardInput, type PartytownOptions } from "./config.js";
+export type { PartytownForwardInput, PartytownOptions };
+export type { PartytownForward, PartytownForwardOptions } from "./client.js";
+/** Run explicitly marked third-party scripts in a Partytown web worker. */
+export declare function partytown(options?: PartytownOptions): import("@farm.js/core/plugin").FarmPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE7E,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,6CAkEvD"}

package/dist/index.js

@@ -0,0 +1,106 @@
+import { definePlugin } from "@farm.js/core/plugin";
+import { injectPartytownBootstrap, normalizeBasePath, partytownAssetUrl, PARTYTOWN_BOOTSTRAP, readPartytownDevAsset, writePartytownBuildArtifacts, } from "./build.js";
+import { resolvePartytownOptions, } from "./config.js";
+/** Run explicitly marked third-party scripts in a Partytown web worker. */
+export function partytown(options = {}) {
+    const resolved = resolvePartytownOptions(options);
+    let configuredBasePath = "/";
+    let configuredOutputDir = ".farm/.output";
+    return definePlugin({
+        name: "farm:partytown",
+        enforce: "pre",
+        configure(config) {
+            configuredBasePath = normalizeBasePath(config.basePath);
+            configuredOutputDir = `${config.root ?? "."}/.farm/.output`;
+            const vitePlugin = createPartytownDevPlugin(configuredBasePath, resolved);
+            return {
+                ...config,
+                vite: {
+                    ...config.vite,
+                    plugins: [vitePlugin, ...(config.vite?.plugins ?? [])],
+                },
+            };
+        },
+        render: {
+            html(html, _render, context) {
+                const basePath = normalizeBasePath(context.config.basePath ?? configuredBasePath);
+                return injectPartytownBootstrap(html, partytownAssetUrl(PARTYTOWN_BOOTSTRAP, basePath));
+            },
+        },
+        build: {
+            configure(nitroConfig) {
+                let copied = false;
+                const hooks = nitroConfig.hooks ?? {};
+                const previousPrerenderDone = hooks["prerender:done"];
+                const previousRollupBefore = hooks["rollup:before"];
+                const copy = async () => {
+                    if (copied)
+                        return;
+                    const built = await writePartytownBuildArtifacts({
+                        outputDir: nitroConfig.output?.dir ?? configuredOutputDir,
+                        publicDir: nitroConfig.output?.publicDir,
+                        preset: nitroConfig.preset ?? "node-server",
+                        basePath: configuredBasePath,
+                        options: resolved,
+                    });
+                    copied = true;
+                    console.info(`[farm:partytown] Copied worker runtime to ${built.bootstrapUrl}`);
+                };
+                return {
+                    ...nitroConfig,
+                    hooks: {
+                        ...hooks,
+                        "prerender:done": async (...args) => {
+                            await callConfiguredHooks(previousPrerenderDone, args);
+                            await copy();
+                        },
+                        "rollup:before": async (...args) => {
+                            await callConfiguredHooks(previousRollupBefore, args);
+                            if (isNitroPrerenderBuild(args[0]))
+                                return;
+                            await copy();
+                        },
+                    },
+                };
+            },
+        },
+    });
+}
+function createPartytownDevPlugin(basePath, options) {
+    return {
+        name: "farm:partytown-assets",
+        enforce: "pre",
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                if (request.method !== "GET" && request.method !== "HEAD")
+                    return next();
+                const pathname = new URL(request.url ?? "/", "http://farm.local").pathname;
+                try {
+                    const asset = await readPartytownDevAsset(pathname, basePath, options);
+                    if (!asset)
+                        return next();
+                    response.statusCode = 200;
+                    response.setHeader("Content-Type", asset.contentType);
+                    response.setHeader("Cache-Control", "no-store");
+                    response.end(request.method === "HEAD" ? undefined : asset.body);
+                }
+                catch (error) {
+                    next(error);
+                }
+            });
+        },
+    };
+}
+function isNitroPrerenderBuild(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const options = value.options;
+    return options?.preset === "nitro-prerender";
+}
+async function callConfiguredHooks(value, args) {
+    const hooks = Array.isArray(value) ? value : [value];
+    for (const hook of hooks) {
+        if (typeof hook === "function")
+            await hook(...args);
+    }
+}

package/dist/shared.d.ts

@@ -0,0 +1,16 @@
+export interface PartytownForwardOptions {
+    /** Also run an existing main-thread implementation before forwarding the call. */
+    preserveBehavior?: boolean;
+}
+export type PartytownForward<T extends (...args: any[]) => unknown> = ((...args: Parameters<T>) => void) & {
+    readonly path: string;
+    readonly preserveBehavior: boolean;
+};
+export interface PartytownForwardDescriptor {
+    path: string;
+    preserveBehavior: boolean;
+}
+export declare function markPartytownForward<T extends (...args: any[]) => unknown>(value: (...args: Parameters<T>) => void, descriptor: PartytownForwardDescriptor): PartytownForward<T>;
+export declare function readPartytownForward(value: unknown): PartytownForwardDescriptor | undefined;
+export declare function validateForwardPath(value: unknown): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,IAAI,CAAC,CACrE,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KACnB,IAAI,CAAC,GAAG;IACX,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EACxE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EACvC,UAAU,EAAE,0BAA0B,GACrC,gBAAgB,CAAC,CAAC,CAAC,CAOrB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,GAAG,SAAS,CAQ3F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiB1D"}

package/dist/shared.js

@@ -0,0 +1,35 @@
+const FORWARD_MARKER = Symbol.for("@farm.js/partytown.forward");
+const FORBIDDEN_PATH_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+export function markPartytownForward(value, descriptor) {
+    Object.defineProperties(value, {
+        [FORWARD_MARKER]: { value: true },
+        path: { value: descriptor.path, enumerable: true },
+        preserveBehavior: { value: descriptor.preserveBehavior, enumerable: true },
+    });
+    return value;
+}
+export function readPartytownForward(value) {
+    if (typeof value !== "function")
+        return undefined;
+    const candidate = value;
+    if (candidate[FORWARD_MARKER] !== true)
+        return undefined;
+    if (typeof candidate.path !== "string" || typeof candidate.preserveBehavior !== "boolean") {
+        return undefined;
+    }
+    return { path: candidate.path, preserveBehavior: candidate.preserveBehavior };
+}
+export function validateForwardPath(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new TypeError("partytown forward path must be a non-empty string");
+    }
+    const path = value.trim();
+    if (path.length > 256)
+        throw new TypeError("partytown forward path must be 256 characters or less");
+    const segments = path.split(".");
+    if (segments.some((segment) => !IDENTIFIER.test(segment) || FORBIDDEN_PATH_SEGMENTS.has(segment))) {
+        throw new TypeError(`partytown forward path ${JSON.stringify(path)} must contain only safe dotted JavaScript identifiers`);
+    }
+    return path;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@farm.js/partytown",
+  "version": "0.1.0-beta.0",
+  "description": "Run opted-in third-party scripts in a web worker in Farm.js applications",
+  "keywords": [
+    "analytics",
+    "farm.js",
+    "partytown",
+    "performance",
+    "web-worker"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-partytown"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@qwik.dev/partytown": "^0.14.4",
+    "@farm.js/core": "0.1.0-beta.91"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}