xslt-tools/README.md

XSLT tools

Browser-only MVP for testing local XML/XSLT transformations. Nothing is uploaded; the app uses browser APIs, LocalStorage, and local file open/save dialogs where available.

Features in this MVP

• Three-column workbench:
  • XML input
  • XSL transformation code
  • XML output
• CodeMirror editors with:
  • line numbers
  • XML syntax highlighting
  • editor undo/redo
  • cut/copy/paste helpers
  • find support via CodeMirror shortcuts
• Transformation engines:
  • SaxonJS 2.7 as the default engine for XSLT 1.0/2.0/3.0-style workflows
  • Browser-native XSLTProcessor as a lightweight XSLT 1.0 fallback
• XML and XSLT well-formedness checks
• Basic XSLT root/version checks
• Snippet toolbox for common XSLT constructs
• Open/save local files
  • File System Access API when supported
  • file input/download fallback otherwise
• Output → Input action for chained transformations
• Confirmation dialog before destructive overwrites
• LocalStorage persistence
• Approximate “explain transformation” table after a run

SaxonJS note

SaxonJS is bundled through the saxon-js npm package and loaded lazily when the SaxonJS engine runs. The browser build may show Vite warnings about Node modules such as fs, path, or stream being externalized. Those warnings come from the package containing Node.js support as well; the app does not use file-based SaxonJS APIs in the browser.

SaxonJS itself is free to use but not open source. Check node_modules/saxon-js/LICENSE.txt after installation before distributing a packaged version.

Run locally

npm install
npm run dev

Then open the local Vite URL shown in your terminal.

Build

npm run build
npm run preview

Suggested next steps

1. Add parameter handling for xsl:param.
2. Add a real diagnostics/lint bridge into CodeMirror gutter markers.
3. Add transformation test cases with expected output assertions.
4. Add project import/export as a single .xslt-tools.json file.
5. Improve explain mode through stylesheet instrumentation.
6. Add optional precompiled SEF import/export support for larger SaxonJS projects.

Structure

src/
├── components/     # Layout, toolbar, editor panels, dialogs
├── editor/         # CodeMirror integration and XSLT snippets
├── file/           # Local file open/save helpers
├── transform/      # Transform engine abstraction, SaxonJS, native engine
├── validation/     # XML/XSLT validation helpers
└── workspace/      # LocalStorage-backed workbench state

Development checks

Use Node.js 22 or newer. The main local quality gate is:

npm run check

Useful individual commands:

npm run typecheck      # TypeScript only
npm run lint           # ESLint
npm run lint:fix       # ESLint autofix where possible
npm run format:check   # Prettier check
npm run format         # Prettier write
npm run test           # Vitest/jsdom test suite
npm run build          # Production build
npm run clean          # Remove generated build/cache files

The vendored SaxonJS browser file is intentionally excluded from ESLint and Prettier because it is a third-party distribution artifact.

Transformation engines

The app currently exposes two engines:

• SaxonJS 2 dynamic XSLT 3.0: default engine. It lazy-loads public/vendor/saxon/SaxonJS2.js, compiles raw XSLT text to SEF in the browser, then executes the generated SEF locally.
• Native browser XSLTProcessor: XSLT 1.0 fallback using the browser implementation.

The SaxonJS runtime is loaded only when a Saxon transformation is requested, so the initial app shell does not block on the large compiler/runtime file.