@vercel/microfrontends 0.9.0

package/README.md

@@ -0,0 +1,202 @@
+# `@vercel/microfrontends`
+
+Defines configuration and utilities for micro-frontend development.
+
+## Getting started
+
+### Define your `micro-frontend.json` file
+
+The first step to get started is to define your `micro-frontend.json` file
+listing all the micro-frontend applications in your setup. Since this file will
+be used by all the micro-frontends, you can define it in a new NPM package.
+
+For example, if your configuration is defined in `packages/my-app-micro-frontends-config`,
+then you would define a `micro-frontends.json` at the root.
+
+```json filename="micro-frontends.json"
+{
+  "version": "1",
+  "applications": {
+    "next-site": {
+      "default": true,
+      "development": {
+        "local": {
+          "protocol": "http",
+          "host": "localhost",
+          "port": 3331
+        },
+        "fallback": {
+          "protocol": "https",
+          "host": "nextjs.org"
+        }
+      },
+      "production": {
+        "protocol": "https",
+        "host": "nextjs.org"
+      },
+      "vercel": {
+        "projectId": "QmbxjYNaxv3Qphmreu8tATuLjwdhJBUxqaXC2fz3CMNwB3",
+        "projectName": "next-site"
+      }
+    },
+    "nextjs-conf": {
+      "default": false,
+      "routing": {
+        "assetPrefix": "nextjs-conf",
+        "matches": [
+          {
+            "group": "next-conf-pages",
+            "paths": ["/conf", "/conf/:path*"]
+          }
+        ]
+      },
+      "development": {
+        "fallback": {
+          "protocol": "https",
+          "host": "nextjs-conf.vercel.sh"
+        },
+        "local": {
+          "protocol": "http",
+          "host": "localhost",
+          "port": 3000
+        }
+      },
+      "production": {
+        "protocol": "https",
+        "host": "nextjs.org"
+      },
+      "vercel": {
+        "projectId": "prj_iv3tCRmwhF1ETZx2rH9NeoJJsoOc",
+        "projectName": "nextjs-conf"
+      }
+    }
+  }
+}
+```
+
+In the `package.json` for the package, add the `micro-frontends.json` file to
+the `files` attribute.
+
+```json filename="package.json"
+{
+  "name": "my-app-micro-frontends-config",
+  "files": ["micro-frontends.json"]
+}
+```
+
+### Set up Micro-Frontends in each Next.js application
+
+#### `next.config.js`
+
+In the `next.config.js` configuration for your application, wrap your config
+with the `withMicroFrontends` function specifying the `micro-frontends.json`
+config that you created above.
+
+```js filename="next.config.js"
+const { withMicroFrontends } = require('@vercel/microfrontends/next/config');
+
+const nextConfig = {
+  // ...
+};
+
+module.exports = withMicroFrontends(
+  nextConfig,
+  path.join(
+    __dirname,
+    'node_modules/my-app-micro-frontends-config/micro-frontends.json',
+  ),
+);
+```
+
+This will set up the necessary environment variables and `rewrites` for the
+application.
+
+#### Middleware
+
+Next you have to include the micro-frontends middleware. You can run this code
+in your middleware to apply the micro-frontends routing logic.
+
+```typescript filename="middleware.ts"
+import { runMicroFrontendsMiddleware } from '@vercel/microfrontends/next/middleware';
+
+export async function middleware(
+  request: NextRequest,
+  event: NextFetchEvent,
+): Promise<Response> {
+  let response = await runMicroFrontendsMiddleware(request);
+  if (response) {
+    return response;
+  }
+}
+```
+
+#### `.well-known` API endpoints
+
+The Micro-Frontends features rely on information exposed in two `.well-known`
+endpoints:
+
+- `/.well-known/vercel/micro-frontends/server-config`
+- `/.well-known/vercel/micro-frontends/client-config`
+
+You must define API handlers for these two routes to serve the information to
+the client and Vercel Toolbar for Micro-Frontends features to work.
+
+If you are using App Router, add a file under the `app/.well-known/vercel/micro-frontends/server-config/route.ts`
+file:
+
+```typescript filename="app/.well-known/vercel/micro-frontends/server-config/route.ts"
+export { wellKnownNextjsServerConfigAppRoute as GET } from '@vercel/microfrontends/next/endpoints';
+```
+
+Then do the same for `app/.well-known/vercel/micro-frontends/client-config/route.ts`:
+
+```typescript filename
+export { wellKnownNextjsClientConfigAppRoute as GET } from '@vercel/microfrontends/next/endpoints';
+```
+
+#### Client-side link navigation and prefetching
+
+Lastly, to correctly navigate between micro-frontends and prefetch content, you
+can use client components provided by this package.
+
+##### Set up prefetching in the root layout
+
+In the root layout of your application, add the `<PrefetchCrossZoneLinks />`
+element. This element will prefetch any cross-zone links to minimize the
+performance impact of hard navigations.
+
+```typescript filename="app/layout.tsx"
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}): JSX.Element {
+  return (
+    <html>
+      // ...
+      <body>
+        // ...
+        <PrefetchCrossZoneLinks />
+      </body>
+    </html>
+  );
+}
+```
+
+Then, use the `Link` component from `@vercel/microfrontends/next/client`
+any place that you would otherwise use the `next/link` package.
+
+## Contributing
+
+### Unit Tests
+
+```bash
+cd packages/microfrontends
+pnpm unit-tests
+```
+
+### Integration Tests
+
+There is an [example application](../../apps/micro-frontends-example-web) that has integration tests with Playwright.
+
+See [README.md](../../apps/micro-frontends-example-web/README.md) for more information.

package/cli/index.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const PATH_TO_DIST = path.resolve(__dirname, '../dist');
+
+// Define the path to the CLI file
+const cliPath = path.resolve(__dirname, PATH_TO_DIST, 'bin/cli.cjs');
+
+try {
+  const result = spawnSync('node', [cliPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+  });
+
+  process.exit(result.status);
+} catch (error) {
+  // eslint-disable-next-line no-console
+  console.error('Error loading microfrontends CLI, please re-install', error);
+  process.exit(1);
+}