@signiphi/pdf-signer 0.1.1

package/INSTALLING_LOCALLY.md

@@ -0,0 +1,184 @@
+# Installing @signiphi/pdf-signer Locally
+
+This guide covers installing the package from a local directory (useful for testing or development).
+
+## The Issue with Local Installations
+
+When installing packages using `file:` protocol (e.g., `npm install file:../pdf-signer` or `npm install ./local-package`), **npm may not run postinstall scripts**. This is a known npm behavior for local file dependencies.
+
+Since @signiphi/pdf-signer relies on a postinstall script to copy PDF.js viewer files to your `public/` directory, you need to run an additional setup step after installation.
+
+## Installation Steps
+
+### 1. Install the Package
+
+```bash
+# From your project directory
+npm install file:path/to/pdf-signer
+
+# Or with a relative path in package.json
+npm install
+```
+
+**Expected behavior:** Package installs but postinstall script may not run.
+
+### 2. Run the Setup Script
+
+After installation, manually run the setup script:
+
+```bash
+npx signiphi-setup
+```
+
+Or explicitly:
+
+```bash
+node node_modules/@signiphi/pdf-signer/scripts/postinstall.js
+```
+
+**Expected output:**
+```
+✓ @signiphi/pdf-signer: PDF.js files copied to C:\Your\Project\public\pdfjs
+```
+
+### 3. Verify Installation
+
+Check that the viewer files exist:
+
+```bash
+ls public/pdfjs/web/viewer.html
+```
+
+You should see:
+```
+public/
+  pdfjs/
+    build/
+      pdf.worker.mjs
+      pdf.mjs
+      ...
+    web/
+      viewer.html       ← Custom viewer for PDF.js 5.x
+      pdf_viewer.mjs
+      pdf_viewer.css
+      images/
+    .version
+```
+
+## Alternative: Use Integration Plugins
+
+For Vite or Next.js projects, use the build-time integration plugins which handle file copying automatically:
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { signiphiPdfJs } from '@signiphi/pdf-signer/vite';
+
+export default defineConfig({
+  plugins: [signiphiPdfJs()],
+});
+```
+
+### Next.js
+
+```javascript
+// next.config.js
+const { withSigniphiPdfJs } = require('@signiphi/pdf-signer/next');
+
+module.exports = withSigniphiPdfJs({
+  // your next.js config
+});
+```
+
+## Why This Happens
+
+npm treats `file:` dependencies differently from registry packages:
+
+1. **Registry packages** (from npmjs.com): postinstall scripts run automatically
+2. **Local file: packages**: npm may skip lifecycle scripts to avoid side effects during local development
+
+This is by design to prevent accidentally running scripts when symlinking or linking local packages during development.
+
+## Production Installations
+
+When your package is published to npm and users install it normally, the postinstall script **will run automatically**:
+
+```bash
+npm install @signiphi/pdf-signer
+# ✓ Postinstall runs automatically
+# ✓ PDF.js files copied to public/pdfjs/
+```
+
+## Troubleshooting
+
+### postinstall didn't run
+
+**Solution:** Run manually with `npx signiphi-setup`
+
+### "viewer.html not found" error
+
+This means the PDF.js files weren't copied. Run:
+
+```bash
+npx signiphi-setup --force
+```
+
+### Files copied to wrong location
+
+Specify the target directory:
+
+```bash
+npx signiphi-setup public/my-custom-path
+```
+
+Then configure your app:
+
+```typescript
+import { setPdfJsConfig } from '@signiphi/pdf-signer';
+
+setPdfJsConfig({
+  viewerBasePath: '/my-custom-path'
+});
+```
+
+### Still not working?
+
+1. Check that pdfjs-dist is installed:
+   ```bash
+   ls node_modules/pdfjs-dist
+   ```
+
+2. Verify the assets directory exists in the package:
+   ```bash
+   ls node_modules/@signiphi/pdf-signer/assets/viewer.html
+   ```
+
+3. Check for errors:
+   ```bash
+   node node_modules/@signiphi/pdf-signer/scripts/postinstall.js
+   ```
+
+4. Check the runtime error message in your browser console for specific guidance
+
+## Testing After Installation
+
+Create a simple test to verify everything works:
+
+```tsx
+import { PdfViewerStyled } from '@signiphi/pdf-signer';
+import '@signiphi/pdf-signer/styles';
+
+function App() {
+  return (
+    <PdfViewerStyled
+      pdfUrl="/path/to/test.pdf"
+      onLoad={() => console.log('PDF loaded successfully!')}
+      onError={(error) => console.error('PDF load error:', error)}
+    />
+  );
+}
+```
+
+If you see the PDF render, everything is working correctly!

package/LICENSE

@@ -0,0 +1,2 @@
+
+Copyright (c) 2025 Xigniphi