@kitschpatrol/tldraw-cli 4.1.0 → 4.1.2

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.
Files changed (4) hide show
  1. package/bin/cli.js +3 -2
  2. package/dist/lib/index.js +1 -2
  3. package/package.json +3 -3
  4. package/readme.md +119 -59
package/bin/cli.js CHANGED
@@ -17257,8 +17257,7 @@ var TldrawController = class {
17257
17257
  if (!this.page)
17258
17258
  throw new Error("Controller not started");
17259
17259
  log_default.info(`Setting dark mode: ${darkMode}`);
17260
- if (!this.originalDarkMode)
17261
- this.originalDarkMode = await this.getDarkMode();
17260
+ this.originalDarkMode ??= await this.getDarkMode();
17262
17261
  await this.page.evaluate(`editor.user.updateUserPreferences({ isDarkMode: ${darkMode}})`);
17263
17262
  }
17264
17263
  async loadFile(filePath) {
@@ -23156,6 +23155,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
23156
23155
  '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.',
23157
23156
  (yargs) => yargs.positional("files-or-urls", {
23158
23157
  array: true,
23158
+ default: void 0,
23159
23159
  demandOption: true,
23160
23160
  describe: "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`.",
23161
23161
  type: "string"
@@ -23276,6 +23276,7 @@ await yargsInstance.scriptName("tldraw-cli").command("$0 <command>", "CLI tools
23276
23276
  "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.",
23277
23277
  (yargs) => yargs.positional("files-or-urls", {
23278
23278
  array: true,
23279
+ default: void 0,
23279
23280
  describe: "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`.",
23280
23281
  type: "string"
23281
23282
  }).option("local", {
package/dist/lib/index.js CHANGED
@@ -17059,8 +17059,7 @@ var TldrawController = class {
17059
17059
  if (!this.page)
17060
17060
  throw new Error("Controller not started");
17061
17061
  log_default.info(`Setting dark mode: ${darkMode}`);
17062
- if (!this.originalDarkMode)
17063
- this.originalDarkMode = await this.getDarkMode();
17062
+ this.originalDarkMode ??= await this.getDarkMode();
17064
17063
  await this.page.evaluate(`editor.user.updateUserPreferences({ isDarkMode: ${darkMode}})`);
17065
17064
  }
17066
17065
  async loadFile(filePath) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kitschpatrol/tldraw-cli",
3
- "version": "4.1.0",
3
+ "version": "4.1.2",
4
4
  "type": "module",
5
5
  "description": "A tiny little CLI tool for exporting tldraw sketches to svg or png images.",
6
6
  "repository": {
@@ -46,12 +46,12 @@
46
46
  "puppeteer": "^22.2.0"
47
47
  },
48
48
  "devDependencies": {
49
- "@kitschpatrol/shared-config": "^4.4.0",
49
+ "@kitschpatrol/shared-config": "^4.4.2",
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.57",
54
+ "@types/react": "^18.2.58",
55
55
  "@types/react-dom": "^18.2.19",
56
56
  "@types/yargs": "^17.0.32",
57
57
  "@vitejs/plugin-react-swc": "^3.6.0",
package/readme.md CHANGED
@@ -1,10 +1,37 @@
1
+ <!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +-->
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
+ - [Usage](#usage)
21
+ - [CLI](#cli)
22
+ - [API](#api)
23
+ - [Background](#background)
24
+ - [Implementation notes](#implementation-notes)
25
+ - [The future](#the-future)
26
+ - [Maintainers](#maintainers)
27
+ - [Contributing](#contributing)
28
+ - [License](#license)
29
+
30
+ <!-- /table-of-contents -->
4
31
 
5
32
  ## Overview
6
33
 
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.**
34
+ A CLI app to automate conversion and export of [tldraw](https://tldraw.dev) URLs and `.tldr` files into SVG or PNG image formats.
8
35
 
9
36
  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
37
 
@@ -30,72 +57,90 @@ npm install --save-dev @kitschpatrol/tldraw-cli
30
57
  npm install --global @kitschpatrol/tldraw-cli
31
58
  ```
32
59
 
33
- ## Command line usage
60
+ ## Usage
34
61
 
35
- ### Invocation
62
+ ### CLI
36
63
 
37
- `tldraw-cli`'s functionality is organized into several sub-commands.
64
+ <!-- cli-help -->
38
65
 
39
- #### Top-level
66
+ #### Command: `tldraw-cli`
40
67
 
41
- ```sh
68
+ CLI tools for tldraw.
69
+
70
+ This section lists top-level commands for `tldraw-cli`.
71
+
72
+ Usage:
73
+
74
+ ```txt
42
75
  tldraw-cli <command>
43
76
  ```
44
77
 
45
- The top-level collection of CLI tools for tldraw.
78
+ | Command | Argument | Description |
79
+ | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
80
+ | `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. |
81
+ | `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
82
 
47
- | Argument | Description |
48
- | --------- | ----------------------------------------------------------------- |
49
- | `command` | CLI tools for tldraw. Available commands are `export` and `open`. |
83
+ | Option | Alias | Description | Type |
84
+ | ----------- | ----- | ------------------- | --------- |
85
+ | `--help` | `-h` | Show help | `boolean` |
86
+ | `--version` | `-v` | Show version number | `boolean` |
50
87
 
51
- | Option | Alias | Description |
52
- | ----------- | ----- | -------------------- |
53
- | `--help ` | `-h` | Show help. |
54
- | `--version` | `-v` | Show version number. |
88
+ _See the sections below for more information on each subcommand._
55
89
 
56
- #### Command: Export
90
+ #### Subcommand: `tldraw-cli export`
57
91
 
58
- ```sh
92
+ 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.
93
+
94
+ Usage:
95
+
96
+ ```txt
59
97
  tldraw-cli export <files-or-urls..>
60
98
  ```
61
99
 
62
- Export a tldraw `.tldr` file or tldraw\.com URL to SVG, PNG, and other formats.
100
+ | Positional Argument | Description | Type |
101
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
102
+ | `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
103
 
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`. |
104
+ | Option | Alias | Description | Type | Default |
105
+ | --------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------- |
106
+ | `--format` | `-f` | Output image format. | `string` | `"svg"` |
107
+ | `--output` | `-o` | Output image directory. | `string` | `"./"` |
108
+ | `--name` | `-n` | Output image name (without extension). | `string` | The original file name or URL id is used. |
109
+ | `--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` |
110
+ | `--transparent` | `-t` | Export an image with a transparent background. | `boolean` | `false` |
111
+ | `--dark` | `-d` | Export a dark theme version of the image. | `boolean` | `false` |
112
+ | `--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` |
113
+ | `--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` |
114
+ | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
115
+ | `--help` | `-h` | Show help | `boolean` | |
116
+ | `--version` | `-v` | Show version number | `boolean` | |
67
117
 
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` |
118
+ #### Subcommand: `tldraw-cli open`
79
119
 
80
- #### Command: Open
120
+ 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
121
 
82
- ```sh
122
+ Usage:
123
+
124
+ ```txt
83
125
  tldraw-cli open [files-or-urls..]
84
126
  ```
85
127
 
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.
128
+ | Positional Argument | Description | Type |
129
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
130
+ | `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` |
87
131
 
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._
132
+ | Option | Alias | Description | Type | Default |
133
+ | ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
134
+ | `--local` | `-l` | Open the file or URL in a local instance of tldraw, instead of tldraw\.com. | `boolean` | `false` |
135
+ | `--verbose` | | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to `stderr` for ease of redirection. | `boolean` | `false` |
136
+ | `--help` | `-h` | Show help | `boolean` | |
137
+ | `--version` | `-v` | Show version number | `boolean` | |
89
138
 
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`. |
139
+ <!-- /cli-help -->
93
140
 
94
- No options.
141
+ #### Examples
95
142
 
96
- ## Examples
97
-
98
- ### Basic `.tldr` file image export
143
+ ##### Basic `.tldr` file image export
99
144
 
100
145
  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
146
 
@@ -105,17 +150,17 @@ tldraw-cli export your-drawing.tldr
105
150
 
106
151
  The file will retain its original name, e.g. `your-drawing.svg`
107
152
 
108
- ### Basic tldraw\.com image download
153
+ ##### Basic tldraw\.com image download
109
154
 
110
155
  ```sh
111
156
  tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4
112
157
  ```
113
158
 
114
- The tldraw.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
159
+ The tldraw\.com URL's id (e.g. `v2_c_JsxJk8dag6QsrqExukis4`) will be used for the file name.
115
160
 
116
161
  This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → SVG" menu item.
117
162
 
118
- ### Export a remote tldraw\.com image to a local .tldr file
163
+ ##### Export a remote tldraw\.com image to a local .tldr file
119
164
 
120
165
  ```sh
121
166
  tldraw-cli export https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4 --format tldr
@@ -125,7 +170,7 @@ This is approximately equivalent to clicking the tldraw\.com "☰ → File → S
125
170
 
126
171
  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
172
 
128
- ### Export to a specific image / file format
173
+ ##### Export to a specific image / file format
129
174
 
130
175
  ```sh
131
176
  tldraw-cli export your-drawing.tldr --format png
@@ -133,7 +178,7 @@ tldraw-cli export your-drawing.tldr --format png
133
178
 
134
179
  This is approximately equivalent to clicking the tldraw\.com "☰ → Edit → Export As → PNG" menu item.
135
180
 
136
- ### Export with a transparent background
181
+ ##### Export with a transparent background
137
182
 
138
183
  ```sh
139
184
  tldraw-cli export your-drawing.tldr --transparent --format png
@@ -141,7 +186,7 @@ tldraw-cli export your-drawing.tldr --transparent --format png
141
186
 
142
187
  This is approximately equivalent to checking the tldraw\.com "☰ → Edit → Export As → ☐ Transparent" menu item.
143
188
 
144
- ### Export to a specific destination
189
+ ##### Export to a specific destination
145
190
 
146
191
  ```sh
147
192
  tldraw-cli export your-drawing.tldr --output ~/Desktop
@@ -149,7 +194,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop
149
194
 
150
195
  Exports to `~/Desktop/your-drawing.svg`
151
196
 
152
- ### Export to a specific destination and filename
197
+ ##### Export to a specific destination and filename
153
198
 
154
199
  ```sh
155
200
  tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
@@ -157,7 +202,7 @@ tldraw-cli export your-drawing.tldr --output ~/Desktop --name not-your-drawing
157
202
 
158
203
  Exports to `~/Desktop/not-your-drawing.svg`
159
204
 
160
- ### Export all frames from a tldraw.com URL
205
+ ##### Export all frames from a tldraw\.com URL
161
206
 
162
207
  ```sh
163
208
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames
@@ -173,19 +218,19 @@ The frame name will be slugified.
173
218
 
174
219
  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
220
 
176
- ### Export a specific frame from a tldraw.com URL
221
+ ##### Export a specific frame from a tldraw\.com URL
177
222
 
178
223
  ```sh
179
224
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 3"
180
225
  ```
181
226
 
182
- ### Export multiple frames from a tldraw.com URL
227
+ ##### Export multiple frames from a tldraw\.com URL
183
228
 
184
229
  ```sh
185
230
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"
186
231
  ```
187
232
 
188
- ### Export to JSON
233
+ ##### Export to JSON
189
234
 
190
235
  ```sh
191
236
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --format "json"
@@ -195,13 +240,13 @@ The `.tldr` file format is also JSON under the covers, but the `--format json` f
195
240
 
196
241
  I'm not completely clear on the use-case for this format, but since tldr.com supports it, so too shall `tldraw-cli`.
197
242
 
198
- ### Write an SVG to stdout
243
+ ##### Write an SVG to stdout
199
244
 
200
245
  ```sh
201
246
  tldraw-cli export https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --print
202
247
  ```
203
248
 
204
- ### Open a tldraw.com URL
249
+ ##### Open a tldraw\.com URL
205
250
 
206
251
  ```sh
207
252
  tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
@@ -209,7 +254,7 @@ tldraw-cli open https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw
209
254
 
210
255
  The remote sketch is copied to a locally-hosted instance of tldraw, which is then opened in your default browser.
211
256
 
212
- ## API usage
257
+ ### API
213
258
 
214
259
  The `export` command's functionality is also provided in module form for use in TypeScript or JavaScript Node projects.
215
260
 
@@ -316,14 +361,13 @@ The local instance of tldraw includes its assets dependencies, so the tool shoul
316
361
 
317
362
  ## The future
318
363
 
319
- This is a very minimal implementation. Current plans for future improvements include the following:
364
+ Current plans for future improvements include the following:
320
365
 
321
366
  - Add save button to local tldraw
322
367
  - Accept globs and optimize batch processing with a single Puppeteer instance
323
368
  - Add CLI tests
324
369
  - Implement the ability to export specific pages as separate image files
325
370
  - Add an option flag to set dpi when exporting to a bitmap format
326
- - Additional commands beyond sketch conversion / export?
327
371
  - There's room for optimization in how tldraw functions are passed to Puppeteer
328
372
  - There's room for optimization in the `--print` option implementation
329
373
 
@@ -332,3 +376,19 @@ Any other suggestions are welcome.
332
376
  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
377
 
334
378
  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.
379
+
380
+ ## Maintainers
381
+
382
+ [@kitschpatrol](https://github.com/kitschpatrol)
383
+
384
+ <!-- footer -->
385
+
386
+ ## Contributing
387
+
388
+ [Issues](https://github.com/kitschpatrol/tldraw-cli/issues) and pull requests are welcome.
389
+
390
+ ## License
391
+
392
+ [MIT](license.txt) © Eric Mika
393
+
394
+ <!-- /footer -->