Skip to content

basic-usage.mdx

Latest commit

 

History

History
198 lines (134 loc) · 3.5 KB

basic-usage.mdx

File metadata and controls

198 lines (134 loc) · 3.5 KB
Raw

Basic Astro usage

The ClearHowGuide Private PDF Compressor is designed to be integrated into Astro projects.

Required layout

Preserve these paths in your Astro project:

src/components/tools/PdfCompressor.astro
src/workers/wise-pdf.worker.js
public/tools/pdf-compressor/pdf-engine.wasm
public/tools/pdf-compressor/pdf-worker.js
public/tools/pdf-compressor/wasm_exec.js
vendor/wise-pdf/

Import the component

Import the compressor into an Astro or MDX page:

---
import PdfCompressor from '../components/tools/PdfCompressor.astro';
---

<PdfCompressor />

Adjust the relative import path if your page is located in a different directory.

Required dependencies

The compressor requires the following JavaScript dependencies:

pdfjs-dist
@jsquash/jpeg
@jsquash/oxipng
@ecgear/wise-pdf

The ClearHowGuide version of wise-pdf is vendored in:

vendor/wise-pdf/ecgear-wise-pdf-0.1.0-clearhowguide.1.tgz

Install project dependencies with:

npm install

Vite configuration

Wise PDF should be excluded from Vite dependency pre-bundling.

Add the following configuration to your Astro configuration:

import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    optimizeDeps: {
      exclude: [
        '@ecgear/wise-pdf',
        '@ecgear/wise-pdf/worker',
      ],
    },
  },
});

Public runtime files

Lossless Optimize requires these files to remain available below:

/tools/pdf-compressor/

Required files:

pdf-engine.wasm
pdf-worker.js
wasm_exec.js

Their source locations in this repository are:

public/tools/pdf-compressor/pdf-engine.wasm
public/tools/pdf-compressor/pdf-worker.js
public/tools/pdf-compressor/wasm_exec.js

Do not rename or move these files unless you also update the paths used by the compressor.

Compression modes

The current implementation provides three modes.

Lossless Optimize

Uses:

Go
WebAssembly
pdfcpu 0.15.0

Lossless Optimize attempts to preserve the original PDF structure and avoids intentional image-quality reduction.

Balanced

Uses the ClearHowGuide wise-pdf integration with approximately:

180 DPI
JPEG quality 82

Pages are rasterized, so selectable text, hyperlinks, forms, accessibility tags and other interactive PDF features may be lost.

Maximum Compression

Uses stronger rasterization with approximately:

120 DPI
JPEG quality 60

This mode prioritizes a smaller output file over preservation of the original PDF structure.

Browser-side processing

PDF processing is performed locally in the browser using:

Web Workers
WebAssembly
PDF.js
pdfcpu
wise-pdf

The compressor itself does not require the selected PDF to be uploaded to ClearHowGuide, PocketBase, Cloudflare R2 or a remote compression server.

Rebuilding the Lossless WebAssembly engine

If you modify the Go/pdfcpu source code, rebuild the WebAssembly engine with:

npm run build:wasm

The build script uses:

src/wasm/pdf-compressor/main.go

and generates:

public/tools/pdf-compressor/pdf-engine.wasm
public/tools/pdf-compressor/wasm_exec.js

Run repository checks

Before publishing changes, run:

npm run check

Or run the checks separately:

npm run check:structure
npm run check:privacy

Live implementation

Official ClearHowGuide tool:

https://clearhowguide.com/en/tools/pdf-compressor/

Full guide:

https://clearhowguide.com/en/files/compress-pdf-without-losing-quality/