{"id":21046366,"url":"https://github.com/kitschpatrol/vite-plugin-tldraw","last_synced_at":"2025-10-11T04:22:04.917Z","repository":{"id":217830234,"uuid":"744881611","full_name":"kitschpatrol/vite-plugin-tldraw","owner":"kitschpatrol","description":"Vite plugin enabling module-like import of local tldraw .tldr files with automatic conversion to SVG or PNG.","archived":false,"fork":false,"pushed_at":"2025-09-29T00:18:22.000Z","size":1011,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-08T23:44:17.117Z","etag":null,"topics":["diagram","drawing","import","npm-package","sketch","tldr","tldraw","vite","vite-plugin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitschpatrol.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-18T07:40:41.000Z","updated_at":"2025-09-29T00:18:25.000Z","dependencies_parsed_at":"2024-01-21T01:33:21.710Z","dependency_job_id":"9c31c79e-9c04-414c-b1de-3bc5fd5a2791","html_url":"https://github.com/kitschpatrol/vite-plugin-tldraw","commit_stats":null,"previous_names":["kitschpatrol/vite-plugin-tldraw"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/kitschpatrol/vite-plugin-tldraw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Fvite-plugin-tldraw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Fvite-plugin-tldraw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Fvite-plugin-tldraw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Fvite-plugin-tldraw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitschpatrol","download_url":"https://codeload.github.com/kitschpatrol/vite-plugin-tldraw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Fvite-plugin-tldraw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006247,"owners_count":26084060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diagram","drawing","import","npm-package","sketch","tldr","tldraw","vite","vite-plugin"],"created_at":"2024-11-19T14:29:19.010Z","updated_at":"2025-10-11T04:22:04.868Z","avatar_url":"https://github.com/kitschpatrol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +--\u003e\n\n\u003c!-- title --\u003e\n\n# @kitschpatrol/vite-plugin-tldraw\n\n\u003c!-- /title --\u003e\n\n\u003c!-- badges --\u003e\n\n[![NPM Package @kitschpatrol/vite-plugin-tldraw](https://img.shields.io/npm/v/@kitschpatrol/vite-plugin-tldraw.svg)](https://npmjs.com/package/@kitschpatrol/vite-plugin-tldraw)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c!-- /badges --\u003e\n\n\u003c!-- description --\u003e\n\n**Vite plugin enabling module-like import of local tldraw .tldr files with automatic conversion to SVG or PNG.**\n\n\u003c!-- /description --\u003e\n\n## Overview\n\n**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.**\n\nThis allows `.tldr` files to be imported just like regular `.webp`, `.jpeg` etc. files in Vite-powered projects:\n\n```ts\n// Main.ts\nimport tldrImage from './test/assets/test-sketch.tldr'\n\nconst body = document.querySelector\u003cHTMLDivElement\u003e('body')\nif (body) body.innerHTML = `\u003cimg src=\"${tldrImage}\" /\u003e`\n```\n\nThe 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.\n\nThe 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.:\n\n```ts\nimport tldrImage from './test/assets/test-sketch.tldr?format=png\u0026tldr'\n```\n\n_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)._\n\n## Installation\n\n### 1. Install the plugin package\n\nAssuming you're starting with a Vite project of some flavor:\n\n```sh\nnpm install --save-dev @kitschpatrol/vite-plugin-tldraw\n```\n\n### 2. Add the plugin to your `vite.config` file\n\n```ts\n// Vite.config.ts\nimport tldraw from '@kitschpatrol/vite-plugin-tldraw'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [tldraw()],\n})\n```\n\n### 3. Configure TypeScript\n\n_Skip this step if you're using plain JavaScript._\n\nAdd the extension declarations to your [types](https://www.typescriptlang.org/tsconfig#types) in tsconfig.json:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"@kitschpatrol/vite-plugin-tldraw/ext\"]\n  }\n}\n```\n\nAlternately, you can add a triple-slash package dependency directive to your global types file (e.g. `env.d.ts` or similar):\n\n```ts\n/// \u003creference types=\"@kitschpatrol/vite-plugin-tldraw/ext\" /\u003e\n```\n\nThis step should take care of errors like:\n\n```sh\nCannot find module './test/assets/test-sketch.tldr' or its corresponding type declarations.ts(2307)\n```\n\n## Usage\n\nSave your tldraw project to a `.tldr` file.\n\nAdd it to your project, most likely in an `assets` folder.\n\nThen simply import the `.tldr` file to get a working asset URL:\n\n```ts\n// Example.ts\nimport tldrImage from './test/assets/test-sketch.tldr'\n\n// Logs a working SVG URL\nconsole.log(tldrImage)\n```\n\nSee the sections below for additional conversion options.\n\n## Plugin Options\n\n`vite-plugin-tldraw` inherits most of the configuration flags available in [@kitschpatrol/tldraw-cli](https://github.com/kitschpatrol/tldraw-cli#command-line-usage).\n\n### `TldrawPluginOptions`\n\n| Key                   | Type                 | Description                                                                                                                                                                                                                                                   | Default             |\n| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |\n| `defaultImageOptions` | `TldrawImageOptions` | Default options object for all the image conversion process. See section below for more detail.                                                                                                                                                               | _See section below_ |\n| `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`              |\n| `verbose`             | `boolean`            | Log information about the conversion process to the console.                                                                                                                                                                                                  | `false`             |\n\n### `TldrawImageOptions`\n\n| Key           | Type             | Description                                                                                                                                      | Default |\n| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |\n| `format`      | `\"png\" \\| \"svg\"` | Output image format.                                                                                                                             | `\"svg\"` |\n| `transparent` | `boolean`        | Output image with a transparent background.                                                                                                      | `false` |\n| `dark`        | `boolean`        | Output a dark theme version of the image.                                                                                                        | `false` |\n| `stripStyle`  | `boolean`        | Remove `\u003cstyle\u003e` elements from SVG output, useful to lighten the load of embedded fonts or if you are providing your own stylesheet for the SVG. | `false` |\n| `padding`     | `number`         | Set a specific padding amount around the exported image.                                                                                         | `32`    |\n| `scale`       | `number`         | Set a sampling factor for raster image exports.                                                                                                  | `1`     |\n\n### Plugin options example\n\nConfigure the plugin to always generate PNGs with a transparent background, and to log conversion details:\n\n```ts\n// Vite.config.ts\nimport tldraw from '@kitschpatrol/vite-plugin-tldraw'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [\n    tldraw({\n      format: 'png',\n      transparent: true,\n      verbose: true,\n    }),\n  ],\n})\n```\n\nThe `@kitschpatrol/vite-plugin-tldraw` also exports `TldrawPluginOptions` and `TldrawImageOptions` types for your convenience.\n\n## Import path options\n\nImport directives may include query parameters to set image conversion options on a per-import basis.\n\nQuery parameters take precedence over `TldrawPluginOptions` set at plugin instantiation in your `vite.config.ts`.\n\n_Note: Due to [constraints in TypeScript's module declaration wildcards](https://github.com/microsoft/TypeScript/issues/38638), the import path must be suffixed with `\u0026tldr` or `\u0026tldraw` when query parameters are used._\n\n### Additional query parameter options\n\nIn addition to all `TldrawImageOptions`, query parameters also accept additional options for selecting specific parts of a sketch:\n\n| Key     | Type                  | Description                                                                                                                                                                              | Default     |\n| ------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `frame` | `string \\| undefined` | When defined, outputs only a specific frame from the `.tldr` file. Provide either the frame name or its shape ID, e.g. `Frame 1`. Slugified frame names will also match, e.g. `frame-1`. | `undefined` |\n| `page`  | `string \\| undefined` | When defined, outputs only a specific page from the `.tldr` file. Provide either the frame name or its page ID, e.g. `Page 1`. Slugified frame names will also match, e.g. `page-1`.     | `undefined` |\n\n### Import path query parameter examples\n\n```ts\n// Example.ts\nimport tldrImageFrame from './test/assets/test-sketch-three-frames.tldr?frame=frame-1\u0026tldr'\nimport tldrImagePng from './test/assets/test-sketch.tldr?format=png\u0026tldr'\nimport tldrImageTransparentPng from './test/assets/test-sketch.tldr?format=png\u0026transparent=true\u0026tldr'\n\n// Logs a PNG URL\nconsole.log(tldrImagePng)\n\n// Logs a transparent-background PNG URL\nconsole.log(tldrImageTransparentPng)\n\n// Logs an SVG URL for \"Frame 1\" in the source `.tldr`\nconsole.log(tldrImageFrame)\n```\n\n## Implementation notes\n\nThis tool is not a part of the official tldraw project, and it is currently only tested and known to be compatible with tldraw 2.0.0-beta.2.\n\nBehind the scenes, the plugin calls [@kitschpatrol/tldraw-cli](https://github.com/kitschpatrol/tldraw-cli)'s Node API to generate image files from `.tldr` files, and then passes the resulting URL as the value of the module import.\n\nBecause [`tldraw-cli`](https://github.com/kitschpatrol/tldraw-cli) relies on the browser automation tool [Puppeteer](https://pptr.dev) for its output, conversion can be a bit slow (on the order of a second or two), so by default generated image assets are cached to expedite subsequent builds.\n\nDuring development, images are served from the cache, and when Vite builds for production the image files are bundled into the output with a hashed filename to simplify cache busting.\n\n## The future\n\nPossible paths for future improvements include the following:\n\n- Rollup cross-compatibility\n- Support importing tldraw\\.com URLs\n- SVG compression, PNG resizing / optimization (or test integration with other asset pipeline plugins)\n\nAny other suggestions are welcome.\n\nI'm consciously releasing this tool under the `@kitschpatrol` namespace on NPM to leave the `vite-plugin-tldraw` package name available to the core tldraw project.\n\n## References\n\nSome links and issues from development are retained for my own reference below:\n\n**TypeScript module query parameter compatibility:**\n\n- https://github.com/microsoft/TypeScript/issues/38638\n- https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules\n- https://github.com/JonasKruckenberg/imagetools/issues/70\n- https://github.com/JonasKruckenberg/imagetools/issues/160\n\n**Vite asset plugin approach:**\n\n- https://github.com/vitejs/vite/discussions/7515\n- https://liana.one/custom-language-plugin-for-vite\n- https://github.com/UstymUkhman/vite-plugin-glsl\n\n**Vite asset Path issues:**\n\n- https://github.com/vitejs/vite/issues/2394\n- https://github.com/vitejs/vite/issues/1997\n\n## Maintainers\n\n[@kitschpatrol](https://github.com/kitschpatrol)\n\n\u003c!-- footer --\u003e\n\n## Contributing\n\n[Issues](https://github.com/kitschpatrol/vite-plugin-tldraw/issues) and pull requests are welcome.\n\n## License\n\n[MIT](license.txt) © Eric Mika\n\n\u003c!-- /footer --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Fvite-plugin-tldraw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitschpatrol%2Fvite-plugin-tldraw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Fvite-plugin-tldraw/lists"}