@nxgt/material 2.3.1 → 2.4.1

package/docs/guides/printing.md

@@ -759,6 +759,12 @@ export async function GET(_request: Request, { params }: { params: Promise<{ id:
 }
 ```
 
+A Next.js route handler also needs its `next.config.ts` wrapped in
+`withNxgtPrint` from `@nxgt/material/next`, which adds
+`serverExternalPackages: ['@nxgt/material']` and, for `output: 'standalone'`,
+a trace of pdfkit's fonts: see
+[Next.js](#nextjs-serverexternalpackages-and-output-standalone).
+
 ```tsx
 // Hono
 import { Hono } from 'hono';
@@ -1292,4 +1298,102 @@ Two changes look like fixes and are not:
   cannot resolve it from your app's directory:
   `Cannot find package 'pdfkit'`.
 
+### Next.js: `serverExternalPackages` and `output: 'standalone'`
+
+A route handler that imports `@nxgt/material/print` needs two keys of
+`next.config.ts`. `withNxgtPrint` from `@nxgt/material/next` (since 2.4.0)
+adds both:
+
+```ts
+// next.config.ts
+import { withNxgtPrint } from '@nxgt/material/next';
+
+export default withNxgtPrint({
+  output: 'standalone',
+  // the rest of your config, as it was
+});
+```
+
+Checked with Next.js 16.3 against `.next/standalone/server.js` run alone,
+with both Turbopack and `next build --webpack`, under npm and pnpm.
+
+- **`serverExternalPackages`** gets `'@nxgt/material'`. Route handlers are
+  bundled with React's `react-server` build, which has no `createContext`,
+  and `/print` calls it when it loads; external, the library and React load
+  from `node_modules`. Without it, `next build` stops at `Collecting page
+  data` with
+  [`TypeError: (0 , t.createContext) is not a function`](../troubleshooting.md#typeerror-0--tcreatecontext-is-not-a-function-in-a-nextjs-route-handler).
+- **`outputFileTracingIncludes`** gets, for every route (`'/**'`), every
+  `.cjs` file under pdfkit's `js/standard-fonts/`: pdfkit `require()`s its
+  fonts at runtime, which the tracer does not follow. Without it, a webpack
+  build passes and `next start` works, but the standalone server answers
+  `500` on the PDF route with
+  [`Cannot find module '…/node_modules/pdfkit/js/standard-fonts/Helvetica.cjs'`](../troubleshooting.md#cannot-find-module-node_modulespdfkitjsstandard-fontshelveticacjs).
+  Turbopack's trace included the files; the glob is added anyway, whatever
+  the `output` and the bundler, because it costs nothing.
+
+What it does, precisely:
+
+- **It merges, and never overwrites.** Your `serverExternalPackages` and
+  `outputFileTracingIncludes` keep what they had, other routes' globs
+  included; the two additions are deduplicated. Every other key passes
+  through.
+- **pdfkit is found where your app installs it.** It resolves
+  `@react-pdf/renderer` from the project directory, then the pdfkit it
+  depends on and the one `@react-pdf/font` depends on, to their real
+  directories, and writes each as a glob relative to the project directory:
+  `./node_modules/pdfkit/js/standard-fonts/**/*.cjs` under npm (checked end
+  to end), `./node_modules/.pnpm/pdfkit@<version>/node_modules/pdfkit/js/standard-fonts/**/*.cjs`
+  under pnpm (checked end to end), `./node_modules/.bun/pdfkit@<version>/…`
+  under Bun's isolated linker, `../../node_modules/…` in a monorepo that
+  hoists it above the app.
+- **Without `@react-pdf/renderer`** (an optional peer), it adds no fonts and
+  says nothing. Any other failure to resolve them prints one
+  `[@nxgt/material/next]` warning; the config is still returned, and the
+  manual globs below are the fallback.
+- **The project directory is `process.cwd()`**, which is right when
+  `next build` runs in the project. For `next build <dir>` run from
+  elsewhere, pass it: `withNxgtPrint(config, { dir: import.meta.dirname })`
+  (checked with Next.js 16.3's `next.config.ts`; `__dirname` in a CommonJS
+  `next.config.js`). A relative `dir` is taken from the working directory.
+- **The function form of `next.config` works too**:
+  `withNxgtPrint((phase, { defaultConfig }) => ({ ... }))` returns a function
+  Next.js calls as usual.
+- It runs in Node at config time, imports only `node:*` built-ins and
+  `@nxgt/material-core/pdfkit-fonts` (already installed with the library),
+  and needs no dependency on `next`: its parameter accepts any `NextConfig`, and it
+  returns the type you passed in. Its keys are not checked against
+  `NextConfig`, so a misspelt one passes: write
+  `withNxgtPrint({ ... } satisfies NextConfig)` to have them checked. The
+  types it is written with are exported too, should you wrap it:
+  `WithNxgtPrintOptions` (`{ dir }`), `NextConfigLike`, `NextConfigFunction`
+  and `WithPrint`.
+- The package is ESM. A CommonJS `next.config.js` `require()`s it, which
+  needs Node 20.19+ or 22.12+; `next.config.ts` and `next.config.mjs` import
+  it.
+
+**By hand**, when you would rather not use the helper, the same config is:
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next';
+
+export default {
+  output: 'standalone',
+  // Route handlers are bundled with React's react-server build, which has no
+  // createContext: load the library from node_modules instead.
+  serverExternalPackages: ['@nxgt/material'],
+  // pdfkit require()s its fonts' .cjs files at runtime; the tracer copies
+  // only the .mjs ones. Only needed with output: 'standalone'.
+  outputFileTracingIncludes: {
+    '/**': ['./node_modules/pdfkit/js/standard-fonts/**/*.cjs'],
+  },
+} satisfies NextConfig;
+```
+
+Under pnpm the glob is
+`./node_modules/.pnpm/pdfkit@*/node_modules/pdfkit/js/standard-fonts/**/*.cjs`.
+
+`pdfkitStandardFonts()` is a Vite plugin and does not apply to Next.js.
+
 More on what a server bundle evaluates in [SSR](ssr.md).

package/docs/roadmap.md

@@ -82,6 +82,12 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **PDFs from a Next.js route handler in one line of config** —
+  `withNxgtPrint(nextConfig)` from `@nxgt/material/next` adds what `/print`
+  needs to `next.config.ts` — the library in `serverExternalPackages`, and
+  pdfkit's fonts in the `output: 'standalone'` trace wherever your package manager
+  installed them — merged with your own config. 2.4.0.
+  ([printing](guides/printing.md#nextjs-serverexternalpackages-and-output-standalone))
 - **One copy of the framework-free code, shared with `@nxgt/material-vue`** —
   the PDF document model and renderer, the print formatters, the PDF file
   helpers, `PdfReader`'s page geometry, scroll spy and search, the

package/docs/troubleshooting.md

@@ -35,6 +35,9 @@ words in your error.
 
 - [`Cannot find module '#standard-fonts/Helvetica'`](#cannot-find-module-standard-fontshelvetica)
 - [`still references '#standard-fonts/' after the transform`](#still-references-standard-fonts-after-the-transform)
+- [`TypeError: (0 , t.createContext) is not a function` in a Next.js route handler](#typeerror-0--tcreatecontext-is-not-a-function-in-a-nextjs-route-handler)
+- [`Cannot find module '…/node_modules/pdfkit/js/standard-fonts/Helvetica.cjs'` (Next.js `output: 'standalone'`)](#cannot-find-module-node_modulespdfkitjsstandard-fontshelveticacjs)
+- [`[@nxgt/material/next] could not resolve …`](#nxgtmaterialnext-could-not-resolve-)
 - [`Module '"@nxgt/material"' has no exported member 'PrintHeader'`](#module-nxgtmaterial-has-no-exported-member-printheader)
 - [`Module '"@nxgt/material"' has no exported member 'formatAmount'`](#module-nxgtmaterial-has-no-exported-member-formatamount)
 - [An amount in yen shows no decimals, or one in dinars shows three](#an-amount-in-yen-shows-no-decimals-or-one-in-dinars-shows-three)
@@ -530,6 +533,130 @@ last `pdfkit` that built, and please report it (see
 { "overrides": { "pdfkit": "<last version that built>" } }
 ```
 
+### `TypeError: (0 , t.createContext) is not a function` in a Next.js route handler
+
+**When:** `next build`, at `Collecting page data`, for an App Router route
+handler that imports `@nxgt/material/print`. The build stops with
+`Failed to collect configuration for /invoices/[id]/pdf`; the letter before
+`.createContext` depends on the build (`t` with Turbopack, `d` with webpack).
+**Why:** Next.js bundles route handlers for React Server Components, with
+the `react-server` build of React, which has no `createContext`.
+`@nxgt/material/print` also holds `usePdfFile` and the print context, so it
+calls `createContext` when the module loads. (`@react-pdf/renderer` is already
+external by default in Next.js; the library that imports it is not.)
+**Fix:** leave the library out of the server bundle, so Node loads it, and
+React, from `node_modules`. `withNxgtPrint` (2.4.0+) does it, and also
+traces pdfkit's fonts for `output: 'standalone'` (the next entry):
+
+```ts
+// next.config.ts
+import { withNxgtPrint } from '@nxgt/material/next';
+
+export default withNxgtPrint({
+  // your config, as it was
+});
+```
+
+By hand, on an older version:
+
+```ts
+// next.config.ts
+export default {
+  serverExternalPackages: ['@nxgt/material'],
+};
+```
+
+With `output: 'standalone'`, add the font files of the next entry too.
+
+### `Cannot find module '…/node_modules/pdfkit/js/standard-fonts/Helvetica.cjs'`
+
+**When:** a Next.js app built with `output: 'standalone'` renders a PDF, run
+from `.next/standalone/server.js` alone (a container image, a copied
+folder). `next build` passes, `next start` works, but the PDF route answers
+`500` with an empty body and the server log shows this message, with
+`code: 'MODULE_NOT_FOUND'`, as an `unhandledRejection`. Seen with
+`next build --webpack` (Next.js 16); Turbopack's trace did include the
+files in the same app.
+**Why:** pdfkit loads its standard fonts at runtime with
+`require('#standard-fonts/<name>')`, which its `package.json` `imports` maps
+to `js/standard-fonts/<name>.cjs` for `require`. The output file tracer
+(`@vercel/nft`) follows the `default` condition and copies the `.mjs` files
+only, so the `.cjs` pdfkit asks for is not in `.next/standalone`.
+**Fix:** add the `.cjs` fonts (and their `chunks/`) to the trace.
+`withNxgtPrint` (2.4.0+) finds where pdfkit is installed (checked end to end
+under npm and pnpm) and adds them, merged with your own
+`outputFileTracingIncludes`:
+
+```ts
+// next.config.ts
+import { withNxgtPrint } from '@nxgt/material/next';
+
+export default withNxgtPrint({ output: 'standalone' });
+```
+
+If it cannot resolve a pdfkit it prints one `[@nxgt/material/next]` warning
+(next entry) and adds only the fonts it did resolve. By hand, or on an older version:
+
+```ts
+// next.config.ts
+export default {
+  output: 'standalone',
+  serverExternalPackages: ['@nxgt/material'],
+  outputFileTracingIncludes: {
+    '/**': ['./node_modules/pdfkit/js/standard-fonts/**/*.cjs'],
+  },
+};
+```
+
+The key is a route glob: `'/**'` covers every route, `'/invoices/**'` only
+the routes under `/invoices`. The path is from the project root to
+where pdfkit is installed. With pnpm, pdfkit is not at the top of
+`node_modules`; use its store directory (checked with pnpm 11, the same
+`500` without it):
+
+```ts
+outputFileTracingIncludes: {
+  '/**': ['./node_modules/.pnpm/pdfkit@*/node_modules/pdfkit/js/standard-fonts/**/*.cjs'],
+},
+```
+
+Check with `ls .next/standalone/node_modules/pdfkit/js/standard-fonts/*.cjs`
+after the build (under pnpm,
+`.next/standalone/node_modules/.pnpm/pdfkit@*/node_modules/pdfkit/js/standard-fonts/`).
+
+### `[@nxgt/material/next] could not resolve …`
+
+**When:** `next build` or `next dev` prints, once,
+`[@nxgt/material/next] could not resolve <what>: <error>. PDF routes may
+answer 500 under output: 'standalone'; add pdfkit's
+js/standard-fonts/**/*.cjs to outputFileTracingIncludes by hand.`
+When several things failed, that one message lists them all, joined by
+`; `, each error cut to its first line (for example `could not resolve
+@react-pdf/font: …; could not resolve pdfkit's fonts for
+@react-pdf/renderer: …`).
+**Why:** `withNxgtPrint` found `@react-pdf/renderer` but could not follow it
+to `@react-pdf/font` or to a pdfkit's `standard-fonts` (an unusual
+installation, a patched or partial `node_modules`). It adds the fonts it did
+resolve and returns your config; the build goes on. Without
+`@react-pdf/renderer` installed it prints nothing: there is nothing to trace.
+**Fix:** only `output: 'standalone'` needs the fonts. Add the missing ones by
+hand, as in the previous entry, next to the helper:
+
+```ts
+// next.config.ts
+import { withNxgtPrint } from '@nxgt/material/next';
+
+export default withNxgtPrint({
+  output: 'standalone',
+  outputFileTracingIncludes: {
+    '/**': ['./node_modules/pdfkit/js/standard-fonts/**/*.cjs'],
+  },
+});
+```
+
+If `next build` runs from another directory, pass `{ dir }` (see
+[printing](guides/printing.md#nextjs-serverexternalpackages-and-output-standalone)).
+
 ### `Module '"@nxgt/material"' has no exported member 'PrintHeader'`
 
 **When:** type-checking (`TS2305`) or bundling (`"PrintHeader" is not exported

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "2.3.1",
+	"version": "2.4.1",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -43,6 +43,11 @@
 			"types": "./dist/lib/vite/index.d.ts",
 			"require": "./dist/vite.js"
 		},
+		"./next": {
+			"import": "./dist/next.js",
+			"types": "./dist/lib/next/index.d.ts",
+			"require": "./dist/next.js"
+		},
 		"./hooks": {
 			"import": "./dist/hooks.js",
 			"types": "./dist/lib/hooks/index.d.ts",
@@ -108,7 +113,7 @@
 		"docs:previews": "vitest run --project previews"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.1.1",
+		"@nxgt/material-core": "^0.2.0",
 		"@base-ui/react": "^1.6.0",
 		"@dnd-kit/core": "^6.3.1",
 		"@dnd-kit/sortable": "^10.0.0",

package/dist/lib/components/ui/media/file-list/format-file-size.d.ts

@@ -1 +0,0 @@
-export declare function formatFileSize(bytes: number): string;