npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@farming-labs/next

v0.2.149

Published

Next.js adapter for @farming-labs/docs — MDX config wrapper

Readme

@farming-labs/next

The Next.js App Router adapter for @farming-labs/docs.

It connects the shared docs configuration and theme to Next.js, compiles Markdown and MDX, generates the standard docs routes, and provides Next-native runtime helpers for documentation APIs, API references, MCP, and changelogs.

What this package does

  • Wraps next.config.ts with the Farming Labs MDX and routing integration
  • Generates missing docs layouts, API routes, MCP routes, and enabled feature routes
  • Adds machine-readable Markdown, agent discovery, sitemap, and llms.txt rewrites
  • Provides App Router layout, metadata, API-reference, and changelog helpers
  • Preserves user-authored files and existing Next.js configuration

The shared config and CLI live in @farming-labs/docs. React UI, MDX components, providers, and theme CSS live in @farming-labs/theme.

Install

The CLI can add docs to an existing Next.js project:

npx @farming-labs/docs@latest init

For manual installation:

npm install @farming-labs/docs @farming-labs/next @farming-labs/theme

Minimal setup

Create docs.config.ts with defineDocs(), then wrap the Next.js config:

// next.config.ts
import { withDocs } from "@farming-labs/next/config";

export default withDocs();

Existing Next.js configuration can be passed directly:

export default withDocs({
  reactStrictMode: true,
});

Import the selected theme in your global stylesheet:

@import "tailwindcss";
@import "@farming-labs/theme/default/css";

Write documentation pages under app/docs/ or src/app/docs/. The CLI also adds the root RootProvider, generated docs layout, and server routes needed for a complete setup.

Extending MDX compilation

Set mdx in docs.config.ts and pass the live config to withDocs. Plugin module names and paths with JSON options work with both Webpack and Turbopack:

export default defineDocs({
  entry: "docs",
  mdx: {
    remarkPlugins: ["remark-directive", "./lib/remark-docs.mjs"],
    rehypePlugins: [["rehype-external-links", { target: "_blank" }]],
  },
});
import { withDocs } from "@farming-labs/next/config";
import docsConfig from "./docs.config";

export default withDocs({}, docsConfig);

Install the plugins in your application. Paths starting with ./ or ../ resolve from the application root. Extra plugins run after the built-in plugins in their respective phase; frontmatter, heading IDs, TOC, Markdown alternate links, and syntax highlighting remain enabled. Put callbacks and other non-JSON configuration inside a local plugin module.

For a migration with its own highlighter, set mdx.codeHighlighter to that plugin's module name or [module, options] tuple. This replaces only the default code-highlighting step, so code is highlighted once. The custom plugin owns its theme and code-block behavior. Omitting mdx keeps the existing defaults. These hooks do not configure Fumadocs collections or replace its source loader.

The third-argument withDocs(nextConfig, docsConfig, { mdx }) form is deprecated and still works. Setting mdx in both places throws.

The built-in highlighter uses Shiki's Oniguruma engine during compilation. A custom highlighter can import @farming-labs/next/mdx-plugins/rehype-code to keep that default while configuring themes and transformers. Passing engine: "js" explicitly selects Shiki's JavaScript engine.

The built-in highlighter also keeps each highlighted code block in <distDir>/cache/farming-labs/code-highlight, which Next.js preserves between builds. When Turbopack recompiles a page, for example after a Next.js upgrade or an edit, unchanged blocks are reused, and a page whose blocks are all cached never starts Shiki. Your remark and rehype plugins still run on every compile. Entries are keyed by the code, language, meta string, highlighter options, and the Fumadocs and Shiki versions, and the cache keeps at most 16,384 blocks per configuration. Blocks in unknown languages are not stored, and neither is a block that took longer than a tokenizeTimeLimit you set. Options that are not plain JSON, such as transformers, disable the cache.

A block gets the same colors in every build, whichever pages a build worker compiled before it. Grammars that change other languages (ts-tags, lit, vue, nix, and Angular's) and grammars that embed languages lazily (Markdown, MDX, Vue, Svelte, Astro, LaTeX, and others) highlight their blocks with highlighters of their own. Code nested in those languages is highlighted when it is YAML, TOML, JSON, JSONC, HTML, CSS, JavaScript, TypeScript, JSX, TSX, shell, Markdown, or MDX, and stays plain otherwise. Shiki's per-line time limit is off, so a busy build machine never leaves part of a line unstyled; set tokenizeTimeLimit in milliseconds to restore one.

Page metadata transport

Production builds send title, description, reading time, dates, and structured data with each compatible Markdown/MDX page. The shared layout keeps navigation and theme settings. This changes the data boundary without changing the rendered page markup or the theme API.

Automatic selection applies to ordinary file routes using the standard generated layout and MDX provider. Customized layouts, MDX providers, compiler extensions, components.wrapper, development, localized layouts, multiple docs roots, custom content directories, Next.js basePath, nested layouts/templates, dynamic/group/parallel routes, and authored MDX exports keep the existing site-wide metadata path. Code fences containing exports remain eligible. Older installed core or theme packages without the boundary support also keep the existing path.

To retain site-wide metadata explicitly:

export default withDocs({}, undefined, { pageMetadata: "site" });

The default is pageMetadata: "auto". Both transports use the same metadata builder and page component. Custom compiler extensions retain the existing transport. The boundary subpaths are internal compiler integration points, not application component APIs.

Main entrypoints

| Entrypoint | Purpose | | --- | --- | | @farming-labs/next/config | withDocs() Next.js configuration wrapper | | @farming-labs/next/layout | App Router docs layout and metadata helpers | | @farming-labs/next/api | Docs API and MCP route handlers | | @farming-labs/next/api-reference | Generated API-reference routes and pages | | @farming-labs/next/changelog | Generated changelog page helpers |

Requirements

  • Next.js 16 or newer
  • React and React DOM 19.2 or newer
  • @farming-labs/docs 0.2.121 or newer and @farming-labs/theme

Learn more

License

MIT