### Complete PDFEasy Plugin Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/plugins.md

A comprehensive example demonstrating the setup of PDFEasy with various plugin options, including custom headers, footers, backgrounds, and page-specific content.

```typescript
import pdfeasy from 'pdfeasy'

pdfeasy.new({
  document: {
    margins: { top: 50, bottom: 50, left: 50, right: 50 },
    size: 'A4'
  },
  plugins: [
    {
      // Run before content rendering
      onBefore: () => {
        console.log('Starting PDF generation')
      },

      // Background for every page
      background: (page) => {
        // Return a light gray background
        return '#F5F5F5'
        // Or return false to skip background
      },

      // Callbacks to render on each page after content
      page: [
        // Footer with page numbers
        ({ Text }, context, current, total) => {
          Text(`Page ${current}/${total}`, {
            fontSize: 10,
            color: '#999999'
          }, {
            x: context.width / 2,
            y: context.height - 30,
            widthAnchor: 'center',
            heightAnchor: 'center'
          })
        },

        // Header
        ({ Text }, context) => {
          Text('Company Logo Document', {
            fontSize: 12,
            bold: true,
            color: '#000000'
          }, {
            x: 50,
            y: 20
          })
        },

        // Side decoration
        ({ Text }, context, current) => {
          if (current === 1) {
            Text('CONFIDENTIAL', {
              fontSize: 48,
              color: '#CCCCCC',
              opacity: 0.2
            }, {
              x: context.width / 2,
              y: context.height / 2,
              widthAnchor: 'center',
              heightAnchor: 'center'
            })
          }
        }
      ],

      // Run after PDF finalization
      onAfter: () => {
        console.log('PDF generation complete')
      }
    }
  ]
})

// Add content
pdfeasy.add([
  { raw: 'Main Document', text: { fontSize: 24, bold: true } },
  { lineBreak: { spacing: 10 } },
  { raw: 'This document has headers, footers, and page numbers.', text: {} }
])

// Generate PDF
pdfeasy.run({
  type: 'client',
  clientEmit: 'blob'
}).then(blobUrl => {
  const iframe = document.querySelector('iframe')
  iframe.src = blobUrl
})
```

--------------------------------

### Install Dependencies

Source: https://github.com/betterwrite/pdfeasy/blob/main/packages/playground/README.md

Install project dependencies using npm, pnpm, or yarn.

```bash
# npm
npm install

# pnpm
pnpm install

# yarn
yarn install
```

--------------------------------

### Start Playground Development Server

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Starts the development server for the Nuxt playground application.

```bash
# Start playground dev server
pnpm play:dev
```

--------------------------------

### Start Core Package Demo

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Starts the Vite development server for the core package. This command should be run from the `packages/core` directory after building.

```bash
# Start demo (core package vite dev server, port 3000)
# Run from packages/core after building
pnpm demo
```

--------------------------------

### Install Dependencies

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Installs project dependencies using pnpm. Ensure pnpm is installed before running.

```bash
# Install deps (pnpm required)
pnpm install
```

--------------------------------

### Start Development Server

Source: https://github.com/betterwrite/pdfeasy/blob/main/packages/playground/README.md

Start the Nuxt 3 development server on http://localhost:3000 using npm, pnpm, or yarn.

```bash
# npm
npm run dev

# pnpm
pnpm run dev

# yarn
yarn dev
```

--------------------------------

### Install PDFEasy

Source: https://github.com/betterwrite/pdfeasy/blob/main/README.md

Install the PDFEasy library using npm.

```shell
npm i pdfeasy
```

--------------------------------

### usePDF() Usage Example - Warning vs. Correct

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Demonstrates incorrect usage of usePDF() at the module level (logs warning) and correct usage within a setup function.

```typescript
// ❌ This will log a warning
const pdf = usePDF()  // Called at module level

// ✅ This is correct
function myComponent() {
  const pdf = usePDF()  // Called inside setup
}
```

--------------------------------

### Install vue-pdfeasy and pdfeasy

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Install the necessary packages for Vue 3 integration with PDFEasy.

```bash
npm install vue-pdfeasy pdfeasy
```

--------------------------------

### Complete Nuxt 3 Configuration Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/nuxt-integration.md

A full example of the `nuxt.config.ts` file including the 'nuxt-pdfeasy' module and a compatibility date.

```typescript
export default defineNuxtConfig({
  modules: ['nuxt-pdfeasy'],
  compatibilityDate: '2024-01-01'
})
```

--------------------------------

### Example Plugin Implementation

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Demonstrates how to implement a plugin with custom background color, page numbering, and lifecycle hooks for PDF generation.

```typescript
pdfeasy.new({
  plugins: [
    {
      onBefore: () => {
        console.log('PDF generation starting')
      },
      background: (page) => {
        return '#F5F5F5'  // Light gray background
      },
      page: [
        ({ Text }, context, current, total) => {
          Text(`Page ${current}/${total}`, {},
            {
              x: context.width / 2,
              y: context.height - 30,
              widthAnchor: 'center'
            }
          )
        }
      ],
      onAfter: () => {
        console.log('PDF generation complete')
      }
    }
  ]
})
```

--------------------------------

### Install nuxt-pdfeasy and pdfeasy

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/nuxt-integration.md

Install the necessary packages for Nuxt 3 integration. This includes both the Nuxt module and the core PDFEasy library.

```bash
npm install nuxt-pdfeasy pdfeasy
```

--------------------------------

### Install Nuxt PDFEasy Module

Source: https://github.com/betterwrite/pdfeasy/blob/main/README.md

Install the Nuxt PDFEasy module using npm.

```bash
npm i nuxt-pdfeasy
```

--------------------------------

### Complete PDFeasy Utilities Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/utilities.md

This comprehensive example demonstrates how to use various utility functions from the PDFeasy library. It covers checking the execution environment, accessing default configurations, retrieving page sizes, testing regular expression patterns for URLs, base64 strings, and hex colors, converting hex to CMYK, and finally, creating and saving a simple PDF document with CMYK color schema.

```typescript
import pdfeasy, { 
  isBrowser, 
  pdfDefaults, 
  pageSizes, 
  regex,
  HEXToCMYK 
} from 'pdfeasy'

// Check environment
console.log('Running in browser:', isBrowser)

// Get default configuration
const defaults = pdfDefaults()
console.log('Default text size:', defaults.text.fontSize)

// Access page sizes
const sizes = pageSizes()
const [a4Width, a4Height] = sizes.A4
console.log(`A4: ${a4Width} × ${a4Height} points`)

// Test regex patterns
console.log(regex().http('https://example.com'))  // Has match
console.log(regex().base64('iVBORw0KGgo...'))     // Has match
console.log(regex().hex('#FF0000'))                // Has match

// Convert colors for print
const printColor = HEXToCMYK('#FF0000')
console.log('Print color (CMYK):', printColor)    // [0, 100, 100, 0]

// Use in PDF
pdfeasy.new({ document: { size: 'A4' } })
pdfeasy.add([
  { raw: 'Print Document', text: { color: '#FF0000' } }
])
pdfeasy.run({
  type: 'client',
  clientEmit: 'save',
  colorSchema: 'CMYK'
})
```

--------------------------------

### Registering a Background Plugin

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/plugins.md

Example of how to register a plugin to set a solid color or image as the background for each new page.

```typescript
import pdfeasy from 'pdfeasy'

pdfeasy.new({
  plugins: [
    {
      background: (page) => {
        // Return a color for solid background
        return '#F0F0F0'
        // Or return an image URL
        // return 'https://example.com/background.jpg'
      },
      page: []
    }
  ]
})
```

--------------------------------

### Vue 3 Setup

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Sets up the Vue application to use the PDFeasy plugin.

```typescript
import { createApp } from 'vue'
import { PDFPlugin } from 'vue-pdfeasy'
import App from './App.vue'

const app = createApp(App)
app.use(PDFPlugin)
app.mount('#app')
```

--------------------------------

### Complete Font Workflow Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/fonts-vfs.md

Demonstrates the full process of initializing pdfeasy, registering custom fonts, adding content that uses these fonts, and generating the PDF. Ensure font URLs are accessible.

```typescript
import pdfeasy from 'pdfeasy'

// Step 1: Initialize PDF
pdfeasy.new({
  document: {
    margins: { top: 40, bottom: 40, left: 70, right: 70 },
    size: 'A4'
  },
  advanced: {
    fontsPurge: true,  // Only load used fonts
    backgroundPurge: true
  }
})

// Step 2: Register custom fonts
pdfeasy.addFonts([
  {
    name: 'CustomSerif',
    normal: 'https://cdn.example.com/CustomSerif-Regular.ttf',
    bold: 'https://cdn.example.com/CustomSerif-Bold.ttf',
    italic: 'https://cdn.example.com/CustomSerif-Italic.ttf',
    bolditalic: 'https://cdn.example.com/CustomSerif-BoldItalic.ttf'
  },
  {
    name: 'CustomSans',
    normal: 'https://cdn.example.com/CustomSans-Regular.ttf',
    bold: 'https://cdn.example.com/CustomSans-Bold.ttf',
    italic: 'https://cdn.example.com/CustomSans-Italic.ttf',
    bolditalic: 'https://cdn.example.com/CustomSans-BoldItalic.ttf'
  }
])

// Step 3: Add content using custom fonts
pdfeasy.add([
  {
    raw: 'Title in Custom Serif',
    text: {
      font: 'CustomSerif',  // This font will be loaded
      fontSize: 24,
      bold: true  // Will use CustomSerif-Bold
    }
  },
  {
    raw: 'Body text in Custom Sans',
    text: {
      font: 'CustomSans',  // This font will also be loaded
      fontSize: 12
    }
  }
  // Note: If we had registered a third font but never referenced it,
  // it would NOT be loaded due to fontsPurge=true
])

// Step 4: Generate PDF
// During run(), setExternalFonts() is called automatically:
// - Detects fonts: 'CustomSerif' and 'CustomSans'
// - Fetches all 8 font files (4 variants × 2 fonts)
// - Registers them with PDFKit
// - Renders content using the custom fonts
pdfeasy.run({
  type: 'client',
  clientEmit: 'blob'
}).then(blobUrl => {
  window.open(blobUrl, '_blank')
})
```

--------------------------------

### Install Vue PDFEasy Plugin

Source: https://github.com/betterwrite/pdfeasy/blob/main/README.md

Install the Vue PDFEasy plugin using npm.

```shell
npm i vue-pdfeasy
```

--------------------------------

### PDFEasy Plugin Example: Background

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

An example of a plugin with a `background` hook. This hook runs before each content item and can inject a full-page background image.

```javascript
const myPlugin = {
  background: async (page, pdfKitDoc) => {
    // Add background image to the current page
    pdfKitDoc.image('path/to/background.png', 0, 0, { width: pdfKitDoc.page.width, height: pdfKitDoc.page.height });
  }
};

const pdf = new PDFEasy({ plugins: [myPlugin] });
```

--------------------------------

### Install PDFPlugin Globally

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Use the PDFPlugin to register a global PDFEasy instance accessible via $pdf.

```typescript
import { PDFPlugin } from 'vue-pdfeasy'

const app = createApp(App)
app.use(PDFPlugin)
app.mount('#app')
```

--------------------------------

### Initialize PDF Document with Options

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/pdfeasy.md

Initialize a new PDF document with custom options, including document dimensions, margins, and plugins. This example demonstrates adding a page number to each page.

```typescript
pdfeasy.new({
  document: {
    margins: {
      top: 40,
      bottom: 40,
      left: 70,
      right: 70
    },
    size: 'A4'
  },
  plugins: [
    {
      page: [
        ({ Text }, context, current, total) => {
          Text(`Page ${current}/${total}`, {}, { x: context.width / 2, y: 50 })
        }
      ]
    }
  ]
})
```

--------------------------------

### PDFEasy Plugin Example: Page Callbacks

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

An example of a plugin with `page` callbacks. These callbacks run after the entire PDF pipeline has finished, allowing for headers, footers, or page numbers to be added to buffered pages.

```javascript
const pageNumberPlugin = {
  page: async (pageNumber, pdfKitDoc) => {
    // Add page number to the bottom of the page
    pdfKitDoc.text(`Page ${pageNumber}`, 50, pdfKitDoc.page.height - 50);
  }
};

const pdf = new PDFEasy({ plugins: [pageNumberPlugin] });
```

--------------------------------

### Nuxt.js Setup

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Configure the nuxt-pdfeasy module in your nuxt.config.ts file.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-pdfeasy']
})
```

--------------------------------

### Vitest Test Environment Setup

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Configuration for Vitest tests using `happy-dom` as the test environment. This setup is typically found in `vitest.config.ts`.

```javascript
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'happy-dom',
    setupFiles: ['./vitest.setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html']
    }
  },
});
```

--------------------------------

### HTTP Font Registration Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/fonts-vfs.md

Illustrates registering fonts directly from HTTP URLs. This method is compatible with both client-side (browser) and server-side environments.

```typescript
pdfeasy.addFonts([
  {
    name: 'RemoteFont',
    normal: 'https://fonts.example.com/RemoteFont-Regular.ttf',
    bold: 'https://fonts.example.com/RemoteFont-Bold.ttf',
    italic: 'https://fonts.example.com/RemoteFont-Italic.ttf',
    bolditalic: 'https://fonts.example.com/RemoteFont-BoldItalic.ttf'
  }
])

// Works in both client and server modes
```

--------------------------------

### Generate Image Gallery PDF

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/http-images.md

A complete example demonstrating how to create a PDF document with an image gallery by iterating through an array of image URLs and embedding them.

```typescript
import pdfeasy from 'pdfeasy'

const images = [
  'https://example.com/photo1.jpg',
  'https://example.com/photo2.jpg',
  'https://example.com/photo3.jpg'
]

pdfeasy.new({
  document: {
    margins: { top: 20, bottom: 20, left: 20, right: 20 },
    size: 'A4'
  }
})

pdfeasy.add([
  { raw: 'Image Gallery', text: { fontSize: 24, bold: true } },
  { lineBreak: { spacing: 10 } }
])

// Add images
for (let i = 0; i < images.length; i++) {
  pdfeasy.add([
    {
      raw: images[i],
      image: {
        size: {
          width: 200,
          height: 200,
          scale: 1
        },
        x: 30,
        y: undefined  // Auto position
      }
    },
    { lineBreak: { spacing: 15 } }
  ])
}

pdfeasy.run({
  type: 'client',
  clientEmit: 'blob'
}).then(blobUrl => {
  window.open(blobUrl, '_blank')
}).catch(error => {
  console.error('Failed to generate PDF:', error)
})
```

--------------------------------

### runPluginBackground()

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/plugins.md

Executes background plugins at the start of each page. It iterates through registered plugins and calls the `background` callback if a new page is detected. The callback can return a color or image URL to set the page background.

```APIDOC
## runPluginBackground()

### Description
Executes background plugins at the start of each page. It iterates through registered plugins and calls the `background` callback if a new page is detected. The callback can return a color or image URL to set the page background.

### Method
`runPluginBackground(instance: PDFEasy): Promise<void>`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
* **instance** (`PDFEasy`) - Required - PDFEasy instance with plugins

### Request Example
```ts
import pdfeasy from 'pdfeasy'

pdfeasy.new({
  plugins: [
    {
      background: (page) => {
        // Return a color for solid background
        return '#F0F0F0'
        // Or return an image URL
        // return 'https://example.com/background.jpg'
      },
      page: []
    }
  ]
})
```

### Response
#### Success Response (200)
`Promise<void>`

#### Response Example
```json
// No specific JSON response example, returns a Promise that resolves to void.
```

### Behavior
- Iterates through all registered plugins
- For each plugin with a `background` callback:
  - Checks if `__NEW_PAGE__` flag is true (new page started)
  - Calls `background(page)` callback
  - If callback returns a truthy string, calls `setBackground()` to render background
- Sets `__NEW_PAGE__` to false after processing

### Background Callback Return Value
- Return falsy value to skip background rendering
- Return a hex color string (e.g., '#FF0000') to fill page with solid color
- Return an image URL or base64 string to render image background
```

--------------------------------

### Vue App Setup with PDFPlugin

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Configure your main Vue application to use the PDFEasy plugin. This involves importing the plugin and calling `app.use()` before mounting the app.

```vue
<script setup lang="ts">
import { PDFPlugin } from 'vue-pdfeasy'
import PDFGenerator from './components/PDFGenerator.vue'
</script>

<template>
  <div id="app">
    <PDFGenerator />
  </div>
</template>

<style>
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
    Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
  background: #fff;
}

#app {
  padding: 20px;
}
</style>
```

```ts
import { createApp } from 'vue'
import { PDFPlugin } from 'vue-pdfeasy'
import App from './App.vue'

const app = createApp(App)

// Install PDFEasy plugin
app.use(PDFPlugin)

app.mount('#app')
```

--------------------------------

### Vue 3 PDF Generation

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/README.md

Shows how to use the `vue-pdfeasy` composable to generate PDFs within a Vue 3 application. This example generates a PDF and opens it in a new window.

```vue
<script setup>
import { usePDF } from 'vue-pdfeasy'

const pdf = usePDF()

const generatePDF = async () => {
  pdf.new({ document: { size: 'A4' } })
  pdf.add([{ raw: 'Hello Vue', text: {} }])
  const url = await pdf.run({ type: 'client', clientEmit: 'blob' })
  window.open(url)
}
</script>
```

--------------------------------

### Generate PDF using Global Property $pdf

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Example of generating a PDF in a Vue component using the global $pdf property accessed via getCurrentInstance.

```vue
<template>
  <div>
    <button @click="generatePDF">Generate PDF</button>
  </div>
</template>

<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const generatePDF = async () => {
  const instance = getCurrentInstance()
  const pdf = instance?.appContext.config.globalProperties.$pdf
  
  if (!pdf) return
  
  pdf.new({
    document: { margins: { top: 40, bottom: 40, left: 70, right: 70 } }
  })
  
  pdf.add([
    { raw: 'Hello from Vue!', text: { fontSize: 20, bold: true } }
  ])
  
  await pdf.run({
    type: 'client',
    clientEmit: 'blob'
  }).then(blobUrl => {
    window.open(blobUrl, '_blank')
  })
}
</script>
```

--------------------------------

### Font Purging Example with HTTP Fonts

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/fonts-vfs.md

Demonstrates registering multiple font variants from HTTP URLs and adding content that references specific fonts. Only the referenced fonts will be loaded and registered during the run phase.

```typescript
pdfeasy.addFonts([
  {
    name: 'Roboto',
    normal: 'https://cdn.example.com/Roboto-Regular.ttf',
    bold: 'https://cdn.example.com/Roboto-Bold.ttf',
    italic: 'https://cdn.example.com/Roboto-Italic.ttf',
    bolditalic: 'https://cdn.example.com/Roboto-BoldItalic.ttf'
  },
  {
    name: 'Open Sans',
    normal: 'https://cdn.example.com/OpenSans-Regular.ttf',
    bold: 'https://cdn.example.com/OpenSans-Bold.ttf',
    italic: 'https://cdn.example.com/OpenSans-Italic.ttf',
    bolditalic: 'https://cdn.example.com/OpenSans-BoldItalic.ttf'
  }
])

pdfeasy.add([
  { raw: 'This uses Roboto', text: { font: 'Roboto' } },
  // Note: Open Sans is NOT used, so it won't be loaded
])

// During run(), only Roboto is fetched and registered
await setExternalFonts(pdfeasy)
```

--------------------------------

### Font Variant Resolution Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/fonts-vfs.md

Demonstrates how font families and variants are resolved for styling text. This shows the mapping from style properties to PDFKit font names.

```typescript
// When rendering text with bold=true and italic=false:
const fontName = resolveFontFamily('Roboto', { bold: true })
// Returns: 'Roboto-Bold'

// Then during registration, the variant name is resolved:
const registeredName = resolveFontName('Roboto', 'bold')
// Returns: 'Roboto-Bold'

// PDFKit then uses: doc.font('Roboto-Bold')
```

--------------------------------

### Generate PDF with Custom Headers and Footers in Nuxt3

Source: https://github.com/betterwrite/pdfeasy/blob/main/packages/nuxt/README.md

Example demonstrating how to generate a PDF with custom headers and footers using the PDFEasy module in Nuxt3. This includes adding text content and configuring plugins for page numbering and headers.

```typescript
<template>
  <iframe id="pdf" />
</template>

<script setup>
import { useNuxtApp } from '#app';

const { $pdf } = useNuxtApp()

$pdf.new({
  plugins: [
    {
      page: [
        // simple counter footer
        ({ Text }, context, current, total) => {
          // render in every page
          Text(`${current}/${total}`, { fontSize: 20 }, {
            x: context.width / 2,
            y: context.height - context.margins.bottom
          })
        },
        // simple header
        ({ Text }, context, current, total) => {
          // render in every page
          Text('A Simple Header', {}, {
            x: context.width / 2,
            y: context.margins.top - 20
          })
        }
      ]
    }
  ]
})

$pdf.add([
  { raw: 'Hello NUXT!', text: { fontSize: 22 }},
])

$pdf.run().then(blob => {
  const iframe = document.querySelector('#pdf')

  iframe.src = blob
}).catch((err) => {
  console.error(err)
})
</script>
```

--------------------------------

### Initialize PDF

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/README.md

Initializes a new PDF document with specified size and margins. Use this to set up the document before adding content.

```typescript
pdfeasy.new({
  document: {
    size: 'A4',
    margins: { top: 40, bottom: 40, left: 70, right: 70 }
  }
})
```

--------------------------------

### Correct Usage of usePDF Hook in Vue

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Ensure `usePDF()` is called within the `<script setup>` or `setup()` function to avoid 'Vue instance not exists' warnings. Calling it at the module level is incorrect.

```typescript
// ❌ Wrong - at module level
const pdf = usePDF()

// ✅ Correct - inside setup
export default {
  setup() {
    const pdf = usePDF()
    return { pdf }
  }
}
```

--------------------------------

### Initialize PDF with Margins and Size

Source: https://github.com/betterwrite/pdfeasy/blob/main/README.md

Create a new PDF document instance with custom margins and page size.

```typescript
pdfeasy.new({
  margins: {
    top: 10,
    bottom: 10,
    left: 10,
    right: 10
  },
  size: "a5"
});
```

--------------------------------

### Vue PDFEasy Plugin Setup

Source: https://github.com/betterwrite/pdfeasy/blob/main/README.md

Integrate the PDFEasy plugin into a Vue application.

```typescript
import { PDFPlugin } from 'vue-pdfeasy';

const app = createApp(App);
app.use(PDFPlugin);
app.mount('#app');

// ...

<script setup>
import { usePDF } from 'vue-pdfeasy';

const pdf = usePDF()

pdf.new()
// ...
</script>
```

--------------------------------

### Basic PDF Generation

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Demonstrates the basic workflow of initializing PDFEasy, adding content, and generating a PDF as a blob URL.

```typescript
import pdfeasy from 'pdfeasy'

// 1. Initialize
pdfeasy.new({
  document: {
    margins: { top: 40, bottom: 40, left: 70, right: 70 },
    size: 'A4'
  }
})

// 2. Add content
pdfeasy.add([
  { raw: 'Hello World', text: { fontSize: 20, bold: true } },
  { lineBreak: { spacing: 10 } },
  { raw: 'This is a PDF', text: { fontSize: 12 } }
])

// 3. Generate
pdfeasy.run({
  type: 'client',
  clientEmit: 'blob'
}).then(blobUrl => {
  window.open(blobUrl, '_blank')
})
```

--------------------------------

### Preview Production Build

Source: https://github.com/betterwrite/pdfeasy/blob/main/packages/playground/README.md

Locally preview the production build of the Nuxt 3 application using npm, pnpm, or yarn.

```bash
# npm
npm run preview

# pnpm
pnpm run preview

# yarn
yarn preview
```

--------------------------------

### Server-Side PDF Generation in API Route

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/nuxt-integration.md

Example of generating a PDF report on the server using fetched data.

```typescript
// server/api/report.ts
import { defineEventHandler } from 'h3'
import { PDFEasy } from 'pdfeasy'

export default defineEventHandler(async (event) => {
  const pdf = new PDFEasy()

  pdf.new({
    document: {
      margins: { top: 40, bottom: 40, left: 70, right: 70 },
      size: 'A4'
    },
    exports: {
      name: 'report'
    }
  })

  // Fetch data (example)
  const data = await $fetch('/api/data')

  // Build PDF content
  const content = [
    { raw: 'Monthly Report', text: { fontSize: 20, bold: true } },
    { lineBreak: { spacing: 15 } },
    ...data.items.map(item => ({
      raw: `${item.name}: ${item.value}`,
      text: { fontSize: 12 }
    }))
  ]

  pdf.add(content)

  // Generate and save
  await pdf.run({
    type: 'server',
    serverPath: '/reports',
    cwd: process.cwd()
  })

  // Return success response
  return { status: 'success', file: 'report.pdf' }
})
```

--------------------------------

### Vanilla JavaScript PDF Generation

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/README.md

Demonstrates basic PDF generation in vanilla JavaScript, including initialization, adding content, and opening the generated PDF in a new tab.

```javascript
import pdfeasy from 'pdfeasy'

pdfeasy.new({ document: { size: 'A4' } })
pdfeasy.add([{ raw: 'Hello', text: {} }])
const url = await pdfeasy.run({ type: 'client', clientEmit: 'blob' })
window.open(url)
```

--------------------------------

### Core Package Build (Production)

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Builds the core PDFEasy package for production, including minification. Run this command from the `packages/core` directory.

```bash
# Build (prod)
pnpm build:prod
```

--------------------------------

### Build for Production

Source: https://github.com/betterwrite/pdfeasy/blob/main/packages/playground/README.md

Build the Nuxt 3 application for production deployment using npm, pnpm, or yarn.

```bash
# npm
npm run build

# pnpm
pnpm run build

# yarn
yarn build
```

--------------------------------

### Build Packages (Production)

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Builds all packages in the monorepo for production, including minification.

```bash
# Build all packages (production, minified)
pnpm build:prod
```

--------------------------------

### Get Default PDF Configuration

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/utilities.md

Retrieves the default styling and layout settings for PDF generation. These defaults can be overridden globally using `pdfeasy.defaults()`.

```typescript
export const pdfDefaults(): PDFEasyDefaults
```

```json
{
  text: {
    fontSize: 16,
    font: 'Times-Roman',
    color: 'black',
    indent: 0,
    align: 'justify',
    paragraphMargin: 0,
    lineHeight: 0,
    opacity: 1,
    destination: undefined,
    go: undefined,
    bold: false,
    italic: false
  },
  lineBreak: {
    spacing: 5
  },
  pageBreak: {
    pages: 1
  },
  checkbox: {
    borderColor: '#000',
    backgroundColor: '#fff',
    size: 10
  },
  list: {
    style: 'circle'
  }
}
```

```typescript
import pdfeasy from 'pdfeasy'

// Set custom defaults
pdfeasy.defaults({
  text: {
    fontSize: 12,
    font: 'Helvetica',
    color: '#333333',
    indent: 0,
    align: 'left',
    paragraphMargin: 5,
    lineHeight: 1.5,
    opacity: 1,
    destination: undefined,
    go: undefined,
    bold: false,
    italic: false
  },
  lineBreak: { spacing: 3 },
  pageBreak: { pages: 1 },
  checkbox: { borderColor: '#000', backgroundColor: '#fff', size: 10 },
  list: { style: 'circle' }
})

// All future content uses these defaults
```

--------------------------------

### PDF Initialization with RunnerOptions

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Configure PDF generation behavior during initialization. Use this to set cover images, advanced font/background purging, document dimensions, margins, and export settings.

```typescript
interface RunnerOptions {
  cover?: string
  advanced?: RunnerOptionsAdvanced
  document?: PDFKit.PDFDocumentOptions
  exports?: RunnerOptionsExports
  plugins?: Plugin[]
}
```

```typescript
pdfeasy.new({
  cover: 'https://example.com/cover.jpg',
  advanced: {
    fontsPurge: true,
    backgroundPurge: true
  },
  document: {
    size: 'A4',
    margins: {
      top: 40,
      bottom: 40,
      left: 70,
      right: 70
    },
    bufferPages: false
  },
  exports: {
    name: 'My Document'
  },
  plugins: []
})
```

--------------------------------

### CMYK Color Schema Conversion

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Set the colorSchema to 'CMYK' to enable CMYK color conversion for print-accurate colors. This example shows the conversion for red.

```typescript
await pdfeasy.run({
  colorSchema: 'CMYK'  // #FF0000 → [0, 100, 100, 0]
})
```

--------------------------------

### Nuxt Route Middleware for PDF Request

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/nuxt-integration.md

Example of creating a Nuxt route middleware to detect if a PDF generation is requested via query parameters.

```typescript
// middleware/pdf.ts
export default defineNuxtRouteMiddleware((to, from) => {
  if (to.query.pdf) {
    // User requested PDF generation
    // Can be handled in page setup
  }
})
```

--------------------------------

### PDFEasy Core Class Initialization

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Initializes the PDFEasy core library. The `new()` method resets state and sets up a PDFDocumentWithTables instance. It can automatically enable `bufferPages` if plugin page callbacks are present.

```javascript
import PDFEasy from 'pdfeasy';

// Initialize with options
const pdf = new PDFEasy({ /* options */ });
```

--------------------------------

### PDF Execution with RunOptions (Client Blob)

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Execute PDF generation in the client environment and receive the output as a blob URL. Ensure the 'clientEmit' option is set to 'blob'.

```typescript
interface RunOptions {
  type: 'client' | 'server' | 'auto'
  clientEmit: PDFRunEmitOption
  serverPath: string
  colorSchema: ColorSchema
  cwd: string
}
```

```typescript
await pdfeasy.run({
  type: 'client',
  clientEmit: 'blob',
  colorSchema: 'RGB'
})
```

--------------------------------

### CORS Restrictions Example

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/http-images.md

Highlights a potential failure when loading images from a different domain due to CORS restrictions, indicating the need for proper CORS headers.

```typescript
// This will fail if example.com doesn't send CORS headers
const result = await getRequestImageRaw('https://example.com/image.png')
// Error: "Failed to load image from CORS-protected resource"
```

--------------------------------

### Complete PDF Generation Workflow

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/pdfeasy.md

This snippet shows the full process of creating a PDF, from initialization to generation. It includes optional steps for adding custom fonts and setting default styles. The PDF is generated as a blob URL and opened in a new tab.

```typescript
import pdfeasy from 'pdfeasy'

// Step 1: Initialize a new PDF
pdfeasy.new({
  document: {
    margins: { top: 40, bottom: 40, left: 70, right: 70 },
    size: 'A4'
  }
})

// Step 2: Add custom fonts (optional)
pdfeasy.addFonts([
  {
    name: 'Roboto',
    normal: 'https://example.com/fonts/Roboto-Regular.ttf',
    italic: 'https://example.com/fonts/Roboto-Italic.ttf',
    bold: 'https://example.com/fonts/Roboto-Bold.ttf',
    bolditalic: 'https://example.com/fonts/Roboto-BoldItalic.ttf'
  }
])

// Step 3: Set defaults (optional)
pdfeasy.defaults({
  text: {
    fontSize: 12,
    font: 'Roboto',
    color: '#000000',
    align: 'left',
    paragraphMargin: 5,
    lineHeight: 1.2,
    indent: 0,
    opacity: 1,
    destination: undefined,
    go: undefined,
    bold: false,
    italic: false
  },
  lineBreak: { spacing: 3 },
  pageBreak: { pages: 1 },
  checkbox: { borderColor: '#000', backgroundColor: '#fff', size: 10 },
  list: { style: 'circle' }
})

// Step 4: Add content
pdfeasy.add([
  { raw: 'Document Title', text: { fontSize: 24, bold: true } },
  { lineBreak: { spacing: 10 } },
  { raw: 'This is a paragraph of text.', text: { fontSize: 12 } },
  { lineBreak: { spacing: 5 } },
  { raw: 'https://example.com/image.jpg', image: { size: { width: 200, height: 150 } } }
])

// Step 5: Generate PDF
pdfeasy.run({
  type: 'client',
  clientEmit: 'blob',
  colorSchema: 'RGB'
}).then((blobUrl) => {
  window.open(blobUrl, '_blank')
}).catch((error) => {
  console.error('Failed to generate PDF:', error)
})
```

--------------------------------

### PDF Execution with RunOptions (Server)

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Execute PDF generation on the server and specify the output directory. Ensure 'type' is 'server' and provide a valid 'serverPath'.

```typescript
await pdfeasy.run({
  type: 'server',
  serverPath: '/pdfs',
  cwd: process.cwd(),
  colorSchema: 'RGB'
})
```

--------------------------------

### Core Package Build (Development)

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Builds the core PDFEasy package in development mode. Run this command from the `packages/core` directory.

```bash
# Build (dev)
pnpm build
```

--------------------------------

### Add Custom Header to PDF in Vue

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/vue-integration.md

Configure PDFEasy with plugins to add a custom header to each page. This example demonstrates adding a 'Company Report' title to the top of the document.

```vue
<script setup lang="ts">
import { usePDF } from 'vue-pdfeasy'

const pdf = usePDF()

const generatePDFWithHeader = async () => {
  pdf.new({
    document: { margins: { top: 60, bottom: 40, left: 70, right: 70 } },
    plugins: [
      {
        page: [
          ({ Text }, context) => {
            Text('Company Report', 
              { fontSize: 14, bold: true }, 
              { x: 70, y: 30 }
            )
          }
        ]
      }
    ]
  })
  
  pdf.add([
    { raw: 'Report Content', text: { fontSize: 12 } }
  ])
  
  await pdf.run({ type: 'client', clientEmit: 'blob' })
}
</script>
```

--------------------------------

### Run All Tests

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Executes all tests in the repository. This command first builds the core package in production mode and then runs Vitest.

```bash
# Run all tests (builds core first, then runs vitest)
pnpm test
```

--------------------------------

### Generate PDF on Server-Side (API Route)

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/nuxt-integration.md

Create a server API route in Nuxt to generate PDFs on the server. This example demonstrates instantiating PDFEasy directly within the API handler.

```typescript
// server/api/generate-pdf.ts
import { defineEventHandler } from 'h3'
import { PDFEasy } from 'pdfeasy'

export default defineEventHandler(async (event) => {
  const pdf = new PDFEasy()
  
  pdf.new({
    document: { margins: { top: 40, bottom: 40, left: 70, right: 70 } }
  })
  
  pdf.add([
    { raw: 'Server-Generated PDF', text: { fontSize: 20 } }
  ])
  
  const result = await pdf.run({
    type: 'server',
    serverPath: '/tmp'
  })
  
  return { status: 'success', result }
})
```

--------------------------------

### RunOptions

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/types.md

Defines the comprehensive configuration options for the `run()` method, specifying the execution environment, output formats, server paths, color schemas, and working directory.

```APIDOC
## RunOptions

Configuration for `run()` method.

### Fields:

| Field | Type | Default | Description |
|---|---|---|---|
| `type` | `'client' | 'server' | 'auto'` | — | Execution environment |
| `clientEmit` | `PDFRunEmitOption` | 'blob' | Client output format |
| `serverPath` | `string` | '/' | Server-side output directory |
| `colorSchema` | `'RGB' | 'CMYK'` | 'RGB' | Color space conversion |
| `cwd` | `string` | `process.cwd()` | Working directory for relative paths |
```

--------------------------------

### Build Packages (Development)

Source: https://github.com/betterwrite/pdfeasy/blob/main/CLAUDE.md

Builds all packages in the monorepo in development mode.

```bash
# Build all packages (dev mode)
pnpm build
```

--------------------------------

### Initialize PDFKit Document Correctly

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/errors.md

Ensure `new()` is called before `run()` to initialize the PDFKit document instance. This prevents 'PDFKit not exists' errors.

```typescript
// ❌ Wrong - Missing new()
const pdf = new PDFEasy()
pdf.add([{ raw: 'Hello' }])
await pdf.run()  // Error!

// ✅ Correct - Call new() first
const pdf = new PDFEasy()
pdf.new()  // Initialize document
pdf.add([{ raw: 'Hello' }])
await pdf.run()
```

--------------------------------

### PDF Execution with RunOptions (Client Save)

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Execute PDF generation in the client environment and trigger a file download. Set 'clientEmit' to 'save' for this behavior.

```typescript
await pdfeasy.run({
  type: 'client',
  clientEmit: 'save',
  colorSchema: 'RGB'
})
```

--------------------------------

### Client-Side PDF Configuration

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/configuration.md

Configures PDF generation for a browser environment, including document size, margins, adding custom fonts, and running the PDF generation process to get a blob URL.

```typescript
// Browser environment
pdfeasy.new({
  document: {
    size: 'A4',
    margins: { top: 40, bottom: 40, left: 70, right: 70 }
  }
})

pdfeasy.addFonts([
  {
    name: 'Roboto',
    normal: 'https://fonts.gstatic.com/s/roboto/v29/KFOmCnqEu92Fr1Mu4mxM.ttf',
    // ... other variants
  }
])

pdfeasy.add([/* ... */])

const blobUrl = await pdfeasy.run({
  type: 'client',
  clientEmit: 'blob',
  colorSchema: 'RGB'
})
```

--------------------------------

### Nuxt 3 PDF Generation

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/README.md

Illustrates PDF generation in a Nuxt 3 application using the `$pdf` injection provided by the `vue-pdfeasy` module. This example generates a PDF but does not explicitly show how it's handled after generation.

```vue
<script setup>
const { $pdf } = useNuxtApp()

const generatePDF = async () => {
  $pdf.new({ document: { size: 'A4' } })
  $pdf.add([{ raw: 'Hello Nuxt', text: {} }])
  await $pdf.run({ type: 'client', clientEmit: 'blob' })
}
</script>
```

--------------------------------

### Basic PDF Generation with Error Handling

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Demonstrates basic PDF generation using pdfeasy.new(), pdfeasy.add(), and pdfeasy.run(). Always wrap PDF generation logic in a try-catch block to handle potential errors.

```typescript
try {
  pdfeasy.new()
  pdfeasy.add(contentData)
  const result = await pdfeasy.run({
    type: 'client',
    clientEmit: 'blob'
  })
  window.open(result)
} catch (error) {
  console.error('PDF generation failed:', error)
  alert('Failed to generate PDF')
}
```

--------------------------------

### Configure Advanced Options

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Initialize PDFEasy with advanced options for font and background caching.

```typescript
pdfeasy.new({
  advanced: {
    fontsPurge: true,      // Load only referenced fonts
    backgroundPurge: true  // Cache background images
  }
})
```

--------------------------------

### Add Content Before Running

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/errors.md

Always add content using `add()` before calling `run()` to avoid the 'Are you sure you added the contents before using this command?' error. Ensure the contents array is not empty.

```typescript
// ❌ Wrong - Empty content
const pdf = new PDFEasy()
pdf.new()
await pdf.run()  // Error!

// ✅ Correct - Add content first
const pdf = new PDFEasy()
pdf.new()
pdf.add([{ raw: 'Document content' }])
await pdf.run()
```

--------------------------------

### run()

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/api-reference/pdfeasy.md

Executes the PDF rendering pipeline, producing the final PDF output. It handles validation, plugin execution, content rendering, and output formatting based on specified options.

```APIDOC
## run()

### Description
Executes the PDF rendering pipeline, producing the final PDF output. It handles validation, plugin execution, content rendering, and output formatting based on specified options.

### Method
```ts
public run(options?: Partial<RunOptions>): Promise<string>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **options** (`Partial<RunOptions>`) - Optional - Runtime execution options.

### Request Example
#### Client-Side (Blob)
```ts
pdfeasy.run({
  type: 'client',
  clientEmit: 'blob',
  colorSchema: 'RGB'
}).then((blobUrl) => {
  const iframe = document.querySelector('#pdf') as HTMLIFrameElement
  iframe.src = blobUrl
}).catch((error) => {
  console.error('PDF generation failed:', error)
})
```

#### Client-Side (Save)
```ts
pdfeasy.run({
  type: 'client',
  clientEmit: 'save'
}).then(() => {
  console.log('PDF saved to downloads')
})
```

#### Server-Side
```ts
pdfeasy.run({
  type: 'server',
  serverPath: '/pdfs',
  cwd: process.cwd()
}).then(() => {
  console.log('PDF written to disk')
})
```

### Response
#### Success Response (Promise<string>)
Returns a promise that resolves with a blob URL string if `clientEmit: 'blob'`, the string `'done'` for other client emit modes or server mode, or rejects with an error string if validation fails.

#### Response Example
(See Request Example for promise resolution values)

### Error Handling
* Throws `'PDFKit not exists. Did you forget to call new() function before calling run()?'` if pdfkit is not initialized.
* Throws `'Are you sure you added the contents before using this command?'` if no content has been added.
* Throws `'Pipeline error.'` if an error occurs during content rendering.
* Throws `'Client emit is wrong!'` if an invalid clientEmit mode is specified.
```

--------------------------------

### Run Method Configuration Interface

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/types.md

Defines the configuration options for the `run()` method, specifying the execution environment, output paths, and color schema.

```typescript
interface RunOptions {
  type: 'client' | 'server' | 'auto'
  clientEmit: PDFRunEmitOption
  serverPath: string
  colorSchema: ColorSchema
  cwd: string
}
```

--------------------------------

### Runtime Options Configuration

Source: https://github.com/betterwrite/pdfeasy/blob/main/_autodocs/GUIDE.md

Configure PDF generation behavior, including output type, client-side emission, color schema, server path, and working directory.

```typescript
pdfeasy.run({
  type: 'client',           // 'client' | 'server' | 'auto'
  clientEmit: 'blob',       // 'blob' | 'save' | 'open-link' | 'none'
  colorSchema: 'RGB',       // 'RGB' | 'CMYK' (for print)
  serverPath: '/pdfs',      // Server output directory
  cwd: process.cwd()        // Working directory for relative paths
})
```