@jasy/nuxt 1.0.0-alpha.1

package/README.md

@@ -0,0 +1,123 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jasy-pdf/jasy/main/docs/jasy-nuxt.png" width="120" alt="jasy nuxt">
+</p>
+
+<h1 align="center">@jasy/nuxt</h1>
+
+<p align="center">
+  <b>Author PDFs as Vue components in Nuxt - render them in the browser or on a server route, zero config.</b>
+</p>
+
+The Nuxt module for [`@jasy/vue`](https://npmx.dev/@jasy/vue) and [`@jasy/pdf`](https://npmx.dev/@jasy/pdf).
+Add it to `modules` and the components and render helpers are just there - no imports, no wiring. Render a
+PDF client-side with `usePdf`, or stream one from a Nitro route with `definePdfHandler`. No headless
+browser, no Java.
+
+## Install
+
+```bash
+npx nuxi module add @jasy/nuxt
+```
+
+That installs the package and adds it to `modules` for you. Or wire it up by hand:
+
+```bash
+pnpm add @jasy/nuxt
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@jasy/nuxt"],
+});
+```
+
+## Client: `usePdf`
+
+Author a PDF as a Vue component - the jasy components are auto-registered, so no imports:
+
+```vue
+<!-- Invoice.vue -->
+<template>
+  <Document :size="11">
+    <Page :size="'A4'" :margin="48">
+      <Text :size="24" bold color="#0a2348">Invoice #{{ id }}</Text>
+    </Page>
+  </Document>
+</template>
+```
+
+```vue
+<script setup lang="ts">
+import Invoice from "./Invoice.vue";
+
+const { open, download, pending } = usePdf(Invoice, { props: { id: 42 } });
+</script>
+
+<template>
+  <button :disabled="pending" @click="open">View PDF</button>
+</template>
+```
+
+`open()` and `download()` render on demand and reuse the result, so one click is one render. Pass
+`{ immediate: true }` to pre-render on mount.
+
+## Server: `definePdfHandler`
+
+The `@jasy/pdf` tree API is auto-imported in `server/`. No Vue, no browser - build the document and stream
+it:
+
+```ts
+// server/api/invoice/[id].get.ts
+export default definePdfHandler((event) =>
+  Document([
+    Page({ size: "A4", margin: 48 }, [
+      Text(`Invoice #${getRouterParam(event, "id")}`, { size: 24, bold: true }),
+    ]),
+  ]),
+);
+```
+
+`GET /api/invoice/42` streams `application/pdf`. Need auth or a data fetch first? Use
+`sendPdf(event, doc, opts)` inside your own handler, or `renderToBytes(doc)` to just get the bytes (save
+them, attach to an email, anything).
+
+### Caching
+
+Wrap a route in Nitro's cache - keyed by path + query, so it caches per request out of the box:
+
+```ts
+export default definePdfHandler(build, { cache: { maxAge: 3600 } });
+```
+
+Expired entries re-render fresh (`swr` is off by default) - a stale invoice is never served.
+
+## What the module sets up
+
+- **Components** for templates: `Document` · `Page` · `Column` · `Row` · `Box` · `Padding` · `Text` ·
+  `Image` · `Table` and the rest. Set a `prefix` to dodge name clashes (`prefix: "Pdf"` makes it
+  `<PdfDocument>`).
+- **Auto-imports**: `usePdf` and `renderToPdf` on the client; the `@jasy/pdf` tree API, `definePdfHandler`
+  and `sendPdf` on the server.
+- **Bundle-safety**: keeps jimp (the server-side image decoder) out of the client bundle - the browser
+  decodes images via canvas instead.
+
+## Options
+
+```ts
+export default defineNuxtConfig({
+  modules: ["@jasy/nuxt"],
+  jasy: {
+    autoImport: true, // auto-register components + the tree API (default true)
+    prefix: "Pdf", // <PdfDocument> in templates, PdfDocument(...) in server/ (default none)
+  },
+});
+```
+
+## Links
+
+- [`@jasy/pdf`](https://npmx.dev/@jasy/pdf) - the pure-TypeScript PDF engine
+- [`@jasy/vue`](https://npmx.dev/@jasy/vue) - author PDFs as Vue components
+- [jasy.dev](https://jasy.dev) - documentation
+
+MIT, by Florian Heuberger

package/dist/module.d.mts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Auto-register the jasy components (client) + the @jasy/pdf tree API (server) so they need no import. Default true. */
+    autoImport?: boolean;
+    /** Component name prefix, e.g. "Pdf" -> <PdfDocument>, <PdfText>. Default none. */
+    prefix?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@jasy/nuxt",
+  "configKey": "jasy",
+  "version": "1.0.0-alpha.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,83 @@
+import { join, dirname } from 'node:path';
+import { defineNuxtModule, createResolver, addComponent, addServerImports, addImports, addImportsDir, addServerImportsDir, resolvePath, extendViteConfig } from '@nuxt/kit';
+
+const COMPONENTS = [
+  "Document",
+  "Page",
+  "Column",
+  "Row",
+  "Box",
+  "Padding",
+  "Expanded",
+  "Spacer",
+  "Divider",
+  "Image",
+  "Text",
+  "Paragraph",
+  "Span",
+  "Table",
+  "TableRow",
+  "TableCell",
+  "Positioned",
+  "DefaultTextStyle"
+];
+const SERVER_FACTORIES = [
+  "Document",
+  "Page",
+  "Column",
+  "Row",
+  "Box",
+  "Padding",
+  "Expanded",
+  "Spacer",
+  "Divider",
+  "Image",
+  "Text",
+  "Paragraph",
+  "span",
+  "Table",
+  "Positioned",
+  "DefaultTextStyle"
+];
+const SERVER_UTILS = ["renderToBytes", "renderPdf", "mm"];
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@jasy/nuxt",
+    configKey: "jasy"
+  },
+  defaults: {
+    autoImport: true
+  },
+  async setup(options) {
+    const resolver = createResolver(import.meta.url);
+    if (options.autoImport) {
+      const prefix = options.prefix ?? "";
+      for (const name of COMPONENTS) {
+        addComponent({ name: `${prefix}${name}`, filePath: "@jasy/vue", export: name });
+      }
+      addServerImports([
+        ...SERVER_FACTORIES.map((name) => ({ name, as: `${prefix}${name}`, from: "@jasy/pdf" })),
+        ...SERVER_UTILS.map((name) => ({ name, from: "@jasy/pdf" }))
+      ]);
+      addImports([
+        { name: "renderToPdf", from: "@jasy/vue" },
+        { name: "renderToPdfString", from: "@jasy/vue" }
+      ]);
+    }
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    const browserImage = join(dirname(await resolvePath("@jasy/pdf")), "platform/browser-image.js");
+    extendViteConfig((config) => {
+      config.resolve ||= {};
+      const existing = config.resolve.alias;
+      const alias = Array.isArray(existing) ? existing : Object.entries(existing ?? {}).map(([find, replacement]) => ({ find, replacement }));
+      alias.push({ find: /^.*platform[\\/]node-image\.js$/, replacement: browserImage });
+      config.resolve.alias = alias;
+      config.optimizeDeps ||= {};
+      config.optimizeDeps.include = [...config.optimizeDeps.include ?? [], "fflate"];
+      config.optimizeDeps.exclude = [...config.optimizeDeps.exclude ?? [], "jimp"];
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/usePdf.d.ts

@@ -0,0 +1,24 @@
+import type { Component } from "vue";
+import type { RenderOptions } from "@jasy/pdf";
+export interface UsePdfOptions {
+    /** Props passed to the rendered component. A function is re-read on each render (reactive). */
+    props?: Record<string, any> | (() => Record<string, any>);
+    /** Render immediately on mount (client only). Default false. */
+    immediate?: boolean;
+    /** Engine options forwarded to renderToPdf (e.g. onOverflow). */
+    renderOptions?: RenderOptions;
+}
+/**
+ * Render a PDF component to bytes in the browser. `open()` / `download()` render on demand and reuse the
+ * result, so one click is one render whether or not `immediate` pre-rendered. `render()` forces a fresh
+ * one (e.g. after the data changed). The object URL is revoked on re-render and scope dispose.
+ */
+export declare function usePdf(component: Component, options?: UsePdfOptions): {
+    bytes: import("vue").ShallowRef<Uint8Array<ArrayBufferLike> | undefined, Uint8Array<ArrayBufferLike> | undefined>;
+    url: import("vue").Ref<string | undefined, string | undefined>;
+    pending: import("vue").Ref<boolean, boolean>;
+    error: import("vue").Ref<unknown, unknown>;
+    render: () => Promise<void>;
+    download: (filename?: string) => Promise<void>;
+    open: () => Promise<void>;
+};

package/dist/runtime/composables/usePdf.js

@@ -0,0 +1,55 @@
+import { ref, shallowRef, onMounted, onScopeDispose } from "vue";
+import { renderToPdf } from "@jasy/vue";
+export function usePdf(component, options = {}) {
+  const bytes = shallowRef();
+  const url = ref();
+  const pending = ref(false);
+  const error = ref();
+  let inflight = null;
+  function revoke() {
+    if (url.value) {
+      URL.revokeObjectURL(url.value);
+      url.value = void 0;
+    }
+  }
+  async function run() {
+    if (typeof document === "undefined") return;
+    pending.value = true;
+    error.value = void 0;
+    try {
+      const props = typeof options.props === "function" ? options.props() : options.props;
+      const out = await renderToPdf(component, props, options.renderOptions);
+      bytes.value = out;
+      revoke();
+      url.value = URL.createObjectURL(new Blob([out], { type: "application/pdf" }));
+    } catch (e) {
+      error.value = e;
+    } finally {
+      pending.value = false;
+    }
+  }
+  function render() {
+    inflight ??= run().finally(() => {
+      inflight = null;
+    });
+    return inflight;
+  }
+  async function ensure() {
+    if (!url.value) await render();
+  }
+  async function open() {
+    await ensure();
+    if (url.value) window.open(url.value, "_blank");
+  }
+  async function download(filename = "document.pdf") {
+    await ensure();
+    if (!url.value) return;
+    const a = document.createElement("a");
+    a.href = url.value;
+    a.download = filename;
+    a.click();
+  }
+  onScopeDispose(revoke);
+  if (options.immediate) onMounted(render);
+  return { bytes, url, pending, error, render, download, open };
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json"
+}

package/dist/runtime/server/utils/jasy-pdf.d.ts

@@ -0,0 +1,24 @@
+import { type H3Event } from "h3";
+import { renderToBytes, type RenderOptions } from "@jasy/pdf";
+type PdfDoc = Parameters<typeof renderToBytes>[0];
+export interface SendPdfOptions {
+    /** Suggested file name. Default "document.pdf". */
+    filename?: string;
+    /** Send as a download (attachment) instead of inline. Default false. */
+    download?: boolean;
+    /** Engine options forwarded to renderToBytes (e.g. onOverflow). */
+    renderOptions?: RenderOptions;
+}
+export interface PdfHandlerOptions extends SendPdfOptions {
+    /**
+     * Cache the rendered PDF with Nitro. `true` for defaults, or pass its cache options (`maxAge`, `name`,
+     * `getKey`, `swr`, ...). Default key is path + query (so `/x?id=1` caches per id); `swr` defaults to
+     * false. Node runtime.
+     */
+    cache?: boolean | Record<string, any>;
+}
+/** Render a @jasy/pdf document and write it as the response (sets the PDF headers), returns the bytes. */
+export declare function sendPdf(event: H3Event, doc: PdfDoc, options?: SendPdfOptions): Promise<Uint8Array>;
+/** A PDF endpoint in one line: build a document from the request, get a streaming application/pdf route. */
+export declare function definePdfHandler(build: (event: H3Event) => PdfDoc | Promise<PdfDoc>, options?: PdfHandlerOptions): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Uint8Array<ArrayBufferLike>>>;
+export {};

package/dist/runtime/server/utils/jasy-pdf.js

@@ -0,0 +1,35 @@
+import { defineEventHandler, setResponseHeader } from "h3";
+import { defineCachedFunction } from "#imports";
+import { renderToBytes } from "@jasy/pdf";
+function setPdfHeaders(event, options) {
+  setResponseHeader(event, "content-type", "application/pdf");
+  setResponseHeader(
+    event,
+    "content-disposition",
+    `${options.download ? "attachment" : "inline"}; filename="${options.filename ?? "document.pdf"}"`
+  );
+}
+export async function sendPdf(event, doc, options = {}) {
+  const bytes = await renderToBytes(doc, options.renderOptions);
+  setPdfHeaders(event, options);
+  return bytes;
+}
+export function definePdfHandler(build, options = {}) {
+  const { cache, ...send } = options;
+  if (!cache) {
+    return defineEventHandler(async (event) => sendPdf(event, await build(event), send));
+  }
+  const renderCached = defineCachedFunction(
+    async (event) => {
+      const bytes = await renderToBytes(await build(event), send.renderOptions);
+      return Buffer.from(bytes).toString("base64");
+    },
+    // swr:false - never serve a stale (e.g. hour-old) invoice; re-render once the entry expires.
+    { swr: false, getKey: (event) => event.path, ...cache === true ? {} : cache }
+  );
+  return defineEventHandler(async (event) => {
+    const bytes = new Uint8Array(Buffer.from(await renderCached(event), "base64"));
+    setPdfHeaders(event, send);
+    return bytes;
+  });
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jasy/nuxt",
+  "version": "1.0.0-alpha.1",
+  "description": "Author PDFs as Vue components in Nuxt - client or server, zero config.",
+  "license": "MIT",
+  "author": "Florian Heuberger",
+  "repository": {
+    "type": "git",
+    "url": "jasy-pdf/jasy"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.4.8",
+    "@jasy/pdf": "1.0.0-alpha.2",
+    "@jasy/vue": "1.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.4.8",
+    "@nuxt/test-utils": "^4.0.3",
+    "@types/node": "latest",
+    "nuxt": "^4.4.8",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.8",
+    "vue-tsc": "^3.3.3"
+  },
+  "scripts": {
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}