PureTeX

A local-first LaTeX build, diagnostics, and PDF preview extension for VS Code.

VS Code Marketplace · Website · How to use · Engineering guide

PureTeX keeps LaTeX work inside your editor and on your machine. It detects the right root document, chooses an appropriate compiler/runtime, builds locally, maps errors back to source files, and renders a polished live PDF preview in VS Code.

PureTeX ships target-specific VSIX packages for Windows x64, Linux x64, macOS Intel, and macOS Apple Silicon.

Features

• Local LaTeX builds with automatic runtime selection.
• Docker, managed local toolchain, and system compiler support.
• Smart diagnostics for compiler, bibliography, glossary, runtime, and package-recovery issues.
• Live PDF preview with refresh, zoom, fit width, fit page, search, page jump, external open, and PDF download.
• SyncTeX-backed source-to-preview and preview-to-source navigation.
• Workspace indexing for labels, references, citations, glossary entries, acronyms, includes, and bibliography resources.
• Structured runtime and recovery logs in the PureTeX output channel.

Requirements

• VS Code 1.95.0 or newer.
• Supported packaged targets: Windows x64, Linux x64, macOS Intel, and macOS Apple Silicon.
• Node.js 22 for extension development.
• Rust stable for backend development.
• At least one LaTeX build path:
  • Docker, recommended for predictable builds.
  • Local tectonic.
  • Local or managed latexmk.

Docker and managed toolchains give PureTeX the best chance of recovering missing packages automatically. Plain system latexmk works, but package installation depends on the host TeX distribution and permissions.

Docker Runtime Image

PureTeX uses a public Docker Hub image for the optional full Docker runtime:

• puretex/puretex-runtime:amd64
• puretex/puretex-runtime:arm64

Users only need Docker installed and running. The extension pulls the image automatically when the full Docker preset is selected.

Runtime image details:

• Basic runtime image
• Full runtime image

Usage

1. Open a folder containing a .tex project.
2. Open a .tex file.
3. Press the PureTeX play button in the editor title bar, or run PureTeX: Open Live Preview from the Command Palette.
4. Build from the preview toolbar or save the document, depending on your build trigger setting.

PureTeX will resolve the project root, choose a runtime, build the document, and show the generated PDF in the preview panel.

Visit the hosted site at hn026.github.io/PureTeX for the demo and install links.

For a complete walkthrough of the preview controls and recommended settings, see How to use PureTeX.

Settings

PureTeX contributes these settings under the puretex namespace:

• puretex.compiler: choose auto, latexmk, or tectonic.
• puretex.buildRuntime: choose auto, docker, or local.
• puretex.dockerImagePreset: choose basic, full, or custom.
• puretex.dockerImage: custom Docker image used with the custom preset.
• puretex.advancedToolchainSource: choose auto, extension, or system.
• puretex.outputDirectory: build output directory, default .latex-build.
• puretex.buildTriggerMode: choose autosave, save, or manual.
• puretex.backendPath: optional backend binary override.
• puretex.texlabPath: optional TexLab binary override.

Development

Install extension dependencies:

cd extension
npm install

Build the extension bundle:

cd extension
npm run build

Run the extension test suite:

cd extension
npm test

Run the backend tests:

cd backend
cargo test

Run type checking:

cd extension
npm run typecheck

Fixture Tests

Compatibility fixture builds are opt-in because they run real LaTeX builds:

cd extension
npm run test:e2e:phase1

Performance fixture builds are intended for release candidates and scale-sensitive changes:

cd extension
npm run test:e2e:performance

Performance budget checks:

cd extension
npm run test:performance-budgets

cd ../backend
PURETEX_PERFORMANCE_BUDGETS=1 cargo test

Packaging

Build the extension, then package it with VSCE:

cd extension
npm run build
PURETEX_VSCODE_TARGET=linux-x64 npx @vscode/vsce package --target linux-x64

The extension build stages a bundled Rust backend under extension/bin/<target>/. Publish separate target-specific VSIX packages for each supported platform, for example:

cd backend
cargo build --release

cd ../extension
PURETEX_VSCODE_TARGET=linux-x64 npx @vscode/vsce package --target linux-x64
PURETEX_VSCODE_TARGET=win32-x64 npx @vscode/vsce package --target win32-x64

The package uses extension/package.json#files plus extension/.vscodeignore to keep development-only files out of the VSIX.

For release builds across multiple platforms, use the GitHub Actions workflow in .github/workflows/release-extension.yml. It builds native backend binaries and target-specific VSIX packages for:

• linux-x64
• darwin-x64
• darwin-arm64
• win32-x64

Run the workflow manually from the Actions tab, or push a version tag such as v0.1.0 to generate release-ready artifacts.

Contributing

Contributions are welcome. Keep changes focused, match the existing TypeScript and Rust style, and update tests or fixtures when behavior changes.

Before opening a pull request, run the checks that match your change:

cd extension
npm run typecheck
npm test
npm run build

cd ../backend
cargo test

For build-runtime, package-recovery, root-detection, or performance-sensitive changes, also run the relevant fixture tests from the sections above. Documentation, Marketplace metadata, and screenshots should be updated in the same change when user-facing behavior changes.

Engineering Docs

• How to use PureTeX: user-facing walkthrough of the preview, controls, defaults, and recommendations.
• Engineering guide: architecture, runtime selection, CI pipeline, design decisions, and release notes.
• Basic runtime image: package expectations for texlive/texlive:latest.
• Full runtime image: package list and build notes for puretex/puretex-runtime.

Project Layout

• extension/: VS Code extension source, preview UI, tests, and Marketplace metadata.
• backend/: Rust backend for root detection, log parsing, and SyncTeX operations.
• shared/protocol/: backend protocol schema.
• examples/: compatibility, navigation, root-detection, and performance fixtures.
• docker/: local Docker runtime image support.
• docs/: engineering notes and runtime image documentation.

License

PureTeX is licensed under the MIT License.