History

alex 965bc10997 [1/4] Blob storage in TLStore (#4068 ) Reworks the store to include information about how blob assets (images/videos) are stored/retrieved. This replaces the old internal-only `assetOptions` prop, and supplements the existing `registerExternalAssetHandler` API. Previously, `registerExternalAssetHandler` had two responsibilities: 1. Extracting asset metadata 2. Uploading the asset and returning its URL Existing `registerExternalAssetHandler` implementation will still work, but now uploading is the responsibility of a new `editor.uploadAsset` method which calls the new store-based upload method. Our default asset handlers extract metadata, then call that new API. I think this is a pretty big improvement over what we had before: overriding uploads was a pretty common ask, but doing so meant having to copy paste our metadata extraction which felt pretty fragile. Just in this codebase, we had a bunch of very slightly different metadata extraction code-paths that had been copy-pasted around then diverged over time. Now, you can change how uploads work without having to mess with metadata extraction and vice-versa. As part of this we also: 1. merge the old separate asset indexeddb store with the main one. because this warrants some pretty big migration stuff, i refactored our indexed-db helpers to work around an instance instead of being free functions 2. move our existing asset stuff over to the new approach 3. add a new hook in `sync-react` to create a demo store with the new assets ### Change type - [x] `api` ### Release notes Introduce a new `assets` option for the store, describing how to save and retrieve asset blobs like images & videos from e.g. a user-content CDN. These are accessible through `editor.uploadAsset` and `editor.resolveAssetUrl`. This supplements the existing `registerExternalAssetHandler` API: `registerExternalAssetHandler` is for customising metadata extraction, and should call `editor.uploadAsset` to save assets. Existing `registerExternalAssetHandler` calls will still work, but if you're only using them to configure uploads and don't want to customise metadata extraction, consider switching to the new `assets` store prop.		2024-07-10 13:00:18 +00:00
..
src	[1/4] Blob storage in TLStore (#4068 )	2024-07-10 13:00:18 +00:00
api-extractor.json	transfer-out: transfer out	2023-04-25 12:01:25 +01:00
api-report.md	[1/4] Blob storage in TLStore (#4068 )	2024-07-10 13:00:18 +00:00
CHANGELOG.md	Update CHANGELOG.md [skip ci]	2024-06-25 13:27:57 +00:00
LICENSE.md	Change licenses to tldraw (#2167 )	2023-12-19 10:41:01 +00:00
package.json	Update CHANGELOG.md [skip ci]	2024-06-25 13:27:57 +00:00
README.md	Update READMEs, add form link (#3741 )	2024-05-12 20:48:07 +00:00
tsconfig.json	Check tsconfig "references" arrays (#2891 )	2024-02-21 13:07:53 +00:00

README.md

@tldraw/tlschema

This package houses type definitions, schema migrations, and other type metadata for the tldraw editor's default persisted data.

There are three main kinds of types:

Record types

These are root record types added to the Store class. They are defined in the ./src/records directory.
Shape types

These are subtypes of the root TLShape record type. They allow specifying a unique name and custom props for a particular kind of shape.
Asset types

These are subtypes of the root TLAsset record type. They allow specifying a unique name and custom props for a particular kind of asset.

Adding migrations

If you make any kind of change to any persisted data shape in this package, you must add migrations that are able to convert old versions to new versions, and vice-versa.

If you are making a change that affects the structure of a record, shape, or asset, update the migrations in the same file as the record, shape, or asset is defined.

If you are making a change that affects the structure of the store (e.g. renaming or deleting a type, consolidating two shape types into one, etc), add your changes in the migrations in schema.ts.

After making your changes, add a new version number, using a meaninful name. For example, if you add a new property to the TLShape type called ownerId that points to a user, you might do this:

In TLShape.ts

 const Versions = {
   RemoveSomeProp: 1,
+  AddOwnerId: 2,
 } as const

and then in the TLShape type

   x: number
   y: number
+  ownerId: ID<TLUser> | null
   props: Props
   parentId: ID<TLShape> | ID<TLPage>

and then adding a migration:

 export const shapeTypeMigrations = defineMigrations({
   currentVersion: Versions.Initial,
   firstVersion: Versions.Initial,
   migrators: {
+    [Versions.AddOwnerId]: {
+      // add ownerId property
+      up: (shape) => ({...shape, ownerId: null}),
+      // remove ownerId property
+      down: ({ownerId, ...shape}) => shape,
+    }
   },

After you've added your migration, make sure to add a test for it in src/migrations.test.ts. It will complain if you do not!

Distributions

You can find tldraw on npm here.

Contribution

Please see our contributing guide. Found a bug? Please submit an issue.

License

The tldraw source code and its distributions are provided under the tldraw license. This license does not permit commercial use. To purchase a commercial license or learn more, please fill out this form.

Trademarks

Contact

Find us on Twitter/X at @tldraw.

Community

Have questions, comments or feedback? Join our discord or start a discussion. For the latest news and release notes, check out our Substack.