# @kitschpatrol/vite-plugin-tldraw [](https://npmjs.com/package/@kitschpatrol/vite-plugin-tldraw) [](https://opensource.org/license/mit/) [](https://github.com/kitschpatrol/vite-plugin-tldraw/actions/workflows/ci.yml) **Vite plugin enabling module-like import of local tldraw .tldr files with automatic conversion to SVG or PNG.** > [!NOTE] > > **This package has been superseded by [@kitschpatrol/unplugin-tldraw](https://github.com/kitschpatrol/unplugin-tldraw)**, which offers similar functionality across a much wider variety of build tools. > > The vite-plugin-tldraw package will receive periodic security updates, but the unplugin-tldraw package is recommended for any new users and will be the site of any future feature development. ## Overview **A [Vite](https://vitejs.dev) plugin to automate the import and conversion of local [tldraw](https://tldraw.dev) `.tldr` files into SVG or PNG image assets.** This allows `.tldr` files to be imported just like regular `.webp`, `.jpeg` etc. files in Vite-powered projects: ```ts // Main.ts import tldrImage from './test/assets/test-sketch.tldr' const body = document.querySelector('body') if (body) { body.innerHTML = `` } ``` The above transforms `./test/assets/test-sketch.tldr` into `./test/assets/test-sketch-{hash}.svg`, caches the output file, and then returns an SVG URL ready to be passed to an `img` element's `src` attribute. The plugin provides a global configuration object to customize of several aspects of the conversion process, and also allows overrides on a per-import basis via query parameters on the asset import path, e.g.: ```ts import tldrImage from './test/assets/test-sketch.tldr?format=png&tldr' ``` _For lower-level processing of `.tldr` files in Node projects or via the command line, please see [@kitschpatrol/tldraw-cli](https://github.com/kitschpatrol/tldraw-cli)._ ## Installation ### 1. Install the plugin package Assuming you're starting with a Vite project of some flavor: ```sh npm install --save-dev @kitschpatrol/vite-plugin-tldraw ``` ### 2. Add the plugin to your `vite.config` file ```ts // Vite.config.ts import tldraw from '@kitschpatrol/vite-plugin-tldraw' import { defineConfig } from 'vite' export default defineConfig({ plugins: [tldraw()], }) ``` ### 3. Configure TypeScript _Skip this step if you're using plain JavaScript._ Add the extension declarations to your [types](https://www.typescriptlang.org/tsconfig#types) in tsconfig.json: ```json { "compilerOptions": { "types": ["@kitschpatrol/vite-plugin-tldraw/client"] } } ``` Alternately, you can add a triple-slash package dependency directive to your global types file (e.g. `env.d.ts` or similar): ```ts /// ``` This step should take care of errors like: ```sh Cannot find module './test/assets/test-sketch.tldr' or its corresponding type declarations.ts(2307) ``` ## Usage Save your tldraw project to a `.tldr` file. Add it to your project, most likely in an `assets` folder. Then simply import the `.tldr` file to get a working asset URL: ```ts // Example.ts import tldrImage from './test/assets/test-sketch.tldr' // Logs a working SVG URL console.log(tldrImage) ``` See the sections below for additional conversion options. ## Plugin Options `vite-plugin-tldraw` inherits most of the configuration flags available in [@kitschpatrol/tldraw-cli](https://github.com/kitschpatrol/tldraw-cli#command-line-usage). ### `TldrawPluginOptions` | Key | Type | Description | Default | | --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `defaultImageOptions` | `TldrawImageOptions` | Default options object for all the image conversion process. See section below for more detail. | _See section below_ | | `cacheEnabled` | `boolean` | Caches generated image files. Hashes based on the source `.tldr` content _and_ any TldrawImageOptions or import query parameters ensure the cache regenerates as needed. Cached files are stored in Vite's `config.cacheDir` (usually `/node_modules/.vite`). | `true` | | `returnMetadata` | `boolean` | Returns an object with some extra details on the image instead of a plain path string. Occasionally useful for integration with other platforms. | `false` | | `verbose` | `boolean` | Log information about the conversion process to the console. | `false` | ### `TldrawImageOptions` | Key | Type | Description | Default | | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | `format` | `"png" \| "svg"` | Output image format. | `"svg"` | | `transparent` | `boolean` | Output image with a transparent background. | `false` | | `dark` | `boolean` | Output a dark theme version of the image. | `false` | | `stripStyle` | `boolean` | Remove `