[ { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n - package-ecosystem: npm\n directory: /\n schedule:\n interval: weekly\n day: sunday\n time: \"01:00\"\n" }, { "path": ".github/workflows/test.yml", "content": "name: Test formatting\n\non:\n push:\n branches:\n - master\n pull_request:\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v1\n - name: Install and test\n run: |\n yarn\n yarn test\n" }, { "path": ".gitignore", "content": ".cache\n.DS_Store\n.yarn-integrity\n*.log\nnode_modules\nnpm-debug.log*\npackage-lock.json\npublic\nyarn-debug.log*\nyarn-error.log\nyarn-error.log*\n" }, { "path": ".prettierignore", "content": ".cache\npublic\n" }, { "path": ".vscode/settings.json", "content": "{\n \"cSpell.enabled\": true\n}\n" }, { "path": ".yarnrc", "content": "--add.exact true\n" }, { "path": "LICENSE", "content": "The MIT License (MIT)\n\nCopyright (c) 2020 Excalidraw\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# Excalidraw Blog\n\n> For news and updates visit: https://blog.excalidraw.com.\n\n## Develop\n\nWe are using [Gatsby](https://www.gatsbyjs.com/) and in order to run it locally, execute the following from the root:\n\n```\nyarn\nyarn start\n```\n\nVisit [`localhost:8000`](http://localhost:8000) to test it.\n\n## Writing a Blog Post\n\n- Create a new folder inside the `content/blog/`\n - The folder name should follow `kebab-case`\n - Use the slug of the title of the post to name it\n- Create `index.md` inside that folder\n- Create `og.png` inside that folder for the open graph image\n- Add a frontmatter\n - `title`: Use Title Case for Titles\n - `date`: Date in ISO format. Example: `2020-03-12`\n - `note`: Optional. Displayed next to the date when reading a post.\n - `image`: Filename of the open graph image. Example: `og.png`\n- The `note` field is usually used to link to the original post when reposting ([example](https://blog.excalidraw.com/reflections-on-excalidraw/))\n- Add somewhere the `` to declare your `excerpt` (it's used on the front page)\n" }, { "path": "content/blog/browser-fs-access/index.md", "content": "---\ntitle: Reading and writing files and directories with the browser-fs-access library\ndate: 2020-12-09\nnote: 'This post appeared first on web.dev.'\nauthor: tomayac\nlink: https://twitter.com/tomayac\nimage: chrome-save-as.png\n---\n\nBrowsers have been able to deal with files and directories for a long time. The [File API](https://w3c.github.io/FileAPI/) provides features for representing file objects in web applications, as well as programmatically selecting them and accessing their data. The moment you look closer, though, all that glitters is not gold.\n\n\n\n## The traditional way of dealing with files\n\n
\n If you know how it used to work the old way, you can\n jump down straight to the new way.\n
\n\n### Opening files\n\nAs a developer, you can open and read files via the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) element. In its simplest form, opening a file can look something like the code sample below. The `input` object gives you a [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList), which in the case below consists of just one [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File). A `File` is a specific kind of [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob), and can be used in any context that a Blob can.\n\n```js\nconst openFile = async () => {\n return new Promise((resolve) => {\n const input = document.createElement(\"input\");\n input.type = \"file\";\n input.addEventListener(\"change\", () => {\n resolve(input.files[0]);\n });\n input.click();\n });\n};\n```\n\n### Opening directories\n\nFor opening folders (or directories), you can set the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-webkitdirectory) attribute. Apart from that, everything else works the same as above. Despite its vendor-prefixed name, `webkitdirectory` is not only usable in Chromium and WebKit browsers, but also in the legacy EdgeHTML-based Edge as well as in Firefox.\n\n### Saving (rather: downloading) files\n\nFor saving a file, traditionally, you are limited to _downloading_ a file, which works thanks to the [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download:~:text=download) attribute. Given a Blob, you can set the anchor's `href` attribute to a `blob:` URL that you can get from the [`URL.createObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL) method.\n\n
\n To prevent memory leaks, always revoke the URL after the download.\n
\n\n```js\nconst saveFile = async (blob) => {\n const a = document.createElement(\"a\");\n a.download = \"my-file.txt\";\n a.href = URL.createObjectURL(blob);\n a.addEventListener(\"click\", (e) => {\n setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);\n });\n a.click();\n};\n```\n\n### The problem\n\nA massive downside of the _download_ approach is that there is no way to make a classic open→edit→save flow happen, that is, there is no way to _overwrite_ the original file. Instead, you end up with a new _copy_ of the original file in the operating system's default Downloads folder whenever you \"save\".\n\n

The File System Access API

\n\nThe File System Access API makes both operations, opening and saving, a lot simpler. It also enables _true saving_, that is, you can not only choose where to save a file, but also overwrite an existing file.\n\n
\n For a more thorough introduction to the File System Access API, see the article\n The File System Access API: simplifying access to local files.\n
\n\n### Opening files\n\nWith the [File System Access API](https://wicg.github.io/file-system-access/), opening a file is a matter of one call to the `window.showOpenFilePicker()` method. This call returns a file handle, from which you can get the actual `File` via the `getFile()` method.\n\n```js\nconst openFile = async () => {\n try {\n // Always returns an array.\n const [handle] = await window.showOpenFilePicker();\n return handle.getFile();\n } catch (err) {\n console.error(err.name, err.message);\n }\n};\n```\n\n### Opening directories\n\nOpen a directory by calling `window.showDirectoryPicker()` that makes directories selectable in the file dialog box.\n\n### Saving files\n\nSaving files is similarly straightforward. From a file handle, you create a writable stream via `createWritable()`, then you write the Blob data by calling the stream's `write()` method, and finally you close the stream by calling its `close()` method.\n\n```js\nconst saveFile = async (blob) => {\n try {\n const handle = await window.showSaveFilePicker({\n types: [\n {\n accept: {\n // Omitted\n },\n },\n ],\n });\n const writable = await handle.createWritable();\n await writable.write(blob);\n await writable.close();\n return handle;\n } catch (err) {\n console.error(err.name, err.message);\n }\n};\n```\n\n## Introducing browser-fs-access\n\nAs perfectly fine as the File System Access API is, it's [not yet widely available](https://caniuse.com/native-filesystem-api).\n\n
\n \"Browser\n
\n Browser support table for the File System Access API.\n (Source)\n
\n
\n\nThis is why I see the File System Access API as a [progressive enhancement](https://web.dev/progressively-enhance-your-pwa). As such, I want to use it when the browser supports it, and use the traditional approach if not; all while never punishing the user with unnecessary downloads of unsupported JavaScript code. The [browser-fs-access](https://github.com/GoogleChromeLabs/browser-fs-access) library is my answer to this challenge.\n\n### Design philosophy\n\nSince the File System Access API is still likely to change in the future, the browser-fs-access API is not modeled after it. That is, the library is not a [polyfill](https://developer.mozilla.org/en-US/docs/Glossary/Polyfill), but rather a [ponyfill](https://github.com/sindresorhus/ponyfill). You can (statically or dynamically) exclusively import whatever functionality you need to keep your app as small as possible. The available methods are the aptly named [`fileOpen()`](https://github.com/GoogleChromeLabs/browser-fs-access#opening-files), [`directoryOpen()`](https://github.com/GoogleChromeLabs/browser-fs-access#opening-directories), and [`fileSave()`](https://github.com/GoogleChromeLabs/browser-fs-access#saving-files). Internally, the library feature-detects if the File System Access API is supported, and then imports the corresponding code path.\n\n### Using the browser-fs-access library\n\nThe three methods are intuitive to use. You can specify your app's accepted `mimeTypes` or file `extensions`, and set a `multiple` flag to allow or disallow selection of multiple files or directories. For full details, see the [browser-fs-access API documentation](https://github.com/GoogleChromeLabs/browser-fs-access#api-documentation). The code sample below shows how you can open and save image files.\n\n```js\n// The imported methods will use the File\n// System Access API or a fallback implementation.\nimport {\n fileOpen,\n directoryOpen,\n fileSave,\n} from \"https://unpkg.com/browser-fs-access\";\n\n(async () => {\n // Open an image file.\n const blob = await fileOpen({\n mimeTypes: [\"image/*\"],\n });\n\n // Open multiple image files.\n const blobs = await fileOpen({\n mimeTypes: [\"image/*\"],\n multiple: true,\n });\n\n // Open all files in a directory,\n // recursively including subdirectories.\n const blobsInDirectory = await directoryOpen({\n recursive: true,\n });\n\n // Save a file.\n await fileSave(blob, {\n fileName: \"Untitled.png\",\n });\n})();\n```\n\n### Demo\n\nYou can see the above code in action in a [demo](https://browser-fs-access.glitch.me/) on Glitch. Its [source code](https://glitch.com/edit/#!/browser-fs-access) is likewise available there. Since for security reasons cross origin sub frames are not allowed to show a file picker, the demo cannot be embedded in this article.\n\n## The browser-fs-access library in the wild\n\nIn my free time, I contribute a tiny bit to an [installable PWA](https://web.dev/progressive-web-apps/#installable) called [Excalidraw](https://excalidraw.com/), a whiteboard tool that lets you easily sketch diagrams with a hand-drawn feel. It is fully responsive and works well on a range of devices from small mobile phones to computers with large screens. This means it needs to deal with files on all the various platforms whether or not they support the File System Access API. This makes it a great candidate for the browser-fs-access library.\n\nI can, for example, start a drawing on my iPhone, save it (technically: download it, since Safari does not support the File System Access API) to my iPhone Downloads folder, open the file on my desktop (after transferring it from my phone), modify the file, and overwrite it with my changes, or even save it as a new file.\n\n
\n \"An\n
\n Starting an Excalidraw drawing on an iPhone where the File System Access API is not supported,\n but where a file can be saved (downloaded) to the Downloads folder.\n
\n
\n\n
\n \"The\n
\n Opening and modifying the Excalidraw drawing on the desktop where the File System Access API is supported\n and thus the file can be accessed via the API.\n
\n
\n\n
\n \"Overwriting\n
\n Overwriting the original file with the modifications to the original Excalidraw drawing file.\n The browser shows a dialog asking me whether this is fine.\n
\n
\n\n
\n \"Saving\n
\n Saving the modifications to a new Excalidraw file. The original file remains untouched.\n
\n
\n\n### Real life code sample\n\nBelow, you can see an actual example of browser-fs-access as it is used in Excalidraw. This excerpt is taken from [`/src/data/json.ts`](https://github.com/excalidraw/excalidraw/blob/cd87bd6901b47430a692a06a8928b0f732d77097/src/data/json.ts#L24-L52). Of special interest is how the `saveAsJSON()` method passes either a file handle or `null` to browser-fs-access' `fileSave()` method, which causes it to overwrite when a handle is given, or to save to a new file if not.\n\n```js\nexport const saveAsJSON = async (\n elements: readonly ExcalidrawElement[],\n appState: AppState,\n fileHandle: any,\n) => {\n const serialized = serializeAsJSON(elements, appState);\n const blob = new Blob([serialized], {\n type: \"application/json\",\n });\n const name = `${appState.name}.excalidraw`;\n (window as any).handle = await fileSave(\n blob,\n {\n fileName: name,\n description: \"Excalidraw file\",\n extensions: [\"excalidraw\"],\n },\n fileHandle || null,\n );\n};\n\nexport const loadFromJSON = async () => {\n const blob = await fileOpen({\n description: \"Excalidraw files\",\n extensions: [\"json\", \"excalidraw\"],\n mimeTypes: [\"application/json\"],\n });\n return loadFromBlob(blob);\n};\n```\n\n### UI considerations\n\nWhether in Excalidraw or your app, the UI should adapt to the browser's support situation. If the File System Access API is supported (`if ('showOpenFilePicker' in window) {}`) you can show a **Save As** button in addition to a **Save** button. The screenshots below show the difference between Excalidraw's responsive main app toolbar on iPhone and on Chrome desktop. Note how on iPhone the **Save As** button is missing.\n\n
\n \"Excalidraw\n
\n Excalidraw app toolbar on iPhone with just a Save button.\n
\n
\n\n
\n \"Excalidraw\n
\n Excalidraw app toolbar on Chrome with a Save and a focused Save As button.\n
\n
\n\n## Conclusions\n\nWorking with native files technically works on all modern browsers. On browsers that support the File System Access API, you can make the experience better by allowing for true saving and overwriting (not just downloading) of files and by letting your users create new files wherever they want, all while remaining functional on browsers that do not support the File System Access API. The [browser-fs-access](https://github.com/GoogleChromeLabs/browser-fs-access) makes your life easier by dealing with the subtleties of progressive enhancement and making your code as simple as possible.\n\n## Acknowledgements\n\nThis article was reviewed by [Joe Medley](https://github.com/jpmedley) and [Kayce Basques](https://github.com/kaycebasques). Thanks to the [contributors to Excalidraw](https://github.com/excalidraw/excalidraw/graphs/contributors) for their work on the project and for reviewing my Pull Requests.\n" }, { "path": "content/blog/building-excalidraw-p2p-collaboration-feature/index.md", "content": "---\ntitle: Building Excalidraw's P2P Collaboration Feature\ndate: 2020-03-29\nauthor: idlewinn\nlink: https://twitter.com/edwinlin1987\nimage: og.png\n---\n\n[Excalidraw](https://excalidraw.com/) is a whiteboard tool that lets you easily sketch diagrams that have a hand-drawn feel to them. As tech companies started to institute mandatory work from home policies due to the [COVID-19 pandemic](https://en.wikipedia.org/wiki/2019%E2%80%9320_coronavirus_pandemic), we realized that Excalidraw could be the perfect substitute for the whiteboard that is usually required for systems design interviews.\n\n\n\nThe problem was that Excalidraw was built to be a fundamentally single-player experience. However, we ([@idlewinn](https://twitter.com/edwinlin1987) and [@floydophone](https://twitter.com/floydophone)) were able to quickly add basic multiplayer support over a long weekend, and are continuing to make improvements to it every day.\n\n## The requirements\n\n- We wanted to be able to use this in our day jobs. In order to do that, it had to support [end-to-end encryption](/end-to-end-encryption/).\n- We did not want to store anything server-side. Therefore, we opted for a pseudo-P2P model, where a central server relays end-to-end encrypted messages to all the peers in the room, but does no centralized coordination.\n\n## Excalidraw's single-player architecture\n\nOriginally, Excalidraw kept an array of all the different drawn shapes -- called `ExcalidrawElement`s -- in Z-index order. The `ExcalidrawElement` interface looked something like this:\n\n```typescript\ninterface ExcalidrawElement {\n id: string;\n type: \"square\" | \"circle\" | \"arrow\";\n width: number;\n height: number;\n // ... other fields describing the shape ...\n canvas: HTMLCanvasElement;\n isSelected: boolean;\n}\n```\n\nThis architecture was very easy to use client-side, but as we'll see, presented some challenges as we moved to multiplayer.\n\n## Moving to multiplayer\n\nWe actually had two parallel multiplayer implementations. One was built on top of [Firebase](https://firebase.com/), the other on top of [Socket.io](https://socket.io/). We ended up going with Socket.io, but both implementations developed the same set of bugs, and the mitigations we applied in one branch were easily ported to the other.\n\nConceptually, we want to share the array of `ExcalidrawElement`s amongst multiple players. The first step was to refactor `ExcalidrawElement` to remove any state specific to a single player. This meant pulling out `canvas` and `isSelected` properties and storing them in a different data structure, as an `HTMLCanvasElement` can't be shared over the network, and every player will have a different selection state. Once we had these properties moved out, we started sharing the `ExcalidrawElement` array between peers.\n\n## Socket.IO\n\nWhen we started investigating multiplayer, we knew that WebSockets would be an important part of the this project because they enable rapid message based communication between clients without polling the server - in order to provide a smooth user experience we would need to sync very frequently. Socket.IO was a great candidate for this project because it's a popular open source library with a lot of support, it has many features relevant to our use case right out of the box, and it has some level of support even for browsers that don't have support for the [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).\n\nSome features of Socket.IO that are particularly beneficial to multiplayer:\n\n- **Auto-reconnection:** if you get disconnected for any reason, you don't need to reload the page to see updates.\n- **Binary Support:** our encrypted messages can be passed between the client and the server back to other clients as `ArrayBuffer`, so we don't need to convert them to other data structures at any point in the transit.\n- **Room Support:** we want to limit updates only to the clients that care about them, and having a separate room per collaborative session was a straightforward way to implement that.\n\n## Dealing with conflicts: adding new elements\n\nOnce we started sharing state between peers, we immediately ran into issues. The first was when elements were added.\n\nIn single-player Excalidraw, we would just append the element to the end of the array. In multiplayer Excalidraw, there was a race condition. If _peer A_ is adding a new element while _peer B_ is changing the color of an existing element, _peer C_ will either lose _peer A_'s new element or _peer B_'s edits. Even worse, if _peer A_ receives _peer B_'s updates while they are editing, the editor would delete the element from right under their mouse! This was clearly a bad user experience and we had to fix it before sharing this with anyone.\n\nhttps://excalidraw.com/#json=5068269564198912,PmL8fegqNyHb0fKxoG6YAA\n\nTo fix this, we adopted an architecture of _merging states_ when we receive them. When _peer A_ receives an update from _peer B_, it looks at all the `ExcalidrawElement.id`s it has locally, and all of the incoming `ExcalidrawElement.id`s, and creates a new `ExcalidrawElement` array containing the union of both the local and incoming set.\n\n## Dealing with conflicts: deleting elements\n\nThere's a big problem with the model above. If we're always keeping the union of all of the elements, there will be no way to delete any shapes from the canvas, as other peers would immediately resync the deleted shape and it would be merged back into the array.\n\nTo solve this problem, we used a method called [tombstoning](). We added a new field to the `ExcalidrawElement` interface called `isDeleted`. Peers would set this field to `true` to delete an element, and would filter the deleted elements out of the array at runtime.\n\nhttps://excalidraw.com/#json=5148123005452288,FnrZbAe4qkHQCSd2BSkUIQ\n\nThe problem with tombstoning is that the size of your list grows forever, as nothing is ever removed from the array. We don't consider this a problem as a shared whiteboard session will only contain a few dozen shapes, but we do remove any element with `isDeleted` set to true when saving to persistent storage, so long-lived drawings where this may become a problem are cleaned up.\n\n## Dealing with conflicts: merging concurrent edits\n\nThere is still a problem with the model. Concurrent edits will still be lost, as our merge algorithm only looks at new elements being added or removed, and not changes to existing elements themselves.\n\nTo fix this, we introduced a new field to `ExcalidrawElement`: a **version number**. Whenever a peer edits an element -- changing its color, deleting it, resizing it, etc -- it increments the version number of that element before sending the state to its peers. Then, when we merge multiple peers state together, we throw out old versions of each element and just keep the latest ones.\n\nhttps://excalidraw.com/#json=5147452789227520,QaCOJixahz7VLHs3eG1s7g\n\nThis algorithm is simple but effective, and solved most of our collaboration problems.\n\n## Dealing with conflicts: breaking ties\n\nThe version number only solves race conditions when players are editing different elements concurrently. What if they're editing the same element concurrently?\n\nFor Excalidraw, we don't really care! We think this will be a pretty rare situation, and that users will tolerate some jankiness if it happens.\n\nWith that said, it is important that all peers converge on the same state. Otherwise, they will see different versions of the drawing and it will be very confusing!\n\nIn order to do this, we made one final change. We added a new field called `versionNonce` to the `ExcalidrawElement`. Any time we increment the `version` of an element, we set `versionNonce` to a random integer. At merge time, if we encounter two elements with the same version number but different data (i.e. two players editing the same element at the same time), we break the tie by favoring the one with the lower `versionNonce`. This ensures that one player will deterministically \"win\" on every peer.\n\n## Future work\n\nOne problem we haven't solved yet is implementing multiplayer undo/redo. Our hack around this was to clear the undo/redo stack whenever you receive an update from a new peer. While this is a subpar user experience, it does solve a common case of one person doing the majority of the whiteboarding, and quickly undoing their most recent action.\n\nMaybe you can help us solve this problem! Go to [our GitHub](https://github.com/excalidraw/excalidraw), fork the repo, and contribute!\n" }, { "path": "content/blog/deprecating-excalidraw-electron/index.md", "content": "---\ntitle: Deprecating Excalidraw Electron in favor of the Web version\ndate: 2020-12-17\nauthor: tomayac\nlink: https://twitter.com/tomayac\nimage: excalidraw-icon.png\n---\n\nOn the [Excalidraw project](https://github.com/excalidraw), we have decided to deprecate [Excalidraw Desktop](https://github.com/excalidraw/excalidraw-desktop), an [Electron](https://www.electronjs.org/) wrapper for Excalidraw, in favor of the web version that you can—and always could—find at [excalidraw.com](https://excalidraw.com/). After a careful analysis, we have decided that [Progressive Web App](https://web.dev/pwa/) (PWA) is the future we want to build upon. Read on to learn why.\n\n\n\n## How Excalidraw Desktop came into being\n\nSoon after [@vjeux](https://twitter.com/vjeux) created the initial version of Excalidraw in January 2020 and [blogged about it](/reflections-on-excalidraw/), he proposed the following in [Issue #561](https://github.com/excalidraw/excalidraw/issues/561#issue-555138343):\n\n> Would be great to wrap Excalidraw within Electron (or equivalent) and publish it as a [platform-specific] application to the various app stores.\n\nThe immediate reaction by [@voluntadpear](https://github.com/voluntadpear) was to suggest:\n\n> What about making it a PWA instead? Android currently supports adding them to the Play Store as Trusted Web Activities and hopefully iOS will do the same soon. On Desktop, Chrome lets you download a desktop shortcut to a PWA.\n\nThe decision that [@vjeux](https://github.com/vjeux) took in the end was simple:\n\n> We should do both :)\n\nWhile work on converting the version of Excalidraw into a PWA was started by [@voluntadpear](https://github.com/voluntadpear) and later others, [@lipis](https://github.com/lipis) independently [went ahead](https://github.com/excalidraw/excalidraw/issues/561#issuecomment-579573783) and created a [separate repo](https://github.com/excalidraw/excalidraw-desktop) for Excalidraw Desktop.\n\nTo this day, the initial goal set by [@vjeux](https://github.com/vjeux), that is, to submit Excalidraw to the various app stores, has not been reached yet. Honestly, no one has even started the submission process to any of the stores. But why is that? Before I answer, let's look at Electron, the platform.\n\n## What is Electron?\n\nThe unique selling point of [Electron](https://www.electronjs.org/) is that it allows you to _\"build cross-platform desktop apps with JavaScript, HTML, and CSS\"_. Apps built with Electron are _\"compatible with Mac, Windows, and Linux\"_, that is, _\"Electron apps build and run on three platforms\"_. According to the homepage, the hard parts that Electron makes easy are [automatic updates](https://www.electronjs.org/docs/api/auto-updater), [system-level menus and notifications](https://www.electronjs.org/docs/api/menu), [crash reporting](https://www.electronjs.org/docs/api/crash-reporter), [debugging and profiling](https://www.electronjs.org/docs/api/content-tracing), and [Windows installers](https://www.electronjs.org/docs/api/auto-updater#windows). Turns out, some of the promised features need a detailed look at the small print.\n\n- For example, automatic updates _\"are [currently] only [supported] on macOS and Windows. There is no built-in support for auto-updater on Linux, so it is recommended to use the distribution's package manager to update your app\"_.\n\n- Developers can create system-level menus by calling `Menu.setApplicationMenu(menu)`. On Windows and Linux, the menu will be set as each window's top menu, while on macOS there are many system-defined standard menus, like the [Services](https://developer.apple.com/documentation/appkit/nsapplication/1428608-servicesmenu?language=objc) menu. To make one's menus a standard menu, developers should set their menu's `role` accordingly, and Electron will recognize them and make them become standard menus. This means that a lot of menu-related code will use the following platform check: `const isMac = process.platform === 'darwin'`.\n\n- Windows installers can be made with [windows-installer](https://github.com/electron/windows-installer). The README of the project highlights that _\"for a production app you need to sign your application. Internet Explorer's SmartScreen filter will block your app from being downloaded, and many anti-virus vendors will consider your app as malware unless you obtain a valid cert\"_ [sic].\n\nLooking at just these three examples, it is clear that Electron is far from \"write once, run everywhere\". Distributing an app on app stores requires [code signing](https://www.electronjs.org/docs/tutorial/code-signing), a security technology for certifying app ownership. Packaging an app requires using tools like [electron-forge](https://github.com/electron-userland/electron-forge) and thinking about where to host packages for app updates. It gets complex relatively quickly, especially when the objective truly is cross platform support. I want to note that it is _absolutely_ possible to create stunning Electron apps with enough effort and dedication. For Excalidraw Desktop, we were not there.\n\n## Where Excalidraw Desktop left off\n\nExcalidraw Desktop so far is basically the Excalidraw web app bundled as an [`.asar`](https://github.com/electron/asar) file with an added **About Excalidraw** window. The look and feel of the application is almost identical to the web version.\n\n
\n \"The\n
Excalidraw Desktop is almost indistinguishable from the Web version
\n
\n\n
\n \"The\n
The About Excalidraw menu providing insights into the versions
\n
\n\nOn macOS, there is now a system-level menu at the top of the application, but since none of the menu actions—apart from **Close Window** and **About Excalidraw**—are hooked up to to anything, the menu is, in its current state, pretty useless. Meanwhile, all actions can of course be performed via the regular Excalidraw toolbars and the context menu.\n\n
\n \"The\n
The menu bar of Excalidraw Desktop on macOS
\n
\n\nWe use [electron-builder](https://github.com/electron-userland/electron-builder), which supports [file type associations](https://www.electron.build/configuration/configuration#PlatformSpecificBuildOptions-fileAssociations). By double-clicking an `.excalidraw` file, ideally the Excalidraw Desktop app should open. The relevant excerpt of our `electron-builder.json` file looks like this:\n\n```json\n{\n \"fileAssociations\": [\n {\n \"ext\": \"excalidraw\",\n \"name\": \"Excalidraw\",\n \"description\": \"Excalidraw file\",\n \"role\": \"Editor\",\n \"mimeType\": \"application/json\"\n }\n ]\n}\n```\n\nUnfortunately, in practice, this does not always work as intended, since, depending on the installation type (for the current user, for all users), apps on Windows 10 do not have the rights to associate a file type to themselves.\n\nThese shortcomings and the pending work to make the experience truly app-like on _all_ platforms (which, again, with enough effort _is_ possible) were a strong argument for us to reconsider our investment in Excalidraw Desktop. The way bigger argument for us, though, was that we foresee that for _our_ use case, we do not need all the features Electron offers. The grown and still growing set of capabilities of the web serves us equally well, if not better.\n\n## How the web serves us today and in the future\n\nEven in 2020, [jQuery](https://jquery.com/) is still [incredibly popular](https://almanac.httparchive.org/en/2020/javascript#libraries). For many developers it has become a habit to use it, despite the fact that today they [might not need jQuery](http://youmightnotneedjquery.com/). There is a similar resource for Electron, aptly called [You Might Not Need Electron](https://youmightnotneedelectron.com/). Let me outline why we think we do not need Electron.\n\n### Installable Progressive Web App\n\nExcalidraw today is an [installable](https://web.dev/installable/) Progressive Web App with a [service worker](https://excalidraw.com/service-worker.js) and a [Web App Manifest](https://excalidraw.com/manifest.json). It caches all its resources in two caches, one for fonts and font-related CSS, and one for everything else.\n\n
\n \"Chrome\n
Excalidraw's cache contents
\n
\n\nThis means the application is fully offline-capable and can run without a network connection. Chromium-based browsers on both desktop and mobile prompt the user to install the app. You can see the installation prompt in the screenshot below.\n\n
\n \"Excalidraw\n
The Excalidraw install dialog in Chrome
\n
\n\nExcalidraw is configured to run as a standalone application, so when you install it, you get an app that runs in its own window. It is fully integrated in the operating system's multitasking UI and gets its own app icon on the home screen, Dock, or task bar; depending on the platform where you install it.\n\n
\n \"Excalidraw\n
The Excalidraw PWA in a standalone window
\n
\n\n
\n \"Excalidraw\n
The Excalidraw icon on the macOS Dock
\n
\n\n### File system access\n\nExcalidraw uses [browser-fs-access](https://github.com/GoogleChromeLabs/browser-fs-access) for accessing the file system of the operating system. On supporting browsers, this allows for a true open→edit→save workflow and actual over-saving and \"save as\", with a transparent fallback for other browsers. You can learn more about this feature in my blog post [Reading and writing files and directories with the browser-fs-access library](/browser-fs-access/).\n\n### Drag and drop support\n\nFiles can be dragged and dropped onto the Excalidraw window just as in platform-specific applications. On a browser that supports the [File System Access API](https://web.dev/file-system-access/), a dropped file can be immediately edited and the modifications be saved to the original file. This is so intuitive that you sometimes forget that you are dealing with a web app.\n\n### Clipboard access\n\nExcalidraw works well with the operating system's clipboard. Entire Excalidraw drawings or also just individual objects can be copied and pasted in `image/png` and `image/svg+xml` formats, allowing for an easy integration with other platform-specific tools like [Inkscape](https://inkscape.org/) or web-based tools like [SVGOMG](https://jakearchibald.github.io/svgomg/).\n\n
\n \"Excalidraw\n
The Excalidraw context menu offering clipboard actions
\n
\n\n### File handling\n\nExcalidraw already supports the experimental [File Handling API](https://web.dev/file-handling/), which means `.excalidraw` files can be double-clicked in the operating system's file manager and open directly in the Excalidraw app, since Excalidraw registers as a file handler for `.excalidraw` files in the operating system.\n\n### Declarative link capturing\n\nExcalidraw drawings can be shared by link. Here is an [example](https://excalidraw.com/#json=4646308765761536,jwZJW8JsOM75vdhqG2nBgA). In the future, if people have Excalidraw installed as a PWA, such links will not open in a browser tab, but launch a new standalone window. Pending implementation, this will work thanks to [declarative link capturing](https://github.com/WICG/sw-launch/blob/master/declarative_link_capturing.md), an, at the time of writing, bleeding-edge proposal for a new web platform feature.\n\n## Conclusion\n\nThe web has come a long way, with more and more features landing in browsers that only a couple of years or even months ago were unthinkable on the web and exclusive to platform-specific applications. Excalidraw is at the forefront of what is possible in the browser, all while acknowledging that not all browsers on all platforms support each feature we use. By betting on a progressive enhancement strategy, we enjoy the latest and greatest wherever possible, but without leaving anyone behind. Best viewed in _any_ browser.\n\nElectron has served us well, but in 2020 and beyond, we can live without it. Oh, and for that objective of [@vjeux](https://github/com/vjeux): since the Android Play Store now accepts PWAs in a container format called [Trusted Web Activity](https://web.dev/using-a-pwa-in-your-android-app/) and since the [Microsoft Store supports PWAs](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps-edgehtml/microsoft-store), too, you can expect Excalidraw in these stores in the not too distant future. Meanwhile, you can always use and install [Excalidraw in and from the browser](https://excalidraw.com/).\n\n## Acknowledgements\n\nThis article was reviewed by [@lipis](https://github.com/lipis), [@dwelle](https://github.com/dwelle), and [Joe Medley](https://github.com/jpmedley).\n" }, { "path": "content/blog/enabling-translations/index.md", "content": "---\ntitle: Enabling Translations\ndate: 2020-04-16\nauthor: Lipis\nlink: https://twitter.com/lipis\n---\n\nFrom the early days people asked for [Excalidraw](https://excalidraw.com) to be translated to other languages. Translation infrastructure and community maintenance have historically been a pain to maintain. Thankfully, with projects like [Crowdin](https://crowdin.com/project/excalidraw) and [i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector), Excalidraw is now translated in 20 languages and the whole process has been very low maintenance.\n\n\n\n## Technical Infrastructure\n\nThe first thing we need to do is to update all our literal strings that need to be translated to be using translated strings from a dictionary.\n\n```js\nimport { t } from \"../i18n\";\n\n{t(\"labels.paste\")};\n```\n\nThe translated strings are stored as JSON in a file per language like this.\n\n```js\n// en.json\n{\n \"labels\": {\n \"paste\": \"Paste\",\n \"selectAll\": \"Select all\",\n \"copy\": \"Copy\",\n \"copyAsPng\": \"Copy to clipboard as PNG\",\n // ...\n }\n}\n```\n\nWe started using a fully fledged internalization library but unfortunately it was a massive dependency and caused multiple React re-renders on startup and added one long round-trip. So instead [we rolled our own](https://github.com/excalidraw/excalidraw/blob/master/src/i18n.ts) in less than 100 lines of code.\n\nSince we don't have that many strings, we decided to bundle all the languages by default to avoid an expensive roundtrip during startup if you're not using English. For this we use `require`.\n\n```js\nexport const languages = [\n { lng: \"en\", label: \"English\", data: require(\"./locales/en.json\") },\n { lng: \"bg-BG\", label: \"Български\", data: require(\"./locales/bg-BG.json\") },\n { lng: \"de-DE\", label: \"Deutsch\", data: require(\"./locales/de-DE.json\") },\n // ...\n];\n```\n\nThe `t` function is pretty simple, where it splits the path by `.` and looks up both the current and fallback languages.\n\n```ts\n// t(\"labels.paste\")\n// + current {\"labels\": {\"paste\": \"Coller\"}}\n// + fallback {\"labels\": {\"paste\": \"Paste\"}}\n// -> \"Coller\"\nexport function t(path: string, replacement?: { [key: string]: string }) {\n const parts = path.split(\".\");\n return (\n findPartsForData(currentLanguage.data, parts) ||\n findPartsForData(fallbackLanguage.data, parts)\n );\n}\n```\n\nThe only external library we're using is [i18next-browser-languagedetector](https://github.com/i18next/i18next-browser-languageDetector) which has a lot of great heuristics to figure out what language the user is currently using.\n\nFinally the last piece of the puzzle is to be able to change the language. We opted for a simple `