@unlockable/vite-plugin-unlock 0.1.0

package/dist/types-C3wWFKIK.d.cts

@@ -0,0 +1,105 @@
+/**
+ * HMR configuration for an unbundled target.
+ *
+ * When a package is excluded from pre-bundling (optimizeDeps.exclude),
+ * Vite loses the pre-bundled HMR boundary and processes raw source.
+ * These options restore fast HMR behaviour.
+ */
+interface TargetHmrConfig {
+    /**
+     * Rewrite a CSS import in the entry file.
+     * Useful when the source CSS contains `@tailwind` directives that would
+     * cause Vite to re-run PostCSS on every HMR update.
+     *
+     * @example { from: './index.css', to: '../dist/app.css' }
+     */
+    cssRedirect?: {
+        from: string;
+        to: string;
+    };
+    /**
+     * Inject `import.meta.hot.accept()` in the entry file.
+     * Prevents HMR propagation to the root when the entry re-exports
+     * mixed values (components + config objects).
+     */
+    entryBoundary?: boolean;
+}
+/**
+ * Full unlock target configuration.
+ */
+interface UnlockTarget {
+    /** npm package name to unlock (e.g. "@acme/dashboard") */
+    package: string;
+    /** Import alias for the package source (e.g. "~dashboard") -- auto-generated if omitted */
+    alias?: string;
+    /** Subdirectory within the package that contains source files (default: "src") */
+    srcDir?: string;
+    /**
+     * Entry redirect: remap dist entry to source entry.
+     * e.g. { from: "dist/app.mjs", to: "src/app.tsx" }
+     */
+    entryRedirect?: {
+        from: string;
+        to: string;
+    };
+    /** HMR optimizations for the unbundled target */
+    hmr?: TargetHmrConfig;
+}
+/**
+ * Shorthand: a string is expanded to `{ package: theString }`.
+ */
+type UnlockTargetInput = string | UnlockTarget;
+/**
+ * Match strategy for resolving overrides.
+ * - "basename": match by filename only (default)
+ * - "path": match by relative path
+ */
+type MatchStrategy = "basename" | "path";
+/**
+ * Conflict resolution strategy when multiple targets have the same filename.
+ * - "error": throw an error (default)
+ * - "warn": log a warning and use first match
+ * - "first": silently use first match
+ */
+type ConflictStrategy = "error" | "warn" | "first";
+/**
+ * Patch configuration: modify a target file using a config file.
+ */
+interface PatchConfig {
+    /** Pattern to match target file paths */
+    target: RegExp;
+    /** Config file basename to search in override dirs (without extension) */
+    configFile: string;
+    /** Transform function: receives original code + absolute config path, returns patched code */
+    apply(code: string, configPath: string): string;
+}
+/**
+ * Plugin options.
+ */
+interface UnlockOptions {
+    /** Packages to unlock */
+    targets: UnlockTargetInput[];
+    /** Directory containing override files (default: "./src/overrides") */
+    overrides?: string | string[];
+    /** Match strategy (default: "basename") */
+    match?: MatchStrategy;
+    /** Conflict handling when basename collides across targets (default: "error") */
+    onConflict?: ConflictStrategy;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** File extensions to consider (default: standard web extensions) */
+    extensions?: string[];
+    /** Patches: modify target files using config files from override dirs */
+    patches?: PatchConfig[];
+    /**
+     * Content patterns that trigger HMR boundary injection.
+     * If a file's code contains any of these strings, `import.meta.hot.accept()`
+     * is appended. Useful for mixed-export modules (component + config) that
+     * React Fast Refresh can't self-accept.
+     *
+     * @example ["defineRouteConfig", "defineWidgetConfig"]
+     */
+    hmrBoundaries?: string[];
+}
+
+export type { ConflictStrategy as C, MatchStrategy as M, PatchConfig as P, TargetHmrConfig as T, UnlockOptions as U, UnlockTarget as a, UnlockTargetInput as b };

package/dist/types-C3wWFKIK.d.ts

@@ -0,0 +1,105 @@
+/**
+ * HMR configuration for an unbundled target.
+ *
+ * When a package is excluded from pre-bundling (optimizeDeps.exclude),
+ * Vite loses the pre-bundled HMR boundary and processes raw source.
+ * These options restore fast HMR behaviour.
+ */
+interface TargetHmrConfig {
+    /**
+     * Rewrite a CSS import in the entry file.
+     * Useful when the source CSS contains `@tailwind` directives that would
+     * cause Vite to re-run PostCSS on every HMR update.
+     *
+     * @example { from: './index.css', to: '../dist/app.css' }
+     */
+    cssRedirect?: {
+        from: string;
+        to: string;
+    };
+    /**
+     * Inject `import.meta.hot.accept()` in the entry file.
+     * Prevents HMR propagation to the root when the entry re-exports
+     * mixed values (components + config objects).
+     */
+    entryBoundary?: boolean;
+}
+/**
+ * Full unlock target configuration.
+ */
+interface UnlockTarget {
+    /** npm package name to unlock (e.g. "@acme/dashboard") */
+    package: string;
+    /** Import alias for the package source (e.g. "~dashboard") -- auto-generated if omitted */
+    alias?: string;
+    /** Subdirectory within the package that contains source files (default: "src") */
+    srcDir?: string;
+    /**
+     * Entry redirect: remap dist entry to source entry.
+     * e.g. { from: "dist/app.mjs", to: "src/app.tsx" }
+     */
+    entryRedirect?: {
+        from: string;
+        to: string;
+    };
+    /** HMR optimizations for the unbundled target */
+    hmr?: TargetHmrConfig;
+}
+/**
+ * Shorthand: a string is expanded to `{ package: theString }`.
+ */
+type UnlockTargetInput = string | UnlockTarget;
+/**
+ * Match strategy for resolving overrides.
+ * - "basename": match by filename only (default)
+ * - "path": match by relative path
+ */
+type MatchStrategy = "basename" | "path";
+/**
+ * Conflict resolution strategy when multiple targets have the same filename.
+ * - "error": throw an error (default)
+ * - "warn": log a warning and use first match
+ * - "first": silently use first match
+ */
+type ConflictStrategy = "error" | "warn" | "first";
+/**
+ * Patch configuration: modify a target file using a config file.
+ */
+interface PatchConfig {
+    /** Pattern to match target file paths */
+    target: RegExp;
+    /** Config file basename to search in override dirs (without extension) */
+    configFile: string;
+    /** Transform function: receives original code + absolute config path, returns patched code */
+    apply(code: string, configPath: string): string;
+}
+/**
+ * Plugin options.
+ */
+interface UnlockOptions {
+    /** Packages to unlock */
+    targets: UnlockTargetInput[];
+    /** Directory containing override files (default: "./src/overrides") */
+    overrides?: string | string[];
+    /** Match strategy (default: "basename") */
+    match?: MatchStrategy;
+    /** Conflict handling when basename collides across targets (default: "error") */
+    onConflict?: ConflictStrategy;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** File extensions to consider (default: standard web extensions) */
+    extensions?: string[];
+    /** Patches: modify target files using config files from override dirs */
+    patches?: PatchConfig[];
+    /**
+     * Content patterns that trigger HMR boundary injection.
+     * If a file's code contains any of these strings, `import.meta.hot.accept()`
+     * is appended. Useful for mixed-export modules (component + config) that
+     * React Fast Refresh can't self-accept.
+     *
+     * @example ["defineRouteConfig", "defineWidgetConfig"]
+     */
+    hmrBoundaries?: string[];
+}
+
+export type { ConflictStrategy as C, MatchStrategy as M, PatchConfig as P, TargetHmrConfig as T, UnlockOptions as U, UnlockTarget as a, UnlockTargetInput as b };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@unlockable/vite-plugin-unlock",
+  "version": "0.1.0",
+  "description": "Universal Vite plugin to unlock and override any module from any npm package by filename convention",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./medusa": {
+      "import": {
+        "types": "./dist/medusa.d.ts",
+        "default": "./dist/medusa.js"
+      },
+      "require": {
+        "types": "./dist/medusa.d.cts",
+        "default": "./dist/medusa.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "yarn build"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "unlock",
+    "override",
+    "module-override",
+    "component-override",
+    "theming",
+    "customization",
+    "unlockable",
+    "medusa"
+  ],
+  "author": {
+    "name": "Olivier Belaud",
+    "url": "https://olivierbelaud.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/unlockablejs/vite-plugin-unlock#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unlockablejs/vite-plugin-unlock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unlockablejs/vite-plugin-unlock/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}