Quickstart

Turn a local HTML file into a persistent app.

This is the shortest path: one HTML file, one script, one collection. The file works when opened with a double click.

1. Add the SDK

Paste this before your app script:

<script src="https://iavica.com/sdk/iavica.js"></script>

Local POC: build the bundle with pnpm sdk:build and use <script src="../packages/sdk/dist/iavica.js"></script>.

2. Connect

Use a stable appId. Keep it when you update the app.

const db = Iavica.connect({
  appId: 'YOUR_STABLE_APP_ID',
  appName: 'Family Expenses',
  locale: 'en'
});

const expenses = db.collection('gastos');
await db.ready(); // prompts for email and waits for the magic link

Generate the appId once with crypto.randomUUID() (or ask the AI to do it). Do not generate a new id on every load.

3. Read and write

// Create
await expenses.add({
  date: '2026-11-18',
  concept: 'Coffee',
  amountCents: 250
});

// List
const page = await expenses.list({ limit: 50 });

// Update with optimistic concurrency
await expenses.update(recordId, {
  data: { concept: 'Coffee', amountCents: 300 },
  version: 1
});

// Delete
await expenses.remove(recordId, { version: 2 });

A 409 means another user changed the record. Refresh and retry; never overwrite.

4. Footer and logout

The footer text must be in the app language. For an English app:

<footer>
  <span>Persistent data with <a href="https://iavica.com">IAVICA</a></span>
  <button id="logout" type="button">Log out</button>
</footer>

<script>
  document.getElementById('logout').addEventListener('click', async () => {
    await db.logout();
    location.reload();
  });
</script>

5. Open and approve

  1. Open the HTML from disk.
  2. Enter your email in the IAVICA modal.
  3. Open the email and approve the magic link.
  4. Return to the app. The session is connected.

Copy the file to another computer. Use the same appId and the same email to reach the same project.

Full example

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Family Expenses</title>
</head>
<body>
  <h1>Family Expenses</h1>
  <div id="status">Disconnected</div>

  <form id="form">
    <input id="date" type="date" required>
    <input id="concept" placeholder="Concept" required>
    <input id="amount" type="number" step="0.01" required>
    <button type="submit">Add</button>
  </form>

  <ul id="list"></ul>

  <footer>
    <span>Persistent data with <a href="https://iavica.com">IAVICA</a></span>
    <button id="logout" type="button">Log out</button>
  </footer>

  <script src="https://iavica.com/sdk/iavica.js"></script>
  <script>
    const db = Iavica.connect({
      appId: 'YOUR_STABLE_APP_ID',
      appName: 'Family Expenses',
      locale: 'en'
    });
    const expenses = db.collection('gastos');
    const status = document.getElementById('status');

    async function refresh() {
      const page = await expenses.list({ limit: 50 });
      const list = document.getElementById('list');
      list.innerHTML = '';
      for (const record of page.items) {
        const li = document.createElement('li');
        li.textContent = `${record.data.date} · ${record.data.concept} · ${record.data.amountCents / 100}`;
        list.appendChild(li);
      }
    }

    document.getElementById('form').addEventListener('submit', async (event) => {
      event.preventDefault();
      await expenses.add({
        date: document.getElementById('date').value,
        concept: document.getElementById('concept').value,
        amountCents: Math.round(Number(document.getElementById('amount').value) * 100)
      });
      event.target.reset();
      await refresh();
    });

    document.getElementById('logout').addEventListener('click', async () => {
      await db.logout();
      location.reload();
    });

    db.on('status', (value) => { status.textContent = value; });
    await db.ready();
    await refresh();
  </script>
</body>
</html>

Next steps