next-md-negotiate 0.0.2 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kacper Siniło
+
+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,205 @@
+# next-md-negotiate
+
+Content negotiation for Next.js — serve Markdown to LLMs and HTML to browsers from the same URL.
+
+## The problem
+
+Your Next.js app serves HTML. LLMs, crawlers, and AI agents want Markdown. Today you're stuck choosing between:
+
+- **Separate endpoints** (`/api/products/123.md`) — duplicates your routing, goes stale, and clients have to know about a non-standard URL scheme.
+- **Markdown-only pages** — breaks the browser experience for human visitors.
+
+The HTTP `Accept` header already solves this. A browser sends `Accept: text/html`. An LLM client sends `Accept: text/markdown`. Your server should respond accordingly — but Next.js has no built-in way to do this.
+
+## The solution
+
+`next-md-negotiate` intercepts requests that ask for Markdown, rewrites them to an internal API route, and returns the Markdown version you define — all transparently, from the same URL.
+
+```
+Browser   → GET /products/42  Accept: text/html       → your normal Next.js page
+LLM agent → GET /products/42  Accept: text/markdown   → your Markdown version
+```
+
+No new URLs. No duplicate routing. The client just sets an `Accept` header.
+
+## Install
+
+```bash
+npm install next-md-negotiate
+```
+
+## Quick start
+
+### 1. Scaffold the handler
+
+```bash
+npx next-md-negotiate init
+```
+
+This creates:
+
+- **App Router:** `app/md-api/[...path]/route.ts`
+- **Pages Router:** `pages/api/md-api/[...path].ts`
+- **Config:** `md.config.ts`
+
+### 2. Define your Markdown versions
+
+```ts
+// md.config.ts
+import { createMdVersion } from 'next-md-negotiate';
+
+export default [
+  createMdVersion('/products/[productId]', async ({ productId }) => {
+    const product = await db.products.find(productId);
+    return `# ${product.name}\n\nPrice: $${product.price}\n\n${product.description}`;
+  }),
+
+  createMdVersion('/blog/[slug]', async ({ slug }) => {
+    const post = await db.posts.find(slug);
+    return `# ${post.title}\n\n${post.content}`;
+  }),
+];
+```
+
+Parameters are type-safe — `{ productId }` is inferred from the `[productId]` in the pattern.
+
+### 3. Add rewrites to `next.config`
+
+This works with both App Router and Pages Router, on any supported Next.js version.
+
+```ts
+// next.config.ts
+import { createMarkdownRewrites } from 'next-md-negotiate';
+
+export default {
+  async rewrites() {
+    return {
+      beforeFiles: createMarkdownRewrites({
+        routes: ['/products/[productId]', '/blog/[slug]'],
+      }),
+    };
+  },
+};
+```
+
+That's it. Requests with `Accept: text/markdown` get your Markdown. Everything else is untouched.
+
+## How it works
+
+```
+                         Accept: text/markdown?
+                                │
+                      ┌─────────┴─────────┐
+                      │ yes               │ no
+                      ▼                   ▼
+              Route matches?        Normal Next.js
+                      │              page renders
+               ┌──────┴──────┐
+               │ yes         │ no
+               ▼             ▼
+        Rewrite to        Pass through
+       /md-api/...
+               │
+               ▼
+    Catch-all handler
+    runs your function
+               │
+               ▼
+     200 text/markdown
+```
+
+1. The rewrite/middleware/proxy layer checks the `Accept` header for `text/markdown`, `application/markdown`, or `text/x-markdown`.
+2. If the request matches a configured route, it internally rewrites to `/md-api/...`.
+3. The catch-all route handler matches the path against your registry and calls your function.
+4. Your function returns a Markdown string. The handler sends it back as `text/markdown; charset=utf-8`.
+
+## Alternative: middleware or proxy
+
+The `next.config` rewrites approach covers most use cases. If you need content negotiation to live in your request-handling layer instead — for example, you already have a `middleware.ts` handling auth/i18n/redirects, or you're on Next.js 16+ using `proxy.ts` — use `createMarkdownNegotiator`:
+
+```ts
+// middleware.ts or proxy.ts
+import { createMarkdownNegotiator } from 'next-md-negotiate';
+
+const md = createMarkdownNegotiator({
+  routes: ['/products/[productId]', '/blog/[slug]'],
+});
+
+export function middleware(request: Request) {
+  // Check markdown negotiation first
+  const mdResponse = md(request);
+  if (mdResponse) return mdResponse;
+
+  // ...your other middleware logic (auth, i18n, etc.)
+}
+```
+
+### When to use what
+
+| Method | Best for |
+|---|---|
+| **`next.config` rewrites** | Most projects. Zero runtime overhead — Next.js handles the routing natively. Works with both App Router and Pages Router. |
+| **`middleware.ts` / `proxy.ts`** | Projects that already have a middleware or proxy and want all request interception in one place. |
+
+## Testing it
+
+```bash
+# Normal HTML response
+curl http://localhost:3000/products/42
+
+# Markdown response
+curl -H "Accept: text/markdown" http://localhost:3000/products/42
+```
+
+## API
+
+### `createMdVersion(pattern, handler)`
+
+Defines a Markdown version for a route.
+
+```ts
+createMdVersion('/products/[productId]', async ({ productId }) => {
+  return `# Product ${productId}`;
+});
+```
+
+**Supported patterns:**
+- Named params: `/products/[productId]`
+- Catch-all params: `/docs/[...slug]`
+- Multiple params: `/[org]/[repo]`
+- Static routes: `/about`
+
+### `createMdHandler(registry)`
+
+Creates an App Router handler for the catch-all route. Assign it to `GET`.
+
+```ts
+export const GET = createMdHandler(registry);
+```
+
+### `createMdApiHandler(registry)`
+
+Creates a Pages Router API handler for the catch-all route.
+
+```ts
+export default createMdApiHandler(registry);
+```
+
+### `createMarkdownRewrites(options)`
+
+Generates rewrite rules for `next.config.js`. The recommended approach for most projects.
+
+### `createMarkdownNegotiator(options)`
+
+Creates a handler for `middleware.ts` or `proxy.ts`. Returns a `Response` for markdown requests, or `undefined` to pass through.
+
+**Options (shared by both):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `routes` | `string[]` | required | Route patterns to negotiate |
+| `internalPrefix` | `string` | `'/md-api'` | Internal rewrite destination prefix |
+
+## License
+
+MIT

package/dist/cli.js

@@ -86,67 +86,22 @@ function main() {
     console.error(`Error: Failed to write files \u2014 ${message}`);
     process.exit(1);
   }
-  let nextMajor = null;
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-      const nextVersion = deps["next"];
-      if (nextVersion) {
-        const match = nextVersion.match(/(\d+)/);
-        if (match) nextMajor = parseInt(match[1], 10);
-      }
-    } catch {
-    }
-  }
-  console.log("\nNext step \u2014 add content negotiation:\n");
-  if (nextMajor !== null && nextMajor >= 16) {
-    console.log(`  Your project uses Next.js ${nextMajor}, so add a proxy.ts in your project root:
-`);
-    console.log("  // proxy.ts");
-    console.log("  import { createMarkdownProxy } from 'next-md-negotiate';");
-    console.log("");
-    console.log("  const md = createMarkdownProxy({");
-    console.log("    routes: ['/products/[productId]', '/blog/[slug]'],");
-    console.log("  });");
-    console.log("");
-    console.log("  export function proxy(request: Request) {");
-    console.log("    return md(request);");
-    console.log("  }");
-  } else if (nextMajor !== null && nextMajor >= 14 && hasAppDir) {
-    console.log(`  Your project uses Next.js ${nextMajor} with App Router, so add a middleware.ts in your project root:
-`);
-    console.log("  // middleware.ts");
-    console.log("  import { createMarkdownMiddleware } from 'next-md-negotiate';");
-    console.log("");
-    console.log("  const md = createMarkdownMiddleware({");
-    console.log("    routes: ['/products/[productId]', '/blog/[slug]'],");
-    console.log("  });");
-    console.log("");
-    console.log("  export function middleware(request: Request) {");
-    console.log("    return md(request);");
-    console.log("  }");
-  } else if (nextMajor !== null && hasPagesDir && !hasAppDir) {
-    console.log(`  Your project uses Next.js ${nextMajor} with Pages Router, so add rewrites to next.config.js:
-`);
-    console.log("  // next.config.js");
-    console.log("  import { createMarkdownRewrites } from 'next-md-negotiate';");
-    console.log("");
-    console.log("  export default {");
-    console.log("    async rewrites() {");
-    console.log("      return {");
-    console.log("        beforeFiles: createMarkdownRewrites({");
-    console.log("          routes: ['/products/[productId]', '/blog/[slug]'],");
-    console.log("        }),");
-    console.log("      };");
-    console.log("    },");
-    console.log("  };");
-  } else {
-    console.log("  Choose the integration method that fits your setup:\n");
-    console.log("  Next.js 16+        \u2192 proxy.ts       with createMarkdownProxy");
-    console.log("  Next.js 14-15 (App Router) \u2192 middleware.ts  with createMarkdownMiddleware");
-    console.log("  Pages Router       \u2192 next.config.js with createMarkdownRewrites");
-  }
-  console.log("\n  Then define your routes in md.config.ts");
+  console.log("\nNext step \u2014 add rewrites to next.config:\n");
+  console.log("  // next.config.ts");
+  console.log("  import { createMarkdownRewrites } from 'next-md-negotiate';");
+  console.log("");
+  console.log("  export default {");
+  console.log("    async rewrites() {");
+  console.log("      return {");
+  console.log("        beforeFiles: createMarkdownRewrites({");
+  console.log("          routes: ['/products/[productId]', '/blog/[slug]'],");
+  console.log("        }),");
+  console.log("      };");
+  console.log("    },");
+  console.log("  };");
+  console.log("");
+  console.log("  Then define your routes in md.config.ts");
+  console.log("");
+  console.log("  Alternative: use createMarkdownNegotiator in middleware.ts or proxy.ts");
 }
 main();

package/dist/index.cjs

@@ -20,8 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createMarkdownMiddleware: () => createMarkdownMiddleware,
-  createMarkdownProxy: () => createMarkdownProxy,
+  createMarkdownNegotiator: () => createMarkdownNegotiator,
   createMarkdownRewrites: () => createMarkdownRewrites,
   createMdApiHandler: () => createMdApiHandler,
   createMdHandler: () => createMdHandler,
@@ -171,8 +170,8 @@ function negotiateRequest(request, options) {
   return null;
 }
 
-// src/createRewriteHandler.ts
-function createRewriteHandler(options) {
+// src/createMarkdownNegotiator.ts
+function createMarkdownNegotiator(options) {
   for (const route of options.routes) {
     validatePattern(route);
   }
@@ -186,20 +185,9 @@ function createRewriteHandler(options) {
     });
   };
 }
-
-// src/createMarkdownProxy.ts
-function createMarkdownProxy(options) {
-  return createRewriteHandler(options);
-}
-
-// src/createMarkdownMiddleware.ts
-function createMarkdownMiddleware(options) {
-  return createRewriteHandler(options);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createMarkdownMiddleware,
-  createMarkdownProxy,
+  createMarkdownNegotiator,
   createMarkdownRewrites,
   createMdApiHandler,
   createMdHandler,

package/dist/index.d.cts

@@ -104,43 +104,24 @@ interface NegotiateOptions {
 }
 
 /**
- * Creates a proxy handler for Next.js 16+ `proxy.ts`.
- *
- * Returns a rewrite response for markdown requests matching
- * configured routes, or `undefined` to pass through.
- *
- * @example
- * // proxy.ts
- * import { createMarkdownProxy } from 'next-md-negotiate';
- *
- * const markdownProxy = createMarkdownProxy({
- *   routes: ['/products/[productId]', '/blog/[slug]'],
- * });
- *
- * export function proxy(request: Request) {
- *   return markdownProxy(request);
- * }
- */
-declare function createMarkdownProxy(options: NegotiateOptions): (request: Request) => Response | undefined;
-
-/**
- * Creates a middleware handler for Next.js 14-15 `middleware.ts`.
+ * Creates a handler that negotiates markdown content.
  *
+ * Use this in `middleware.ts` (Next.js 14–15) or `proxy.ts` (Next.js 16+).
  * Returns a rewrite response for markdown requests matching configured
  * routes, or `undefined` to pass through.
  *
  * @example
  * // middleware.ts
- * import { createMarkdownMiddleware } from 'next-md-negotiate';
+ * import { createMarkdownNegotiator } from 'next-md-negotiate';
  *
- * const markdownMiddleware = createMarkdownMiddleware({
+ * const md = createMarkdownNegotiator({
  *   routes: ['/products/[productId]', '/blog/[slug]'],
  * });
  *
  * export function middleware(request: Request) {
- *   return markdownMiddleware(request);
+ *   return md(request);
  * }
  */
-declare function createMarkdownMiddleware(options: NegotiateOptions): (request: Request) => Response | undefined;
+declare function createMarkdownNegotiator(options: NegotiateOptions): (request: Request) => Response | undefined;
 
-export { type ExtractParams, type MarkdownRewriteOptions, type MdVersionHandler, type NegotiateOptions, createMarkdownMiddleware, createMarkdownProxy, createMarkdownRewrites, createMdApiHandler, createMdHandler, createMdVersion };
+export { type ExtractParams, type MarkdownRewriteOptions, type MdVersionHandler, type NegotiateOptions, createMarkdownNegotiator, createMarkdownRewrites, createMdApiHandler, createMdHandler, createMdVersion };

package/dist/index.d.ts

@@ -104,43 +104,24 @@ interface NegotiateOptions {
 }
 
 /**
- * Creates a proxy handler for Next.js 16+ `proxy.ts`.
- *
- * Returns a rewrite response for markdown requests matching
- * configured routes, or `undefined` to pass through.
- *
- * @example
- * // proxy.ts
- * import { createMarkdownProxy } from 'next-md-negotiate';
- *
- * const markdownProxy = createMarkdownProxy({
- *   routes: ['/products/[productId]', '/blog/[slug]'],
- * });
- *
- * export function proxy(request: Request) {
- *   return markdownProxy(request);
- * }
- */
-declare function createMarkdownProxy(options: NegotiateOptions): (request: Request) => Response | undefined;
-
-/**
- * Creates a middleware handler for Next.js 14-15 `middleware.ts`.
+ * Creates a handler that negotiates markdown content.
  *
+ * Use this in `middleware.ts` (Next.js 14–15) or `proxy.ts` (Next.js 16+).
  * Returns a rewrite response for markdown requests matching configured
  * routes, or `undefined` to pass through.
  *
  * @example
  * // middleware.ts
- * import { createMarkdownMiddleware } from 'next-md-negotiate';
+ * import { createMarkdownNegotiator } from 'next-md-negotiate';
  *
- * const markdownMiddleware = createMarkdownMiddleware({
+ * const md = createMarkdownNegotiator({
  *   routes: ['/products/[productId]', '/blog/[slug]'],
  * });
  *
  * export function middleware(request: Request) {
- *   return markdownMiddleware(request);
+ *   return md(request);
  * }
  */
-declare function createMarkdownMiddleware(options: NegotiateOptions): (request: Request) => Response | undefined;
+declare function createMarkdownNegotiator(options: NegotiateOptions): (request: Request) => Response | undefined;
 
-export { type ExtractParams, type MarkdownRewriteOptions, type MdVersionHandler, type NegotiateOptions, createMarkdownMiddleware, createMarkdownProxy, createMarkdownRewrites, createMdApiHandler, createMdHandler, createMdVersion };
+export { type ExtractParams, type MarkdownRewriteOptions, type MdVersionHandler, type NegotiateOptions, createMarkdownNegotiator, createMarkdownRewrites, createMdApiHandler, createMdHandler, createMdVersion };

package/dist/index.js

@@ -140,8 +140,8 @@ function negotiateRequest(request, options) {
   return null;
 }
 
-// src/createRewriteHandler.ts
-function createRewriteHandler(options) {
+// src/createMarkdownNegotiator.ts
+function createMarkdownNegotiator(options) {
   for (const route of options.routes) {
     validatePattern(route);
   }
@@ -155,19 +155,8 @@ function createRewriteHandler(options) {
     });
   };
 }
-
-// src/createMarkdownProxy.ts
-function createMarkdownProxy(options) {
-  return createRewriteHandler(options);
-}
-
-// src/createMarkdownMiddleware.ts
-function createMarkdownMiddleware(options) {
-  return createRewriteHandler(options);
-}
 export {
-  createMarkdownMiddleware,
-  createMarkdownProxy,
+  createMarkdownNegotiator,
   createMarkdownRewrites,
   createMdApiHandler,
   createMdHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-md-negotiate",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Content negotiation for Next.js - serve Markdown to LLMs, HTML to browsers, from a single URL",
   "type": "module",
   "exports": {