@kitschpatrol/tldraw-cli 4.0.0 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,8 +4,8 @@
4
4
  <meta charset="UTF-8" />
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <title>tldraw via tldraw-cli</title>
7
- <script type="module" crossorigin src="/assets/index-R37c2LB5.js"></script>
8
- <link rel="stylesheet" crossorigin href="/assets/index-1gkReWLJ.css">
7
+ <script type="module" crossorigin src="/assets/index-C93mJRxX.js"></script>
8
+ <link rel="stylesheet" crossorigin href="/assets/index-DWCRF5Ys.css">
9
9
  </head>
10
10
  <body>
11
11
  <div id="root"></div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kitschpatrol/tldraw-cli",
3
- "version": "4.0.0",
3
+ "version": "4.1.1",
4
4
  "type": "module",
5
5
  "description": "A tiny little CLI tool for exporting tldraw sketches to svg or png images.",
6
6
  "repository": {
@@ -43,37 +43,37 @@
43
43
  ],
44
44
  "dependencies": {
45
45
  "express": "^4.18.2",
46
- "puppeteer": "^22.0.0"
46
+ "puppeteer": "^22.2.0"
47
47
  },
48
48
  "devDependencies": {
49
- "@kitschpatrol/shared-config": "^4.3.3",
49
+ "@kitschpatrol/shared-config": "^4.4.1",
50
50
  "@sindresorhus/slugify": "^2.2.1",
51
51
  "@tldraw/assets": "2.0.0-canary.e6e4e7f6cbac",
52
52
  "@tldraw/tldraw": "2.0.0-canary.e6e4e7f6cbac",
53
53
  "@types/express": "^4.17.21",
54
- "@types/react": "^18.2.53",
55
- "@types/react-dom": "^18.2.18",
54
+ "@types/react": "^18.2.57",
55
+ "@types/react-dom": "^18.2.19",
56
56
  "@types/yargs": "^17.0.32",
57
57
  "@vitejs/plugin-react-swc": "^3.6.0",
58
58
  "bumpp": "^9.3.0",
59
59
  "chalk": "^5.3.0",
60
60
  "cheerio": "1.0.0-rc.12",
61
- "esbuild": "^0.20.0",
61
+ "esbuild": "^0.20.1",
62
62
  "eslint-plugin-react-hooks": "^4.6.0",
63
63
  "eslint-plugin-react-refresh": "^0.4.5",
64
64
  "get-port": "^7.0.0",
65
- "nanoid": "^5.0.5",
65
+ "nanoid": "^5.0.6",
66
66
  "open": "^10.0.3",
67
67
  "path-type": "^5.0.0",
68
68
  "plur": "^5.1.0",
69
69
  "pretty-ms": "^9.0.0",
70
70
  "react": "^18.2.0",
71
71
  "react-dom": "^18.2.0",
72
- "tsx": "^4.7.0",
72
+ "tsx": "^4.7.1",
73
73
  "typescript": "^5.3.3",
74
74
  "untildify": "^5.0.0",
75
- "vite": "^5.0.12",
76
- "vitest": "^1.2.2",
75
+ "vite": "^5.1.4",
76
+ "vitest": "^1.3.1",
77
77
  "yargs": "^17.7.2"
78
78
  },
79
79
  "publishConfig": {
package/readme.md CHANGED
@@ -1,10 +1,36 @@
1
+ <!--+ Warning: Content in HTML comment blocks generated by mdat on 2024-02-22 +-->
2
+
3
+ <!-- header -->
4
+
1
5
  # @kitschpatrol/tldraw-cli
2
6
 
3
- [![NPM Package](https://img.shields.io/npm/v/@kitschpatrol/tldraw-cli.svg)](https://npmjs.com/package/@kitschpatrol/tldraw-cli)
7
+ [![NPM Package @kitschpatrol/tldraw-cli](https://img.shields.io/npm/v/@kitschpatrol/tldraw-cli.svg)](https://npmjs.com/package/@kitschpatrol/tldraw-cli)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+
10
+ **A tiny little CLI tool for exporting tldraw sketches to svg or png images.**
11
+
12
+ <!-- /header -->
13
+
14
+ <!-- table-of-contents { maxDepth: 2 } -->
15
+
16
+ ## Table of contents
17
+
18
+ - [Overview](#overview)
19
+ - [Installation](#installation)
20
+ - [Command line usage](#command-line-usage)
21
+ - [Examples](#examples)
22
+ - [API usage](#api-usage)
23
+ - [Background](#background)
24
+ - [Implementation notes](#implementation-notes)
25
+ - [The future](#the-future)
26
+ - [Contributing](#contributing)
27
+ - [License](#license)
28
+
29
+ <!-- /table-of-contents -->
4
30
 
5
31
  ## Overview
6
32
 
7
- **A minimal CLI app to automate conversion and export of [tldraw](https://tldraw.dev) URLs and `.tldr` files into SVG or PNG image formats.**
33
+ A CLI app to automate conversion and export of [tldraw](https://tldraw.dev) URLs and `.tldr` files into SVG or PNG image formats.
8
34
 
9
35
  This could be useful in the context of a content publishing pipeline where you want to use a `.tldr` file (perhaps under version control) as the "source of truth" for assets to be embedded elsewhere, and you don't want to manage the export of that diagram manually.
10
36
 
@@ -32,70 +58,86 @@ npm install --global @kitschpatrol/tldraw-cli
32
58
 
33
59
  ## Command line usage
34
60
 
35
- ### Invocation
61
+ <!-- cli-help -->
36
62
 
37
- `tldraw-cli`'s functionality is organized into several sub-commands.
63
+ #### Command: `tldraw-cli`
38
64
 
39
- #### Top-level
65
+ CLI tools for tldraw.
40
66
 
41
- ```sh
67
+ This section lists top-level commands for `tldraw-cli`.
68
+
69
+ Usage:
70
+
71
+ ```txt
42
72
  tldraw-cli <command>
43
73
  ```
44
74
 
45
- The top-level collection of CLI tools for tldraw.
75
+ | Command | Argument | Description |
76
+ | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
77
+ | `export` | `<files-or-urls..>` | Export a local tldraw ".tldr" file or a tldraw\.com URL to an svg, png, json, or tldr file. Prints the absolute path(s) to the exported image(s) to stdout. |
78
+ | `open` | `[files-or-urls..]` | Open a tldraw `.tldr` file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are temporarily copied to the local system, and will not be kept in sync with tldraw\.com. This process does not exit until the browser is closed. |
46
79
 
47
- | Argument | Description |
48
- | --------- | ----------------------------------------------------------------- |
49
- | `command` | CLI tools for tldraw. Available commands are `export` and `open`. |
80
+ | Option | Alias | Description | Type |
81
+ | ----------- | ----- | ------------------- | --------- |
82
+ | `--help` | `-h` | Show help | `boolean` |
83
+ | `--version` | `-v` | Show version number | `boolean` |
50
84
 
51
- | Option | Alias | Description |
52
- | ----------- | ----- | -------------------- |
53
- | `--help ` | `-h` | Show help. |
54
- | `--version` | `-v` | Show version number. |
85
+ _See the sections below for more information on each subcommand._
55
86
 
56
- #### Command: Export
87
+ #### Subcommand: `tldraw-cli export`
57
88
 
58
- ```sh
89
+ Export a local tldraw ".tldr" file or a tldraw\.com URL to an svg, png, json, or tldr file. Prints the absolute path(s) to the exported image(s) to stdout.
90
+
91
+ Usage:
92
+
93
+ ```txt
59
94
  tldraw-cli export <files-or-urls..>
60
95
  ```
61
96
 
62
- Export a tldraw `.tldr` file or tldraw\.com URL to SVG, PNG, and other formats.
97
+ | Positional Argument | Description | Type |
98
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
99
+ | `files-or-urls` | The tldraw sketch to export. May be one or more paths to local `.tldr` files, or tldraw\.com sketch URLs. Accepts a mix of both file paths and URLs, and supports glob matching via your shell. Prints the absolute path(s) to the exported image(s) to `stdout`. _(Required.)_ | `array` |
63
100
 
64
- | Argument | Description |
65
- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
66
- | `<files-or-urls..>` | The tldraw sketch to export. May be one or more paths to local `.tldr` files, or tldraw.com sketch URLs. Accepts a mix of both file paths and URLs, and supports glob matching via your shell. Prints the absolute path(s) to the exported image(s) to `stdout`. |
101
+ | Option | Alias | Description | Type | Default |
102
+ | --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
103
+ | `--format` | `-f` | Output image format. | `string` | `"svg"` |
104
+ | `--output` | `-o` | Output image directory. | `string` | `"./"` |
105
+ | `--name` | `-n` | Output image name (without extension). | `string` | The original file name or URL id is used. |
106
+ | `--frames` | | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames. | `array` | `false` |
107
+ | `--transparent` | `-t` | Export an image with a transparent background. | `boolean` | `false` |
108
+ | `--dark` | `-d` | Export a dark theme version of the image. | `boolean` | `false` |
109
+ | `--strip-style` | | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts if you intend to provide your own stylesheets. Applies to SVG output only. | `boolean` | `false` |
110
+ | `--print` | `-p` | Print the exported image(s) to stdout instead of saving to a file. Incompatible with `--output`, and disregards `--name`. PNGs are printed as base64-encoded strings. | `boolean` | `false` |
111
+ | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
112
+ | `--help` | `-h` | Show help | `boolean` | |
113
+ | `--version` | `-v` | Show version number | `boolean` | |
67
114
 
68
- | Option | Alias | Description | Default Value |
69
- | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
70
- | `--format [string]` | `-f` | Output image format, one of `svg`, `png`, `json`, or `tldr`. | `svg` |
71
- | `--output <string>` | `-o` | Output image directory. | `./` |
72
- | `--name <string>` | `-n` | Output image name (without extension). By default the original file name or URL id is used. | |
73
- | `--frames [array]` | | Export each sketch "frame" as a separate image. Pass one or more frame names or IDs to export specific frames, or skip the arguments to export all frames. | `false` |
74
- | `--transparent ` | `-t` | Export an image with a transparent background. | `false` |
75
- | `--dark ` | `-d` | Export a dark theme version of the image. | `false` |
76
- | `--strip-style` | | Remove `<style>` elements from SVG output, useful to lighten the load of embedded fonts if you intend to provide your own stylesheets. Applies to SVG output only. | `false` |
77
- | `--print` | `-p` | Print the exported image(s) to stdout instead of saving to a file. Incompatible with `--output`, and ignores `--name`. PNGs are printed as base64-encoded strings. | `false` |
78
- | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `false` |
115
+ #### Subcommand: `tldraw-cli open`
79
116
 
80
- #### Command: Open
117
+ Open a tldraw `.tldr` file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are temporarily copied to the local system, and will not be kept in sync with tldraw\.com. This process does not exit until the browser is closed.
81
118
 
82
- ```sh
119
+ Usage:
120
+
121
+ ```txt
83
122
  tldraw-cli open [files-or-urls..]
84
123
  ```
85
124
 
86
- Open a tldraw `.tldr` file or tldraw\.com URL your default browser. Uses a locally-hosted instance of tldraw. Call `open` without an argument to open a blank sketch. Sketches opened via URL are temporarily copied to the local system, and will not be kept in sync with tldraw.com. This command does not exit until the browser is closed.
87
-
88
- _"Save as" support is not yet implemented in the local tldraw instance, so the `open` command is only recommended for viewing purposes at the moment._
125
+ | Positional Argument | Description | Type |
126
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
127
+ | `files-or-urls` | The `.tldr` file(s) or tldraw\.com sketch URL(s) to open. Omit the argument to open a blank sketch. Supports glob matching via your shell. Prints the URL of the local server to `stdout`. _(Optional.)_ | `array` |
89
128
 
90
- | Argument | Description |
91
- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
92
- | `[files-or-urls..]` | The `.tldr` file(s) or tldraw\.com sketch URL(s) to open. Omit the argument to open a blank sketch. Supports glob matching via your shell. Prints the URL of the local server to `stdout`. |
129
+ | Option | Alias | Description | Type | Default |
130
+ | ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
131
+ | `--local` | `-l` | Open the file or URL in a local instance of tldraw, instead of tldraw\.com. | `boolean` | `false` |
132
+ | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
133
+ | `--help` | `-h` | Show help | `boolean` | |
134
+ | `--version` | `-v` | Show version number | `boolean` | |
93
135
 
94
- No options.
136
+ <!-- /cli-help -->
95
137
 
96
- ## Examples
138
+ ### Examples
97
139
 
98
- ### Basic `.tldr` file image export
140
+ #### Basic `.tldr` file image export
99
141
 
100
142
  To export the file `your-drawing.tldr` to an SVG named `your-drawing.svg` in the current working directory, run the following command. Note that the default output format is SVG, and the default export location is the current working directory.
101
143
 
@@ -105,17 +147,17 @@ tldraw-cli export your-drawing.tldr
105
147
 
106
148
  The file will retain its original name, e.g. `your-drawing.svg`
107
149
 
108
- ### Basic tldraw\.com image download
150
+ #### Basic tldraw\.com image download
109
151
 
110
152
  ```sh
111
153
  tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
112
154
  ```
113
155
 
114
- The tldraw.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
156
+ The tldraw\.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
115
157
 
116
158
  This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → SVG" menu item.
117
159
 
118
- ### Export a remote tldraw\.com image to a local .tldr file
160
+ #### Export a remote tldraw\.com image to a local .tldr file
119
161
 
120
162
  ```sh
121
163
  tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr
@@ -125,7 +167,7 @@ This is approximately equivalent to clicking the tldraw\.com "☰ → File → S
125
167
 
126
168
  Note that using `--format tldr` with a _file path_ instead of a _URL_ will still send the file through the pipeline, but it's effectively a no-op. (Except perhaps in rare edge cases where tldraw performs a file format version migration).
127
169
 
128
- ### Export to a specific image / file format
170
+ #### Export to a specific image / file format
129
171
 
130
172
  ```sh
131
173
  tldraw-cli export your-drawing.tldr --format png
@@ -133,7 +175,7 @@ tldraw-cli export your-drawing.tldr --format png
133
175
 
134
176
  This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → PNG" menu item.
135
177
 
136
- ### Export with a transparent background
178
+ #### Export with a transparent background
137
179
 
138
180
  ```sh
139
181
  tldraw-cli export your-drawing.tldr --transparent --format png
@@ -141,7 +183,7 @@ tldraw-cli export your-drawing.tldr --transparent --format png
141
183
 
142
184
  This is approximately equivalent to checking the tldraw\.com "☰ → Edit → Export As → ☐ Transparent" menu item.
143
185
 
144
- ### Export to a specific destination
186
+ #### Export to a specific destination
145
187
 
146
188
  ```sh
147
189
  tldraw-cli export your-drawing.tldr --output ~/Desktop
@@ -149,7 +191,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop
149
191
 
150
192
  Exports to `~/Desktop/your-drawing.svg`
151
193
 
152
- ### Export to a specific destination and filename
194
+ #### Export to a specific destination and filename
153
195
 
154
196
  ```sh
155
197
  tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
@@ -157,7 +199,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
157
199
 
158
200
  Exports to `~/Desktop/not-your-drawing.svg`
159
201
 
160
- ### Export all frames from a tldraw.com URL
202
+ #### Export all frames from a tldraw\.com URL
161
203
 
162
204
  ```sh
163
205
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
@@ -173,19 +215,19 @@ The frame name will be slugified.
173
215
 
174
216
  It's possible in tldraw to give multiple frames in a single sketch the same name. In these cases, the frame ID is used in addition to the name to ensure unique output file names.
175
217
 
176
- ### Export a specific frame from a tldraw.com URL
218
+ #### Export a specific frame from a tldraw\.com URL
177
219
 
178
220
  ```sh
179
221
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 3"
180
222
  ```
181
223
 
182
- ### Export multiple frames from a tldraw.com URL
224
+ #### Export multiple frames from a tldraw\.com URL
183
225
 
184
226
  ```sh
185
227
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
186
228
  ```
187
229
 
188
- ### Export to JSON
230
+ #### Export to JSON
189
231
 
190
232
  ```sh
191
233
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --format "json"
@@ -195,13 +237,13 @@ The `.tldr` file format is also JSON under the covers, but the `--format json` f
195
237
 
196
238
  I'm not completely clear on the use-case for this format, but since tldr.com supports it, so too shall `tldraw-cli`.
197
239
 
198
- ### Write an SVG to stdout
240
+ #### Write an SVG to stdout
199
241
 
200
242
  ```sh
201
243
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --print
202
244
  ```
203
245
 
204
- ### Open a tldraw.com URL
246
+ #### Open a tldraw\.com URL
205
247
 
206
248
  ```sh
207
249
  tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
@@ -299,8 +341,8 @@ On GitHub:
299
341
 
300
342
  On Discord:
301
343
 
302
- - [@jorisjh in #ideas_old](https://discord.com/channels/859816885297741824/859816885801713730/1156880056501665802)
303
- - [@Nitsuj in #ideas_old](https://discord.com/channels/859816885297741824/859816885801713730/1020352607920869406)
344
+ - [@jorisjh in #ideas\_old](https://discord.com/channels/859816885297741824/859816885801713730/1156880056501665802)
345
+ - [@Nitsuj in #ideas\_old](https://discord.com/channels/859816885297741824/859816885801713730/1020352607920869406)
304
346
 
305
347
  ## Implementation notes
306
348
 
@@ -316,14 +358,13 @@ The local instance of tldraw includes its assets dependencies, so the tool shoul
316
358
 
317
359
  ## The future
318
360
 
319
- This is a very minimal implementation. Current plans for future improvements include the following:
361
+ Current plans for future improvements include the following:
320
362
 
321
363
  - Add save button to local tldraw
322
364
  - Accept globs and optimize batch processing with a single Puppeteer instance
323
365
  - Add CLI tests
324
366
  - Implement the ability to export specific pages as separate image files
325
367
  - Add an option flag to set dpi when exporting to a bitmap format
326
- - Additional commands beyond sketch conversion / export?
327
368
  - There's room for optimization in how tldraw functions are passed to Puppeteer
328
369
  - There's room for optimization in the `--print` option implementation
329
370
 
@@ -332,3 +373,15 @@ Any other suggestions are welcome.
332
373
  Eventually, I think it would make sense for some kind of CLI tool like this one to be part of the core tldraw project. (Similar to how [tldraw-vscode](https://github.com/tldraw/tldraw/tree/main/apps/vscode) is currently integrated.)
333
374
 
334
375
  I'm consciously releasing this tool under the `@kitschpatrol` namespace on NPM to leave the `tldraw-cli` package name available to the core tldraw project.
376
+
377
+ <!-- footer -->
378
+
379
+ ## Contributing
380
+
381
+ [Issues](https://github.com/kitschpatrol/tldraw-cli/issues) and pull requests are welcome.
382
+
383
+ ## License
384
+
385
+ [MIT](license.txt) © Eric Mika
386
+
387
+ <!-- /footer -->