Skip to main content
skill CX Codex

add-pdf-viewer — Claude Code skill: what it does, how to install

add-pdf-viewer configures a native PDF viewer wrapper for HTTPS links and file:// URIs in Power Platform mobile projects.

MIT ★ 1,167 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add microsoft/power-platform-skills
/plugin install mobile-app@power-platform-skills
Open on GitHub

What add-pdf-viewer does

This internal skill runs under /add-native inside Claude Code. It inspects the project root to ensure app.config.js, power.config.json, package.json, and the src folder are present. If the app is missing these files, execution halts immediately.

The helper then verifies that @microsoft/power-apps-native-pdf-viewer version 0.2.9+ exists in package.json and node_modules. It deliberately refuses to run npm install or touch native configuration files: the extension must already be linked in the native build. It then generates or updates src/native/pdfViewer.ts.

The generated wrapper rejects http://, blob:, and content:// paths before reaching native code and returns a discriminated union without throwing errors. If the native binary lacks the compiled extension, calls fail cleanly with NATIVE_MODULE_MISSING.

What it helps with

  • create a safe TypeScript wrapper for the native PDF viewer component
  • verify package version 0.2.9+ to guarantee local file URI support
  • reject unsupported schemes such as blob and content before calling native code
  • capture user interactions like sharing, printing, or closing the viewer

Example prompts for the agent

  • /add-native pdf-viewer
  • /add-native pdf-control
  • /add-native @microsoft/power-apps-native-pdf-viewer

How to install add-pdf-viewer

1Plugin marketplace

/plugin marketplace add microsoft/power-platform-skills
/plugin install mobile-app@power-platform-skills

This installs the whole mobile-app plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/power-platform-skills --skill add-pdf-viewer -a claude-code

3Manually: put the files in place

~/.claude/skills/add-pdf-viewer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/add-pdf-viewer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about add-pdf-viewer

How to install add-pdf-viewer in Claude Code?

Run /plugin marketplace add microsoft/power-platform-skills, then execute /plugin install mobile-app@power-platform-skills.

What does add-pdf-viewer do?

It verifies mobile dependencies and writes src/native/pdfViewer.ts to open PDF files through @microsoft/power-apps-native-pdf-viewer.

Does this skill install npm dependencies automatically?

No, it stops if the package is missing. The native module must be installed and compiled into the app beforehand.

Source text

SKILL.md · MIT
---
name: add-pdf-viewer
description: Internal implementation skill invoked by /add-native for native PDF control workflows. Handles HTTPS and file URI PDF viewing with @microsoft/power-apps-native-pdf-viewer 0.2.9+.
user-invocable: false
disable-model-invocation: true
allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion
model: sonnet
---

**📋 Shared instructions: [shared-instructions.md](${PLUGIN_ROOT}/shared/shared-instructions.md)** — read first.

**Working directory:** before any project read or command, execute
[native-artifact-compatibility.md Step 0](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md#0-bind-every-operation-to-the-app-root).
Inherit `/add-native`'s resolved absolute `working_dir`; bind every shell call and
file tool to it, even when this helper starts from another directory.

# Add PDF Viewer

**Internal helper.** Users should invoke `/add-native pdf-viewer`, `/add-native pdf-control`, or `/add-native @microsoft/power-apps-native-pdf-viewer`; `/add-native` routes here after resolving the capability.

Generate or verify the native PDF viewer wrapper and show how to call its **native React Native API**. Version 0.2.9 and later support HTTPS PDF URLs and local `file://` URIs. Do not use the HostingSDK / PCF path from the package README; that is for a different use case.

## Steps

### 1. Verify app

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json && test -d src || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }
```

If this fails, tell the user to run `/create-mobile-app` first and STOP.

### 2. Verify package is already present

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node -e "const p=require('./package.json'); const m='@microsoft/power-apps-native-pdf-viewer'; if (!p.dependencies?.[m]) { console.error('MISSING: ' + m + ' is not in package.json. The template/app must already ship this native extension. This skill will not install it or edit native config.'); process.exit(1); } let v; try { v=require('./node_modules/' + m + '/package.json').version; } catch { console.error('MISSING_INSTALL: cannot verify the installed ' + m + ' version. Run the project package install first.'); process.exit(1); } const [major,minor,patch]=v.split('.').map(Number); if (!(major > 0 || minor > 2 || (minor === 2 && patch >= 9))) { console.error('UNSUPPORTED_VERSION: ' + m + ' ' + v + ' does not support file:// URIs. Version 0.2.9+ is required.'); process.exit(1); } console.log('OK: native PDF viewer ' + v + ' supports https:// and file://');"
```

If the check fails, STOP. Do not run `npm install`, `npx expo install`, `pod install`, or edit `app.config.js`. Version 0.2.9+ must already be part of the app's native build.

### 2a. Reconcile requested artifacts

Read and execute [native-artifact-compatibility.md](${PLUGIN_ROOT}/shared/references/native-artifact-compatibility.md)
Steps 1–3 for the PDF viewer row before any writes or reuse. Inherit the current
approval/mode from `/add-native`; do not repeat a valid scoped approval.
Inspect `src/native/pdfViewer.ts` for `openHttpsPdf`, `PdfViewerResult`, requested
options/actions, and the actual HTTPS/local-file behavior against installed
version 0.2.9+. An HTTPS-only implementation cannot satisfy a requested local
`file://` preview. Check invalid URI and missing-native-module paths, not just
exports; an incompatible artifact outside approval returns `NEEDS_CONTEXT` to
the owner, or asks standalone.

### 3. Write or verify `src/native/pdfViewer.ts`

Apply Step 2a's decision for `src/native/pdfViewer.ts`: create when requested and
missing, reuse unchanged only if compatible, or make only the approved scoped
update. Preserve custom code, exports, and callers; do not overwrite from the example.

The wrapper MUST:

- Accept `https://` URLs and `file://` URIs.
- Reject `content://`, `blob:`, `http://`, empty, and malformed URLs before calling native code.
- Return a discriminated union and never throw.
- Return `NATIVE_MODULE_MISSING` when the extension is installed in JS but unavailable in the native build.
- Surface viewer action results (`shared`, `printed`, `dismissed`) when available.
- Return `VIEWER_FAILED` for native errors not covered by validation/module checks.

```ts
// src/native/pdfViewer.ts
import { NativePdfViewer } from '@microsoft/power-apps-native-pdf-viewer';

export type PdfViewerResult =
  | { ok: true; action?: 'shared' | 'printed' | 'dismissed' }
  | { ok: false; reason: 'INVALID_URL' | 'NATIVE_MODULE_MISSING' | 'VIEWER_FAILED'; message?: string };

export async function openHttpsPdf(
  url: string,
  options?: { title?: string; maxFileSizeMb?: number; cacheEnabled?: boolean },
): Promise<PdfViewerResult> {
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    return { ok: false, reason: 'INVALID_URL', message: 'PDF location must be a valid https:// URL or file:// URI.' };
  }

  const isHttpsUrl = parsed.protocol === 'https:';
  const isFileUri = parsed.protocol === 'file:' && url.startsWith('file://') && parsed.pathname !== '/';
  if (!isHttpsUrl && !isFileUri) {
    return { ok: false, reason: 'INVALID_URL', message: 'Native PDF viewer supports https:// and file:// inputs only.' };
  }

  if (!NativePdfViewer?.openPdf) {
    return { ok: false, reason: 'NATIVE_MODULE_MISSING', message: 'Native PDF viewer module is not available in this build.' };
  }

  try {
    const response = await NativePdfViewer.openPdf(url, {
      maxFileSizeMb: 50,
      cacheEnabled: true,
      ...options,
    });

    if (response.status === 'ok') {
      return { ok: true, action: response.result?.action };
    }

    return { ok: false, reason: 'VIEWER_FAILED', message: response.message ?? response.error };
  } catch (error: any) {
    return { ok: false, reason: 'VIEWER_FAILED', message: error?.message ?? String(error) };
  }
}
```

### 4. Use the wrapper

Integration guidance for the owner; do not edit screens in this helper.

Screens import the wrapper, not the native package directly:

```ts
import { openHttpsPdf } from '@/native/pdfViewer';

const response = await openHttpsPdf('https://example.com/report.pdf', {
  title: "Inspection report",
});

if (response.ok) {
  switch (response.action) {
    case "shared":
      // User completed native Share.
      break;
    case "printed":
      // User completed native Print.
      break;
    case "dismissed":
      // User closed the viewer.
      break;
  }
} else {
  console.warn("Failed to open PDF:", response.reason, response.message);
}
```

Notes:
- URLs must use `https://` or a non-empty `file://` URI. `content://`, `blob:`, and `http://` are not supported by this skill.
- Use `@microsoft/power-apps-native-pdf-viewer` only for this native PDF viewing use case.
- Use `expo-document-picker` for picking/importing/uploading a local PDF or document.
- Use `/add-native pdf-report` for generated local PDFs. That helper requires `expo-print` and adds sharing behavior only when `expo-sharing` is already present.
- Generated local PDFs from `expo-print` may be opened by native PDF viewer 0.2.9+ as `file://` URIs.
- Share and Print are built into the native viewer; there are no separate JS share/print calls.
- The wrapper returns `{ ok: true } | { ok: false }`; handle every non-ok reason in UI.

### 5. Type-check

```bash
cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit
```

Fix only in-scope helper errors, then execute the shared compatibility contract's
Step 4. Recheck requested inputs/options/actions, invalid URI rejection, missing
native module, and viewer failures. Type-check success alone is insufficient;
do not fix screen/generated files.

### 6. Native rebuild note

This skill does not install native code. If the package was just added outside the skill, the app needs a native rebuild outside this workflow. If the package was already in the build, Metro hot reload is enough for wrapper edits.

### 7. Do not use HostingSDK / PCF

Do not import or register:

```ts
import NativePdfViewerExtension from "@microsoft/power-apps-native-pdf-viewer";
```

Do not wire Companion PCF or `NativePdfViewerExtension`. In Power Apps native code apps, use the native React Native API above.

### 8. Summary

Return the shared compatibility result and actual created/updated/reused paths
before this summary. Update memory-bank only after success, and leave final
updates to the owner when orchestrated.

Tell the user:

```text
PDF viewer added
Package present   : @microsoft/power-apps-native-pdf-viewer
Wrapper           : src/native/pdfViewer.ts
URL support       : HTTPS and file:// (0.2.9+)
Type-check        : PASS
Native rebuild    : not performed by this skill
Usage             : openHttpsPdf(...)
HostingSDK / PCF  : not used
```

Update `memory-bank.md` under `Controls`:

```text
- PDF viewer added — @microsoft/power-apps-native-pdf-viewer (<ISO date>)
```

© Microsoft · MIT · microsoft/power-platform-skills

Similar skills

All skills for Mobile →

From the same set157

The whole set →
add-sharepoint add-sharepoint connects SharePoint Online to Power Apps code apps: reads lists, manages documents, creates new lists via Graph API. CX Codex +1 ★ 1,167repo stars preview-offline-scope preview-offline-scope estimates download payload and sync frequency costs for a Power Platform offline profile before rollout. Runs strictly in read-only mode. CX Codex +1 ★ 1,167repo stars canvas-screen-builder canvas-screen-builder is a Claude Code subagent that adds or edits one screen in an existing Canvas App from a shared contract and scoped brief. It runs local QA without compiling. CX Codex ★ 1,167repo stars code-app-architect code-app-architect is a Claude Code subagent that guides Power Apps code project architecture with React and Vite, Dataverse integration, connector selection, and build troubleshooting. CX Codex ★ 1,167repo stars add-pen-input The add-pen-input skill creates or checks a wrapper for handwriting and signature capture in a mobile app. /add-native routes pen, ink, drawing, and handwriting requests to it. CX Codex +1 ★ 1,167repo stars canvas-app-planner canvas-app-planner is a Microsoft subagent for Claude Code that turns approved Canvas App edits into implementation contracts for each screen while preserving existing logic and layout. CX Codex ★ 1,167repo stars assemble-ppmplugin assemble-ppmplugin is a Claude Code skill that assembles a .ppmplugin bundle from a manifest and Android/iOS binaries, validates them, and packages the result. It runs after /generate-ppmplugin-manifest and build skills. CX Codex +1 ★ 1,167repo stars add-geolocation The add-geolocation skill sets up background GPS tracking with durable storage and Dataverse sync in a mobile app. The /add-native geolocation command invokes it. CX Codex +1 ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open