nvlang/sveltex

Getting Started

Note: See the docs for more information.
Note: This package is ESM-only.

Creating a new project

You can use the create-sveltex package to create a new project using SvelTeX:

pnpm dlx create-sveltex # If using PNPM
bunx     create-sveltex # If using Bun
npx      create-sveltex # If using NPM
yarn dlx create-sveltex # If using Yarn

...and follow the prompts.

Adding to existing project

Installation

pnpm add -D @nvl/sveltex # If using PNPM
bun  add -D @nvl/sveltex # If using Bun
npm  add -D @nvl/sveltex # If using NPM
yarn add -D @nvl/sveltex # If using Yarn

Basic steup

// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
import { sveltex } from '@nvl/sveltex';

/** @type {import('@sveltejs/kit').Config} */
const config = {
    // ...
    preprocess: [
        vitePreprocess(), // (optional)
        await sveltex({
            markdownBackend: 'unified',
            codeBackend: 'shiki',
            mathBackend: 'mathjax',
        }, {
            // Options
        }),
        // ...
    ],
    extensions: ['.svelte', '.sveltex'],
    // ...
};

export default config;

Now, install the backends (cf. IntelliSense or the error message you'd get if you tried to run the above code without installing the backends), and you should be good to go. Create a +page.sveltex file in your src/routes directory, and start adding markdown, math, code blocks, and even TeX components.

Editor integration

For VS Code, you can install the official SvelTeX extension from the marketplace. This will provide syntax highlighting for .sveltex files.

For other editors, you'd need to configure syntax highlighting yourself using the SvelTeX TextMate grammar provided within the VS Code extension.

Proper LSP-style language support is not currently implemented. Doing so via e.g. request forwarding could be an immense enrichment to the developer experience, but it's not something I can currently commit to. Contributions for this would be extremely welcome.

Acknowledgments

See acknowledgments on the project site.

Note: The TSDoc comments for many of this project's interfaces, particularly those describing options to be passed to external libraries, may be copies, paraphrasings, or adaptations of the official documentations of the respective libraries. Some notable examples are MathJax and TikZ.

Addendum: Some lessons learned

Tips

Always run your linter before you run your tests. In particular, note that VSCode's ESLint extension only runs on files that are currently open, so even if the problems pane is clear, you might still have linting errors in files that are not currently open.
Generally speaking, don't combine .ts and .d.ts files. In short, it's either .ts or it's .js + (optionally) .d.ts. This is almost certainly an egregious oversimplification, but it's the feeling I got after spending a bunch of time trying to debug issues caused by me mixing .ts and .d.ts files.
In YAML files for GitHub actions, 'text', "text", and text may not be the same. In particular, I had workflow_run events not triggering because the needed workflow's name wasn't in quotes, but the workflow_run element was.

Cool software I didn't know before

fast-check, for fuzzy testing.
plop, for code generation with templates and CLI prompts.
Shiki, for code highlighting.
twoslash, for IntelliSense in markdown code blocks.
VitePress, a great SSG for docs.
node-poppler, a Node.js wrapper for Poppler, which can used to convert PDFs to SVGs.
Knip, a tool for detecting unused files, dependencies, and exports.

nvlang / sveltex