mountly-vite-plugin 1.0.0 → 1.2.2

package/README.md

@@ -0,0 +1,98 @@
+# mountly-vite-plugin
+
+Vite plugins for both ends of a [mountly](https://npmjs.com/package/mountly)
+setup: building a widget so other teams can load it, and configuring the host
+page that loads them.
+
+```bash
+pnpm add -D mountly-vite-plugin
+```
+
+## Building a widget
+
+One config produces two builds from the same source:
+
+```ts
+// vite.config.ts
+import { defineMountlyWidgetConfig } from "mountly-vite-plugin";
+
+export default defineMountlyWidgetConfig({
+  framework: "react",
+  entry: "src/index.ts",
+  verticalId: "billing",
+  featureExport: "checkout",
+  exposes: { "./Checkout": "src/Checkout.tsx" },
+});
+```
+
+- **`dist/index.js`** — React inlined. Drops onto any page, no host setup.
+- **`dist/peer.js`** — React external. The host supplies one copy through its
+  import map, so three widgets share it instead of shipping three.
+
+Widget authors pick neither; both are emitted, and the host decides which URL
+it points at.
+
+It also writes **`dist/mountly.manifest.fragment.json`**, the entry your CI
+merges into the host's manifest — including a `types` block naming what each
+entry exports, read from the TypeScript checker rather than guessed. Declaration
+files land in `dist/types/`, so a host that imports `billing/Checkout` gets real
+types for a module it never compiled.
+
+`vite build` outputs both, plus the fragment, with no separate build script.
+
+## Configuring the host
+
+```ts
+// vite.config.ts
+import { mountlyHostPlugin } from "mountly-vite-plugin";
+
+export default {
+  plugins: [mountlyHostPlugin({ manifest: "./mountly.manifest.json" })],
+};
+```
+
+The host plugin externalizes every remote the manifest declares — so Vite
+doesn't try to bundle code that lives on someone else's CDN — and injects the
+import map into the served HTML. Vite's `base` is applied to the map, so a site
+served from a subpath resolves correctly.
+
+Point it at fragments instead and it composes the manifest itself, which is
+useful in a monorepo where the remotes are built alongside the host:
+
+```ts
+mountlyHostPlugin({
+  verticals: [{ fragment: "./packages/billing/dist/mountly.manifest.fragment.json" }],
+});
+```
+
+## Individual plugins
+
+`defineMountlyWidgetConfig` is a preset over these, exported for when you need
+to compose them into a config you already own:
+
+| Export                          | Does                                                     |
+| ------------------------------- | -------------------------------------------------------- |
+| `mountlyHostPlugin`             | externalize remotes, inject the import map               |
+| `mountlyRemote`                 | build one vertical, emit its manifest fragment           |
+| `mountlyManifestFragmentPlugin` | emit the fragment and declarations for an existing build |
+| `mountlyCssAsText`              | import CSS as a string, for adopting into a shadow root  |
+| `getFrameworkPeerExternals`     | the externals list for a peer build                      |
+
+## TypeScript
+
+`mountlyManifestFragmentPlugin` reads exports from the TypeScript checker and
+drives `tsc` for declaration emit, so `typescript` is a peer dependency. Nearly
+every project that builds a widget already has it. Without it, the build still
+succeeds — the fragment is written without its `types` block, and typed remotes
+are unavailable until you install it.
+
+TypeScript 7 or later is required, since it uses the `typescript/unstable`
+checker API.
+
+## Documentation
+
+<https://mountly.dev/concepts/manifest-hosts/>
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -4,7 +4,10 @@ export { mountlyManifestFragmentPlugin, type ManifestFragmentPluginOptions } fro
 export type MountlyWidgetFramework = "react" | "vue" | "svelte";
 export declare function getFrameworkPeerExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
 export declare function getSelfContainedExternals(framework: MountlyWidgetFramework): Array<string | RegExp>;
-export declare function mountlyCssAsText(): Plugin;
+export interface MountlyCssAsTextOptions {
+    include?: string | RegExp | (string | RegExp)[];
+}
+export declare function mountlyCssAsText(options?: MountlyCssAsTextOptions): Plugin;
 export interface MountlyWidgetPluginOptions {
     framework?: MountlyWidgetFramework;
 }

package/dist/index.js

@@ -8,9 +8,20 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs";
 import { dirname, join, parse, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import { exportKeyToSubpath } from "mountly-manifest";
-import { API, SymbolFlags } from "typescript/unstable/sync";
+async function loadTypeScript() {
+  try {
+    return await import("typescript/unstable/sync");
+  } catch {
+    return void 0;
+  }
+}
 function tscBin() {
-  return join(dirname(fileURLToPath(import.meta.resolve("typescript/package.json"))), "bin", "tsc");
+  try {
+    const packageJson = fileURLToPath(import.meta.resolve("typescript/package.json"));
+    return join(dirname(packageJson), "bin", "tsc");
+  } catch {
+    return void 0;
+  }
 }
 function mountlyManifestFragmentPlugin(options) {
   let outDir = options.outDir ?? "dist";
@@ -25,10 +36,13 @@ function mountlyManifestFragmentPlugin(options) {
       dir = next;
     }
   }
-  function collectNamedExports(entries) {
+  async function collectNamedExports(entries) {
     const sources = entries.filter((entry) => /\.(?:[cm]?[jt]sx?)$/i.test(entry));
     const names = /* @__PURE__ */ new Map();
     if (sources.length === 0) return names;
+    const typescript = await loadTypeScript();
+    if (!typescript) return names;
+    const { API, SymbolFlags } = typescript;
     const api = new API();
     try {
       const snapshot = api.updateSnapshot({ openFiles: [...sources] });
@@ -64,16 +78,24 @@ function mountlyManifestFragmentPlugin(options) {
     return relative(rootDir, entry).replace(/\.(?:[cm]?[jt]sx?)$/i, ".d.ts");
   }
   function emitDeclarations(entry, exposeEntries) {
-    if (!entry) return { exportDeclarations: {} };
+    const tsc = tscBin();
+    if (!entry || !tsc) return { exportDeclarations: {} };
     const sourceEntries = [entry, ...Object.values(exposeEntries)];
     const rootDir = commonDir(sourceEntries);
     const declarationDir = resolve(outDir, "types");
     mkdirSync(declarationDir, { recursive: true });
     const emitConfigPath = join(declarationDir, "tsconfig.emit.json");
+    const baseConfigPath = findConfigFile();
     writeFileSync(
       emitConfigPath,
       JSON.stringify({
-        ...findConfigFile() ? { extends: findConfigFile() } : {},
+        ...baseConfigPath ? { extends: baseConfigPath } : {},
+        // `files` and an inherited `include` are additive, and anything outside
+        // `rootDir` escapes the `outDir` mapping and lands beside its source.
+        // Only the entries below may be compiled.
+        include: [],
+        exclude: [],
+        files: sourceEntries,
         compilerOptions: {
           declaration: true,
           emitDeclarationOnly: true,
@@ -83,12 +105,11 @@ function mountlyManifestFragmentPlugin(options) {
           outDir: declarationDir,
           declarationDir,
           rootDir
-        },
-        files: sourceEntries
+        }
       })
     );
     try {
-      execFileSync(process.execPath, [tscBin(), "-p", emitConfigPath], { stdio: "pipe" });
+      execFileSync(process.execPath, [tsc, "-p", emitConfigPath], { stdio: "pipe" });
     } catch {
     } finally {
       rmSync(emitConfigPath, { force: true });
@@ -108,7 +129,7 @@ function mountlyManifestFragmentPlugin(options) {
       root = config.root;
       outDir = resolve(root, options.outDir ?? "dist");
     },
-    closeBundle() {
+    async closeBundle() {
       const entry = options.entry ? resolve(root, options.entry) : void 0;
       const exposeEntries = Object.fromEntries(
         Object.entries(options.exposeEntries ?? {}).map(([key, value]) => [
@@ -124,7 +145,7 @@ function mountlyManifestFragmentPlugin(options) {
       if (options.version) vertical.version = options.version;
       if (options.featureExport) vertical.featureExport = options.featureExport;
       const declarations = emitDeclarations(entry, exposeEntries);
-      const namedExports = collectNamedExports([
+      const namedExports = await collectNamedExports([
         ...entry ? [entry] : [],
         ...Object.values(exposeEntries)
       ]);
@@ -592,12 +613,19 @@ function getSelfContainedExternals(framework) {
     ...FRAMEWORK_EXTERNALS[framework].filter((id) => !FRAMEWORK_BUNDLE[framework].includes(id))
   ];
 }
-function mountlyCssAsText() {
+function matchesFilter(id, include) {
+  return include.some(
+    (pattern) => typeof pattern === "string" ? id.includes(pattern) : pattern.test(id)
+  );
+}
+function mountlyCssAsText(options = {}) {
+  const includePatterns = options.include ? Array.isArray(options.include) ? options.include : [options.include] : null;
   return {
     name: "mountly-css-as-text",
     enforce: "pre",
     load(id) {
       if (!id.endsWith(".css")) return null;
+      if (includePatterns && !matchesFilter(id, includePatterns)) return null;
       const source = readFileSync2(id, "utf8");
       return {
         code: `export default ${JSON.stringify(source)};`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mountly-vite-plugin",
-  "version": "1.0.0",
+  "version": "1.2.2",
   "description": "Vite lib build plugin for mountly vertical widgets (dual ESM output)",
   "license": "Apache-2.0",
   "repository": {
@@ -23,18 +23,21 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "typescript": "^7.0.2"
-  },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^7.0.2",
     "vite": "^8.1.5",
-    "mountly-manifest": "1.0.0"
+    "mountly-manifest": "1.0.3"
   },
   "peerDependencies": {
+    "typescript": ">=7.0.0",
     "vite": "^8.2.1",
-    "mountly-manifest": "1.0.0"
+    "mountly-manifest": "1.0.3"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.json --noEmit false --declaration --emitDeclarationOnly --declarationMap false --outDir dist",