How does export utilities work and how do I save my drawing ?

[vineetdigit]

Hello,

I recently discovered the beautiful Excalidraw, and very delighted by its simplicity. I'm quickly trying to ramp myself up to understand its capabilities in order to map them to a use case I have in mind for my react app.

At a high level, the user starts a new drawing and along the way saves snapshots of the drawing. The user can later go back to any of the snapshot, and use it as a starting point to make further changes. For each of the drawing the user also generates svg that can be shared with other users.

Looking at the demos and the documentation, I suppose I can use exportToSvg to get the svg programmatically.

But how do I save the actual drawing itself. I read that the drawing is saved as JSON. I am not able to understand the difference between exportToBlob and exportToCanvas. Are these calls used for saving the drawing?

Thanks,

Vineet

[ad1992]

@vineetdigit looks like your queries are related to the npm package so I will summarize the usage of the 3 export utilities

• exportToSvg - As you mentioned, this returns the svg of the exported elements.
• exportToBlob This will return the blob representing the image in the canvas, you can specify the mime type here (ex "image/png", "image/jpeg"), so will be useful when you want to convert the drawings to image.
• exportToCanvas - This returns the canvas with the exported elements, app state and dimensions. You can use this when you want to customize the canvas let's say add some custom drawing of yours, for example 👇🏻

const ctx = canvas.getContext("2d");
ctx.font = "30px Virgil";
ctx.strokeText("My custom text", 50, 60);

I have updated the example as well in the demo for the same.

As per your question of saving the drawing, I think you are talking about saving it so users can retrieve the same when they come back to the app the way it works in excalidraw app we save to local storage, similarly, you can save it to your preferred storage using the onChange callback, this gives you the elements as well as the appState so you save these to your storage and pass the same using initialData when initializing excalidraw.

However, right now the onChange callback gets triggered for every minimal change so you might want to optimize it using debounce and also cache the scene version using getSceneVersion so that you only save when the scene version is updated. Adding both of these should suffice to make sure onChange callback is not triggered unnecessarily.

[vineetdigit]

@ad1992 This is an excellent explanation, and has helped further my understanding 🤞

If I have to summarize what I understand about these formats, an Excalidraw drawing is represented as a JSON object which has at two properties, a) an array of elements and b) the app state. This is the format used when the drawing is,

1. saved as the .excalidraw file on the https://excalidraw.com app
2. saved in the local storage on the https://excalidraw.com app
3. fed to the Excalidraw react component via the initialData prop
4. made available to the application via the onChange callback

And then there are exported formats (SVG, PNG, etc). These are essentially "output" only format, i.e. can't be used for editing a drawing.

Is my understanding generally correct?

BTW thanks for updating the demo for the exportToCanvas case. Seems like a great way to draw using HTMLCanvasElement

[ad1992]

Thanks @vineetdigit 🙂
Yes the understand is correct

And then there are exported formats (SVG, PNG, etc). These are essential "output" only formats, i.e. can't be used for editing a drawing.

This can be used for editing the drawing when those files are dropped to the excalidraw app (considering the file contains the scene data if you had exported by checking the option "embed scene data" when exporting).

For .excalidraw file you can just drop it to edit the initial drawing.

To do it programmatically, in the next release we will be exporting some utilities like loadFromBlob which can be used when you want to load the data from blob and pass the json to initialData so excalidraw component can load the initial drawing. To try it out you can use @excalidraw/excalidraw-next

[vineetdigit]

Thanks, again! @ad1992

What is still not clear to me is the format in which the embedded scene gets stored? I thought the original scene is represented as JSON objects. Is JSON somehow exported with the SVG/PNG?

What is the purpose of this functionality? Is it to store the scene data (source) together with the SVG/PNG (output)?

[ad1992]

What is still not clear to me is the format in which the embedded scene gets stored? I thought the original scene is represented as JSON objects. Is JSON somehow exported with the SVG/PNG?

The scene data is stringified + encoded + compressed and appended to SVG/PNG. In case you want to check the implementation, you can check here for image(the metadata is the stringified scene data), and for svg (the text is stringified scene data)

What is the purpose of this functionality? Is it to store the scene data (source) together with the SVG/PNG (output)?

Since we don't support images yet so this is a way for users to retrieve the scene from images if needed.

[vineetdigit]

This is great! Really appreciate your answers. Thanks @ad1992 !!

[lukesmurray]

RESOLVED: I can use restoreAppState and restoreElements to load the app state. I can use serializeAsJSON to save the app state.

@ad1992 I took a look at the localStorage implementation in excalidraw.

export const saveToLocalStorage = (
  elements: readonly ExcalidrawElement[],
  appState: AppState,
) => {
  try {
    localStorage.setItem(
      STORAGE_KEYS.LOCAL_STORAGE_ELEMENTS,
      JSON.stringify(clearElementsForLocalStorage(elements)),
    );
    localStorage.setItem(
      STORAGE_KEYS.LOCAL_STORAGE_APP_STATE,
      JSON.stringify(clearAppStateForLocalStorage(appState)),
    );
  } catch (error) {
    // Unable to access window.localStorage
    console.error(error);
  }
};

It looks like on save there are a couple of helper methods clearElement... which prepare the state to be saved in localStorage.

Similarly on load the application seems to provide helper methods which prepare the state to be serialized from localStorage.

      appState = {
        ...getDefaultAppState(),
        ...clearAppStateForLocalStorage(
          JSON.parse(savedState) as Partial<AppState>,
        ),
      };

These helper methods are not exposed in the package and as a result there are runtime errors since the state saved and loaded from local storage doesn't have the correct shape.

An example of application state not working is the collaborators Map which is unexpectedly null.

collaborators: Map<string, Collaborator>;

[lukesmurray]

restore worked thank you @ad1992! Not sure why I was getting the bug earlier. Sounds like the initialData should have been cleaned up internally but I couldn't reproduce. I'll let you know if I run into any issues going forward! But I appreciate the help!

[vineetdigit]

UPDATE:

Turns out that I wasn't using serializeAsJSON before saving the drawing at the backend. Upon fetching it back, it resulted in the collaborators property NOT being a map leading to this error.

---

I can easily reproduce the above error in App.tsx.

This is essentially what I'm doing.

function DrawingCanvas({initialData, ...}) {
    const onChange = (elements, appState) => {
       // pass elements and appState to the parent of DrawingCanvas
       // which saves them into the backend, and later on passes it back down to
       // DrawingCanvas via initialData
    }

return(
  <Excalidraw  initialData={initialData} />
 )
}

Nowhere along the way I am serializing the appState or using restore utility (which I am going to try next).

@ad1992 Should I open an issue?

[dwelle]

@vineetdigit serializeAsJSON doesn't serialize collaborators — it's not something you want to persist to a database.

[resetmerlin]

@dwelle , Why do I have to serialize? I mean what is the impact of it and what is the best and recommended way to save excalidraw content on db? this is my code and i'm facing issue that it is not bring the latest excalidraw content eventhough the api data is fetching correctly.

'use client';

import React, { useEffect, useState, useCallback } from 'react';
import { useTheme } from 'next-themes';
import { ExcalidrawImperativeAPI, LibraryItems } from '@excalidraw/excalidraw/types/types';
import { Excalidraw as ExcalidrawComp } from '@excalidraw/excalidraw';
import { useSaveExcalidrawQuery } from './remote';
import { ExcalidrawElement } from '@excalidraw/excalidraw/types/element/types';
import { GetExcalidrawResponse } from './model';
import { useDebounce } from '@/hooks';

interface IProps {
  noteId: string;
  data?: GetExcalidrawResponse;
}
const Editor = ({ noteId, data }: IProps) => {
  const { resolvedTheme } = useTheme();
  const [elements, setElements] = useState<readonly ExcalidrawElement[] | null>(null);
  const [library, setLibrary] = useState<LibraryItems | null>(null);
  const [initialLoad, setInitialLoad] = useState<boolean>(true);
  const [excalidrawAPI, setExcalidrawAPI] = useState<ExcalidrawImperativeAPI | null>(null);

  const isDarkMode = resolvedTheme === 'dark';

  const setAPI = useCallback((api: ExcalidrawImperativeAPI | null) => {
    setExcalidrawAPI(api);
  }, []);

  // Callback to update the view background color
  const updateViewBackgroundColor = useCallback(() => {
    if (excalidrawAPI) {
      excalidrawAPI.updateScene({
        appState: {
          viewBackgroundColor: isDarkMode ? 'black' : 'white',
        },
      });
    }
  }, [excalidrawAPI, isDarkMode]);

  useEffect(() => {
    if (resolvedTheme && excalidrawAPI) {
      updateViewBackgroundColor();
    }
  }, [resolvedTheme, excalidrawAPI, updateViewBackgroundColor]);

  useEffect(() => {
    if (data && initialLoad && excalidrawAPI) {
      requestAnimationFrame(() => {
        excalidrawAPI.updateScene({ elements: data.data });
        setElements(data.data );
        setLibrary(data.library);
      });

      setInitialLoad(false);
    }
  }, [data, excalidrawAPI, initialLoad]);

  useSaveExcalidrawQuery(
    {
      excalidraw: elements as any[],
      libraryItems: library as any[],
      noteId,
    },
    {
      enabled: Boolean(elements) && Boolean(library) && Boolean(noteId) && initialLoad === false,
    },
  );

  /** Debounce excalidraw content */
  const debounceDraw = useDebounce((term) => {
    setElements(term);
  }, 500);

  return (
    <ExcalidrawComp
      excalidrawAPI={setAPI}
      onChange={(elements) => {
        if (initialLoad === false) debounceDraw(elements);
      }}
      onLibraryChange={(library) => {
        setLibrary(library);
      }}
      initialData={{
        elements,
        libraryItems: library ?? [],
        appState: {
          viewBackgroundColor: isDarkMode ? 'black' : 'white',
        },
        scrollToContent: true,
      }}
    />
  );
};

export default Editor;

[resetmerlin]

ah I realized that there is no problem of excalidraw. The problem was data cache from React Query, I fixed this issue via putting stale. gcTime 0