DEV Community: Yu Wang

The DOCX demo was perfect. The first real contract was awful.

Yu Wang — Wed, 22 Jul 2026 07:46:10 +0000

The first DOCX demo looked great.

One page. One font. A small table. No headers. No section breaks. I thought the hard part was done.

Then a customer sent a real contract.

It had missing fonts, nested tables, merged cells, numbered clauses, headers, footers, page breaks, and a signature block that had to stay in the right place. Our clean demo became useless in seconds.

That failure changed how I think about Office preview.

A file that opens is not a file that renders correctly

Parsing the ZIP package is the easy part of DOCX. The ugly work starts after that.

You need to answer questions such as:

Which font metrics should be used when the original font is missing?
Does a section break create a new page or only change layout rules?
What happens when a table is wider than the page?
How do floating images interact with text?
Where does a paragraph split when line height and font fallback both change?

A browser can display the text and still get the document badly wrong.

The same trap exists in every Office format.

Old DOC and XLS files use binary structures that are nothing like DOCX and XLSX. PPT and PPTX need different readers. A huge spreadsheet may parse correctly and still freeze the tab when the renderer creates too many cells.

So I stopped treating “Office preview” as one feature.

We split the problem into real pipelines

The commercial build has dedicated paths for DOC, DOCX, PPT, PPTX, XLS, and XLSX. The rough flow is:

file bytes
  -> format probe
  -> format-specific input guard
  -> dedicated parser
  -> normalized document model
  -> layout and browser renderer

The protected distribution keeps parser entry points behind a small WASM license gate. Workers and WASM assets are served from the same origin. That matters for private networks, strict CSP rules, and deployments with no public internet access.

The gate is deliberately boring:

signed license -> WASM verification -> viewer token -> parser entry

It does not make rendering better. It gives a business deployment a clear delivery boundary without pushing document bytes to our server.

The open-source and commercial paths should not pretend to be the same

I maintain an open-source File Viewer for broad browser-side preview. It covers many formats and is the right answer for a lot of products.

But broad support and high Office fidelity are different jobs.

The open-source path is great when the product needs fast preview across many file types and can accept layout differences. The commercial Office path exists for teams that need private deployment, source delivery, legacy Office support, and someone responsible when a release breaks.

Hiding that difference would be dishonest.

Our test files got uglier on purpose

Pretty samples produce pretty lies.

The useful test set contains files that are unpleasant:

a contract with several section changes;
a DOC file saved by an old Office version;
a spreadsheet with merged regions, charts, frozen panes, and a large used range;
a deck with custom fonts and shapes positioned outside the normal slide box;
files with missing fonts;
files that are valid but unusually large.

We compare structure, page flow, cell position, and failure behavior. A renderer must also fail clearly. A blank page or a tab that spins forever is worse than an honest error.

Browser-side preview still has limits

This is not Microsoft Office rebuilt in JavaScript.

Font substitution can move text. Rare drawing objects can look wrong. Very large files can consume enough memory to freeze the tab. Some products should still use server-side conversion for the hardest documents.

The useful question is not “Can the browser render Office files?”

It can.

The real question is where your product draws the line between instant local preview, high-fidelity browser rendering, and server conversion.

I built Flyfish Office Preview for the middle path: higher Office fidelity, private deployment, and no forced upload to our server.

You can test the current demo here:

https://demo.flyfish.group/

What breaks first in your product: pagination, legacy formats, missing fonts, or spreadsheet memory?

Self-Hosting a Browser File Viewer Under a Strict CSP: Workers, WASM, and Assets Without Public CDNs

Yu Wang — Tue, 14 Jul 2026 01:44:30 +0000

File Viewer began with a consumer-facing application whose backend resources were limited. In 2022, my manager asked me to move document preview entirely into the frontend. That constraint eventually grew into an Apache-2.0 viewer ecosystem, and Worker/WASM delivery became one of its hardest practical deployment problems.

The hardest part has been making many format engines behave consistently while keeping large customer files usable. I spent a lot of time on Worker loading, asset paths, and performance so heavy parsers remain practical in real deployments.

File Viewer previewing an English DOCX sample in the browser. Renderer chunks, Workers, WASM modules, and fonts can all be served from infrastructure you control.

A browser-side file viewer is often selected for privacy: a document can be parsed and rendered without first being uploaded to a third-party conversion service.

That is only half of the deployment story.

A modern viewer may still load renderer chunks, Web Workers, WASM modules, fonts, and vendor assets at runtime. If those resources come from a public CDN, the deployment is not truly self-contained. If their URLs are not planned in advance, a strict Content Security Policy can also turn a successful local integration into a production failure.

This article describes the model I use for self-hosting File Viewer, an Apache-2.0 browser-native viewer for internal and private web applications. The same principles apply to many JavaScript applications that combine lazy imports, Workers, WASM, and private file URLs.

The examples use v2.2.2. Exact asset filenames can change between releases, so pin a version and use the asset manifest produced by that release instead of copying filenames from an old deployment.

Start with the runtime graph, not the component tag

The visible component is only the first node in the runtime graph.

A complete deployment may include:

The host application and framework wrapper.
A core viewer package.
Renderer bundles loaded only when a matching file is opened.
Worker scripts for pipelines such as PDF, DOCX, PPTX, spreadsheets, or archives.
WASM modules used by archive, CAD, and Typst-related paths.
Fonts and other vendor assets.
The source file being previewed.

This distinction matters because loading the initial JavaScript successfully does not prove that the deployment works. A PDF may open while a DOCX Worker is blocked. A ZIP file may fall back to a limited compatibility path because its Worker found the wrong WASM URL. A Typst document may fail only after the compiler module or font assets are requested.

File Viewer currently maps 206 extensions to 24 preview pipelines. That is a routing and capability matrix, not a claim that all 206 extensions use the same renderer or provide identical fidelity.

For deployment testing, think in pipelines rather than extensions.

Prefer one controlled origin

The simplest strict-CSP arrangement is:

https://app.example.internal/
  app JavaScript and CSS
  /static/file-viewer/v2.2.2/
  /api/files/...

With the application, viewer assets, and file endpoint on the same origin, most runtime requests can remain under 'self'.

A separate private static origin also works:

https://app.example.internal/
https://assets.example.internal/file-viewer/v2.2.2/
https://files.example.internal/...

However, this requires three configurations to agree:

The viewer must generate the correct asset URLs.
CSP must allow the asset and file origins under the appropriate directives.
The static and file servers must return suitable CORS and content-type headers.

Same-origin hosting removes an entire class of deployment errors, so I use it unless a private CDN is operationally necessary.

Pin and copy the whole asset layout

There are several ways to integrate the viewer, and their asset behavior differs slightly.

The @file-viewer/web-full IIFE loads the Custom Element and controller first, then resolves heavy renderer bundles and runtime assets relative to the script URL. For this mode, mirror the complete dist directory and preserve its structure. Copying only the entry JavaScript is not enough.

For Vue full packages, the copied assets normally use /file-viewer/ as their default base. A versioned private path can be set explicitly:

import { setDefaultFullAssetBaseUrl } from '@file-viewer/vue3-full'

setDefaultFullAssetBaseUrl('/static/file-viewer/v2.2.2/')

The asset-copy output includes a generated flyfish-viewer-assets.json. Keep the copied directory intact and treat the manifest as the release’s source of truth.

If the application uses composed packages, a Vite project can use @file-viewer/vite-plugin to discover installed presets and copy runtime assets. Other build systems can publish the same assets through their own copy step.

The important principle is the same in every case: do not let a bundler rename one Worker, flatten a WASM directory, and leave the application guessing where the files moved.

Use explicit URLs when the gateway changes paths

A base URL is convenient, but explicit options should remain available for reverse proxies, tenant prefixes, or unusual static gateways.

For example:

const viewerOptions = {
  archive: {
    workerUrl:
      '/static/file-viewer/v2.2.2/vendor/libarchive/worker-bundle.js',
    wasmUrl:
      '/static/file-viewer/v2.2.2/vendor/libarchive/libarchive.wasm'
  },

  docx: {
    worker: true,
    workerUrl:
      '/static/file-viewer/v2.2.2/vendor/docx/docx.worker.js',
    workerJsZipUrl:
      '/static/file-viewer/v2.2.2/vendor/docx/jszip.min.js'
  },

  spreadsheet: {
    worker: false
  }
}

Those archive and DOCX locations reflect the documented copied layout. For PDF, Typst, CAD, and other pipelines, take the precise versioned filenames from the copied assets or generated manifest rather than inventing a path.

The spreadsheet Worker is optional and disabled by default. Main-thread parsing avoids Worker startup problems in local servers, restrictive WebViews, and CSP-sensitive environments. That is a useful reminder: a Worker is an architectural choice, not automatically a requirement for every parser.

Build CSP from observed resource types

Start with Content-Security-Policy-Report-Only, exercise the required pipelines, and inspect every violation before enforcing the policy.

A same-origin starting point may look like this:

Content-Security-Policy-Report-Only:
  default-src 'none';
  base-uri 'none';
  object-src 'none';
  frame-ancestors 'self';
  script-src 'self' 'wasm-unsafe-eval';
  worker-src 'self';
  connect-src 'self';
  img-src 'self' data: blob:;
  style-src 'self' 'unsafe-inline';
  font-src 'self' data:;
  media-src 'self' blob:;
  frame-src 'self';

This is a starting template, not a universal policy.

Several directives deserve special attention:

worker-src 'self' permits statically hosted same-origin Workers. Avoid adding blob: automatically. Add it only if an enabled and reviewed code path actually creates blob Workers.
script-src 'wasm-unsafe-eval' permits WebAssembly compilation without granting general JavaScript string evaluation in browsers that support this CSP source expression. Test the exact browser fleet before deciding whether a broader exception is acceptable.
connect-src must include every origin used to fetch documents, renderer data, WASM, or signed file URLs.
img-src, font-src, and media-src depend on the document types you enable. Local uploads and generated previews can require blob: or data:.
style-src 'unsafe-inline' may be needed by document layout surfaces that produce runtime styles. If the host already uses a stricter nonce- or hash-based design, validate each renderer instead of weakening the policy globally.
frame-src is only necessary when using the iframe distribution or another framed preview surface.

For a private asset origin, replace the relevant 'self' entries with the exact origin. Avoid wildcards such as https: because they erase much of the value of CSP.

WASM failures are not always WASM failures

When a WASM pipeline fails, first inspect the network response.

A common failure sequence is:

The application requests libarchive.wasm.
The path is missing.
An SPA fallback returns index.html with status 200.
The browser reports a WASM compilation or MIME error.

The underlying problem is routing, not the binary.

Static asset routes should fail with a real 404 instead of falling through to the application shell. Also verify these response types:

.js / .mjs    JavaScript MIME type
.wasm         application/wasm
fonts         matching font MIME type

Use X-Content-Type-Options: nosniff after the MIME mapping is correct, not before it has been tested.

The archive Worker and libarchive.wasm should remain adjacent when using the default layout, unless both URLs are explicitly configured. The DOCX Worker also needs access to its JSZip dependency. A successful Worker request alone does not prove that its secondary imports succeeded.

Cache releases, not mutable filenames

A versioned directory makes CSP deployment and rollback much easier:

/static/file-viewer/v2.2.2/...
/static/file-viewer/v2.2.2/...

Immutable versioned JavaScript, Workers, WASM, and fonts can receive long cache lifetimes. HTML entry points and any manifest used to select the current release should have shorter caching.

This avoids a dangerous mixed-release state where the application loads a new renderer with an old Worker or WASM module from the browser cache.

It also allows a rollback to change one application reference instead of overwriting assets in place.

Treat iframe mode as a separate security boundary

The release provides a zero-dependency iframe entry for hosts that do not want an npm integration.

If the iframe and parent are on different controlled origins, remember that they are separate documents with separate CSP policies. Restrict frame-ancestors on the viewer origin, restrict frame-src on the parent, and use an exact target origin for postMessage.

Do not use '*' as the target origin for document blobs.

If the parent fetches the private file and sends a Blob into the iframe, the file authorization remains in the parent application. The iframe origin still needs permission to load its own Workers, WASM, fonts, and renderer chunks.

Test one file from every expensive pipeline

My minimum private-deployment matrix is not 206 sample files. It is a smaller set selected to activate different runtime paths:

PDF for PDF.js Worker and Range behavior.
DOCX for the document Worker and JSZip asset.
PPTX for progressive slide processing.
ZIP or 7z for the archive Worker and WASM pair.
DWG for the CAD Worker and LibreDWG WASM path.
Typst for compiler WASM, renderer WASM, and fonts.
A local image or media file for blob URLs.
The iframe entry, if the application uses it.

Then I verify:

No request reaches an unapproved public origin.
Every Worker runs under the enforced CSP.
WASM responses have the correct MIME type.
Missing assets return 404 rather than HTML.
Version rollback does not mix cached releases.
The same tests work in required mobile or embedded WebViews.
CSP reports are empty after expected user actions, not merely after page load.

The boundary of “browser-native”

Browser-native does not mean “no network requests.” The browser still needs to fetch the source file and the assets required for its pipeline. The privacy property comes from controlling those endpoints and avoiding a mandatory document-conversion service.

It also does not mean every extension has identical fidelity. Some pipelines render rich visual content, some progressively parse legacy files, and some provide safe structural inspection. Heavy CAD/BIM formats may still be better served by a deliberate conversion workflow. PlantUML rendering uses a configurable endpoint, which must be self-hosted or excluded if the environment cannot make that request.

The project is a viewer, not a document editor. Download preserves the original bytes; it does not write the rendered result back into the source document. Print and HTML export are exposed only where the corresponding renderer can provide a meaningful result.

Those boundaries are part of a secure design because they prevent a broad support matrix from being mistaken for a universal document engine.

Final thought

A strict CSP should not be the final obstacle added after integration. It should shape the asset model from the beginning.

Once Workers, WASM, fonts, renderer chunks, and source files have stable versioned locations, the policy becomes understandable. More importantly, the private-deployment promise becomes verifiable: open the network panel, exercise each pipeline, and confirm exactly where every byte came from.

GitHub: https://github.com/flyfish-dev/file-viewer

Distribution guide: https://doc.file-viewer.app/en/guide/distribution

English demo: https://demo.file-viewer.app/?lang=en-US

Designing a Browser-Native File Preview Layer for Internal Web Apps

Yu Wang — Mon, 13 Jul 2026 07:13:28 +0000

File Viewer began with a practical constraint at work. My manager asked me to build document preview entirely in the frontend because the backend had limited resources and the product served consumers at scale. I published the first article about the approach in 2022; I did not expect so many developers to adopt it or tell me it had solved a real problem for them.

The hardest part since then has been making many format engines behave consistently while keeping large customer files usable. I spent a lot of time on Worker loading, runtime asset delivery, and performance so that heavy parsers remain practical outside a demo.

The current English demo routes 206 extensions through 24 lazy browser-side preview pipelines.

Adding file preview to a web application often looks simple at first. Display images with an <img> element, embed PDFs, and download everything else.

That approach usually stops working when an internal application accumulates real business attachments: DOCX reports, XLSX workbooks, PPTX decks, legacy Office files, CAD drawings, archives, email messages, diagrams, source code, and structured data. Teams then end up operating a conversion backend, sending files to an external service, or maintaining a collection of unrelated viewers.

File Viewer is an Apache-2.0 project that treats this problem as frontend infrastructure. It provides a common browser-side loading, rendering, interaction, and deployment layer while keeping format-specific engines modular.

This article explains the architectural choices behind it, including the tradeoffs and the places where browser-native preview is not the right answer.

Start With Deployment Constraints

The project was designed around internal tools, intranet systems, approval workflows, attachment centers, engineering archives, and private deployments.

These environments frequently have constraints that are easy to overlook:

Documents may not be uploaded to a third-party converter.
The application may run without public internet access.
Worker, WASM, font, and vendor assets must come from an approved internal origin.
A strict Content Security Policy may block dynamically created Workers or remote resources.
The host application may use Vue, React, Svelte, jQuery, or no framework at all.
A global design system may contain aggressive CSS resets.
Most users open common files, but a small number need much heavier CAD or archive engines.

Those constraints make a single monolithic viewer bundle unattractive. They also make “just run a document conversion server” an incomplete answer.

Separate Orchestration From Rendering

The project is divided into several layers.

@file-viewer/core owns the behavior shared by every format:

source loading and format detection;
renderer registration and selection;
lifecycle and controller APIs;
search and highlight state;
zoom and navigation state;
print and HTML export coordination;
download and operation guards;
theme, watermark, and toolbar configuration.

Format-specific behavior lives in @file-viewer/renderer-* packages. PDF, Word, spreadsheets, presentations, CAD, archives, email, drawings, geospatial data, and other families can therefore evolve independently.

This boundary is important. The core should not need to understand how a DWG file is decoded or how a ZIP entry is extracted. It only needs a renderer contract that describes whether the active document supports operations such as search, print, zoom, or export.

That also prevents the common toolbar from advertising operations a renderer cannot perform reliably. For example, a PDF renderer can provide full-page printing, while an archive browser may expose nested preview and extraction but intentionally hide print.

Assemble Capabilities With Presets

Most applications do not need every supported format. File Viewer groups common renderer sets into presets:

@file-viewer/preset-lite covers text, Markdown, code, images, audio, and video.
@file-viewer/preset-office covers PDF, Word, Excel, PowerPoint, OFD, RTF, and OpenDocument workflows.
@file-viewer/preset-engineering covers CAD, 3D, geospatial data, diagrams, archives, and engineering formats.
@file-viewer/preset-all provides the capability set used by the complete demo.

An application can also install one renderer directly when it only needs an exact format boundary.

The *-full framework packages favor fast setup by combining a component package with the full preset. They are useful for evaluation, attachment workbenches, and applications where broad coverage matters more than the smallest possible dependency graph.

Production applications with a narrower format set should usually start with a native component package and add only the required preset or renderers.

Lazy Loading Is More Important Than the Extension Count

At the time of writing, the registry declares 206 extension mappings across 24 preview pipelines. That does not mean all 206 implementations are downloaded when the page starts.

Heavy Office, PDF, CAD, archive, Typst, drawing, PSD, Worker, and WASM paths load when their file types are selected. A user opening Markdown should not first download a CAD decoder.

The CDN full entry follows the same idea. Its initial script installs the Custom Element, controller, and lazy capability registry. Renderer bundles are fetched from the distribution directory when needed. Worker, WASM, font, and vendor assets can be served from the same origin or copied to a private asset path.

For Vite applications, an optional plugin can discover installed presets and copy their runtime assets. Other build systems can pass presets explicitly and copy assets as part of their normal deployment process.

This architecture does not make heavy document engines small. It limits when they are transferred and lets the application exclude engines it never uses. Bundle-size claims should therefore be based on the selected preset and measured production build, not on one universal number.

Keep Framework Integrations Thin

The same core is exposed through packages for Web Components, Vanilla JavaScript, Vue 3, Vue 2.7/2.6, React, legacy React, Svelte, and jQuery.

Framework packages translate native concepts—props, events, refs, hooks, actions, or plugins—into the same viewer options and controller semantics. They do not maintain separate rendering implementations.

A basic React integration using the full package looks like this:

import FileViewer from '@file-viewer/react-full'

export function Preview() {
  return (
    <FileViewer
      url="/files/report.pdf"
      style={{ height: 720 }}
    />
  )
}

A no-build page can use the Web Component entry:

<script src="https://cdn.jsdelivr.net/npm/@file-viewer/web-full@latest/dist/flyfish-file-viewer-web-full.iife.js"></script>

<flyfish-file-viewer
  src="/files/report.docx"
  theme="light"
  style="display:block;height:720px">
</flyfish-file-viewer>

The Web Component and IIFE paths use Shadow DOM isolation by default. Framework integrations retain light-DOM compatibility but can opt into stronger isolation. CSS variables and stable Shadow Parts provide safer customization than depending on internal class names.

Be Precise About Privacy

“Browser-side” should not be translated into “the application never makes a network request.”

File Viewer does not require a server-side document conversion service. A local file can be parsed and rendered in the browser, and runtime assets can be self-hosted. This means a private document does not need to be sent to a third-party SaaS converter.

The final privacy boundary still depends on deployment:

A remote document URL must be fetched from somewhere.
Worker, WASM, fonts, and vendor scripts use the origins configured by the application.
Optional integrations, such as a configured PlantUML rendering endpoint, can introduce another request.
Application telemetry remains the host application’s responsibility.

For an offline or intranet deployment, teams should self-host the complete runtime asset set, audit configured endpoints, and test under the production CSP.

Extension Support Is Not a Fidelity Guarantee

A long extension list can become misleading if every recognized file is described as fully rendered.

The project documents several capability levels. Mature pipelines provide visual preview and useful document operations. Some specialized engineering formats currently provide safe structure inspection, metadata, or conversion guidance. Extremely complex formats may require a dedicated C++, Rust, or WASM engine before high-fidelity rendering is realistic.

Office preview also has a different goal from running Microsoft Office itself. Complex pagination, fonts, SmartArt, embedded objects, macros, and vendor-specific layout behavior can produce differences. The correct evaluation method is to test representative, sanitized production files and review the published fidelity notes.

The component is also read-only. Download preserves the original bytes; it does not write rendered changes back into the source document. Applications needing collaborative editing, tracked changes, or Office-compatible authoring should evaluate a document editing suite instead.

Self-Hosting and Evaluation

The project provides npm packages, static release artifacts, and a Docker image. A local demo can be started with:

docker run --rm -p 8080:80 flyfishdev/file-viewer:latest

For evaluation, start with the live samples, then test sanitized files that resemble production data. Verify rendering, search, print, asset loading, mobile behavior, and CSP rules before selecting a preset.

Browser-native preview is a good fit when an application needs read-only access to mixed attachments, private deployment, frontend integration, and a consistent interaction layer. It is a weaker fit when exact Office editing, server-generated canonical output, or professional CAD authoring is the main requirement.

The useful question is not whether one viewer can replace every native application. It is whether a modular browser preview layer can remove enough downloads, conversion jobs, and one-off integrations to improve a real workflow.

Repository: https://github.com/flyfish-dev/file-viewer

English demo: https://demo.file-viewer.app/?lang=en-US

Documentation: https://doc.file-viewer.app/en/

Format notes: https://doc.file-viewer.app/en/guide/format-fidelity