How to install a web app and why it matters

What the install button actually does

An install button in a browser is not an installer download. It registers the page as a progressive web app with your operating system, which then launches it in its own window with its own icon, starting from a set URL rather than a web address.

In Canvasola the manifest sets the display mode to standalone, the start URL to /app and the scope to /app, so the installed app opens the editor and nothing else. The File menu inside the editor carries an Install Canvasola item, and the browser's own install icon in the address bar does exactly the same job.

There is a third effect that people rarely expect, and it is the useful one. The service worker is registered in auto-update mode, so when a new version is deployed the cached shell is replaced and the app reloads itself instead of sitting on a stale copy for weeks.

• The app gains its own window, icon and launch point
• The manifest decides what the installed app opens and where
• The same install works on desktop, tablet and phone

Note: Installation changes where the app runs. It does not change where your work is stored, which is the part worth understanding before you install anything.

What the service worker precaches

A service worker is a small program the browser keeps on your device and runs before the page loads. Canvasola registers one and asks it to precache the app shell: the HTML entry point, the bundled JavaScript and CSS, the web fonts and the icons. That cache is why the editor can start with no network.

The precache is deliberately narrow. The navigation fallback only answers for the app path, so the marketing pages and the guides are not pulled into the offline copy, and the cached set stays small enough to open quickly on a phone.

When the precache finishes, the app says it is ready to work offline. That message is the signal to trust, and it is worth waiting for it once after a fresh install rather than assuming the cache is complete.

• The HTML entry point for the app is in the cache
• Bundled scripts, styles and web fonts are in the cache
• The app tells you when the cache is ready

Note: A cache that is still filling is the usual reason a first offline launch fails. Open the app with a connection and give it a minute before you test it.

Why the 3D view loads later

The 3D layer stack is left out of the precache on purpose. It ships as separate chunks: the 3D engine, its camera controls and the 3D interface. Pre-caching them would make every install several times larger for a feature many people never open, so they are fetched the first time you use the 3D view and then kept in a runtime cache.

The 3D view also needs WebGL, which is the browser's hardware-accelerated 3D support. On a device that cannot provide it the stack will not render at all, and no amount of caching changes that. The 3D layer stack guide is worth reading before you plan a layered map for a device you are not sure about.

The practical rule is short: open the 3D view once while you still have a connection. After that it is cached and available offline, and the 3D layer guides cover what to do with it once it is open.

• The 3D engine, camera controls and interface load on first use
• WebGL is required, so some devices cannot render the stack
• Opening it once online is what makes it available offline

Note: The 3D view is the one part of Canvasola that is not ready the moment the install finishes, which is why it is worth doing before a flight rather than during one.

Where your notes live after installing

Installing changes where the app runs, not where the work is kept. The current document is autosaved in browser storage under the key canvasola_document_v2, and the set of open workspace tabs is kept under canvasola_workspace_tabs_v1. Those keys belong to the site in the browser, and the installed app uses the same site, so it finds the same copy.

Cloud sync is a separate, opt-in layer. A free account holds 5 projects of 2 MB each, and sessions last 30 days. Keeping that layer switched off is what makes the local copy the working copy rather than a cache of something held elsewhere.

The third copy is the project file. Saving produces a .canv file, a JSON document with a CANV1 header that carries the canvas elements, the style, the mind map, the App Builder project, the camera and the layout mode, up to 50 MB in size. The backup guide covers keeping one of those per project, and the offline guide separates the three layers.

• canvasola_document_v2 holds the document you are editing
• canvasola_workspace_tabs_v1 holds the list of open workspace tabs
• Cloud sync is opt-in, and small at 5 projects of 2 MB each

Note: The three layers are easy to confuse. The cache runs the app, the autosave protects one document, and a saved project file is the copy you can move.

What clearing site data erases

Clearing site data for a site removes the service worker cache and the local storage in a single action. The consequences arrive together: the installed app stops opening without a connection, and the document autosaved under canvasola_document_v2 along with the workspace tabs under canvasola_workspace_tabs_v1 are gone with it.

Private browsing has a similar effect with a shorter fuse. A private window keeps its storage for that window only, so work done there disappears when the window closes. It is a reasonable place to look at a document you have a copy of, and a poor place to make one.

The recovery path is straightforward once a file exists. Open the app with a connection, let it precache again, and reopen the .canv project. If the file does not exist, the exported formats are what you have, which is why exporting matters even when nothing seems to be wrong.

• Clearing site data removes the cache and the autosave together
• Private browsing discards local work when the window closes
• A .canv file is what makes the loss recoverable
• Reinstalling is a visit with a connection and a wait

Note: Never clear site data to fix a problem in the app before you have saved the important canvases as project files. The cure removes the patient.

Reinstalling on a new device

A new phone or laptop starts with no app and no local copy, so the order matters. Open the app with a connection, install it, let the whole editor load, and then open the .canv file you moved across.

If the old device is already gone, the exports are the fallback rather than the project file. A mind map can be rebuilt from Markdown, OPML 2.0 or the plain-text outline, a canvas can be brought back as SVG or PNG, and an App Builder project can be reopened from the JSON export.

The phone install guide covers the small-screen route, and the complete Canvasola guide shows where the open and save commands live in the File menu.

1. Open the app with a connection. Visit the app in the browser on the new device and let the editor load completely.
2. Install it. Use the browser's install option or the Install Canvasola item in the File menu.
3. Open the project file. Use Open Project to open the .canv file you copied across, rather than rebuilding from a screenshot.
4. Test without a signal. Switch the device to airplane mode, reopen the app and confirm the document is there.

Note: Keep the old device until the new one has passed the offline test. The last copy of a file is always the one on the machine you have not checked yet.

A checklist you can reuse

• The app is installed from the browser rather than bookmarked
• The installed app opens in its own window with the editor
• The offline-ready message appeared after the install
• The 3D view was opened once with a connection if it is needed
• The document and workspace tabs are known to be stored locally
• A .canv file exists for every project that matters
• The new device passed an airplane-mode test before the old one was cleared

Common mistakes to avoid

• Clearing site data to fix a problem. The reset removes the offline cache and the autosaved document in one go. Save the important work as project files first, then reset.
• Working in a private window. A private window forgets everything when it closes, including the map you spent an hour on. Use it to look at a copy, not to make one.
• Assuming the install means the 3D view is ready. The 3D engine downloads on first use, so an offline session that has never opened the stack will not have it. Open it once while you are online.
• Discarding the old device too early. The first offline launch on new hardware can still surprise you. Keep the old device until the new one has opened your document with the radio off.

Frequently asked questions

Does installing a web app download a program onto my computer?

Not in the sense of a native installer. The browser registers the page as an app with the operating system, caches the files it needs so it can start without a connection, and launches it in its own window. The cached copy is what makes the offline start work, and it is updated for you.

Why does the 3D view not work the first time I open it offline?

Because the 3D engine, its camera controls and the 3D interface are downloaded on first use rather than pre-cached at install time, which keeps the install small. Open the 3D view once while you have a connection and those files are cached for later. The stack also needs WebGL, so a device without it will not render the stack at all.

Will an install on one device show my work on another?

Not by itself. The local autosave lives in the browser on the device that made the change, under canvasola_document_v2 for the document and canvasola_workspace_tabs_v1 for the workspace tabs. Copying a .canv file across is the deliberate route, and the optional cloud tier of 5 projects of 2 MB each is the other.

Is there a risk the install makes the app slower on a phone?

The precache is small by design: the app shell, the bundled scripts, styles and fonts, and the icons. Larger pieces, such as the 3D view, are held separately and only when used. The result is an app that opens without waiting for a network round trip, which on a slow connection is faster than the browser version.

This guide is part of the offline and install collection. For the wider product tour, read the complete Canvasola guide, and keep the keyboard shortcut cheat sheet open while you work.