Guides / Files and sandboxing

Files and sandboxing

Store app data in its sandbox. Use a native picker when the user chooses a file outside it.

1) Start with a dedicated app-data directory#

Use the writable app-data location on desktop and mobile. Treat the bundled resource directory as read-only:

import * as fs from 'oro:fs/promises'
import { DATA } from 'oro:path/well-known'
import { join } from 'oro:path'

if (!DATA) throw new Error('App data directory is unavailable')
const dataDirectory = join(DATA, 'field-notes')
const statePath = join(dataDirectory, 'state.json')
await fs.mkdir(dataDirectory, { recursive: true })

Use ordinary JSON for early iterations. Move to SQLite once the model is stable.

2) Read and write structured files#

// Continue in the same module.
async function loadState() {
  try {
    const text = await fs.readFile(statePath, 'utf8')
    return JSON.parse(text)
  } catch (error) {
    if (error.code === 'ENOENT') return { notes: [] }
    throw error
  }
}

async function saveState(state) {
  await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf8')
}

This is enough for preferences, cached drafts, import history, and lightweight app state.

3) Keep the sandbox enabled by default#

The sandbox exists to prevent accidental or unsafe file access:

[filesystem]
sandbox_enabled = true
no_follow_symlinks = true

Keep both on unless you have a concrete reason not to. They make your app’s file behavior easier to reason about.

4) Use native pickers for external files#

When users need to import or inspect files outside your app’s controlled data directory, use a picker:

import application from 'oro:application'
import * as fs from 'oro:fs/promises'

const currentWindow = await application.getCurrentWindow()
const [path] = await currentWindow.showOpenFilePicker({ multiple: false })

if (path) {
  const text = await fs.readFile(path, 'utf8')
  console.log(text)
}

That keeps explicit user intent in the loop.

5) Bundle only what the app needs#

Your bundle inputs should stay separate from mutable user data:

"./dist/index.html" = "index.html"
"./dist/main.js" = "main.js"
"./assets/icon.png" = "assets/icon.png"

Do not write back into the bundled resource tree at runtime. Treat it as read-only application content.

6) A practical rule of thumb#

  • Bundle: HTML, CSS, JS, icons, offline shell assets.
  • Runtime data: user notes, caches, imported files, session state.
  • Secure storage: secrets such as refresh tokens or encryption keys.

Keeping those boundaries clean makes packaging, updates, and debugging simpler.

Next#

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.