Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Projects and Practice

Project: Notes App with Offline Sync

Build a notes app with Ionic and Capacitor: data model, store, local persistence, an outbox for sync, search and a clean page structure, with runnable core logic.

In this project you plan and build a notes app that works offline. It uses ideas from the whole course: pages and navigation, forms, a shared store, local storage and a sync queue. You will write the core logic in a form you can run here, and see the real Ionic page code that sits on top of it.

The goal is not a pile of code but a structure you can reuse: the UI stays thin and the logic lives in small testable pieces, as recommended in Unit Testing Ionic Components and Services.

Requirements

  1. List notes, newest first, with a search box.
  2. Create, edit, pin and delete notes.
  3. Everything works offline; changes sync when the network returns.
  4. The list shows a small "pending" mark for unsynced notes.
  5. Settings (theme) persist across restarts.

Architecture

flowchart TD
  P1["NotesPage<br/>(list and search)"] --> S["NotesStore"]
  P2["NoteEditPage<br/>(form)"] --> S
  S --> R["NotesRepository<br/>(SQLite / Preferences)"]
  S --> Q["Outbox"]
  Q --> A["Api client"]
  N["Network plugin"] --> Q

Pages only talk to the store. The store talks to the repository and outbox. Plugins hide behind small interfaces.

Folder layout:

TEXT
src/app/
  notes/
    notes.page.ts       # list, search, pull-to-refresh
    note-edit.page.ts   # form
    notes.store.ts      # signals, actions
    notes.repository.ts # SQLite or Preferences
    sync.service.ts     # outbox and network listener
    note.model.ts

Step 1: the model and the store logic

The note has an id created on the device, so it can exist before the server knows it. updatedAt helps sorting and conflicts, and pending marks unsynced changes.

JS Notes store: add, edit, pin, search

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 2: the repository

The repository hides how data is saved. The store calls load() and save(); the first version can use Preferences, and a later one can switch to SQLite without touching the pages.

TypeScript
export interface NotesRepository {
  load(): Promise<Note[]>;
  save(notes: Note[]): Promise<void>;
}

export class PreferencesNotesRepository implements NotesRepository {
  private static readonly KEY = 'notes.v1';
  async load() {
    const { value } = await Preferences.get({ key: PreferencesNotesRepository.KEY });
    return value ? (JSON.parse(value) as Note[]) : [];
  }
  async save(notes: Note[]) {
    await Preferences.set({ key: PreferencesNotesRepository.KEY, value: JSON.stringify(notes) });
  }
}

The key has a version suffix (v1) so a later format change can migrate old data. If notes grow beyond a few hundred, move to SQLite as in Storage, Preferences and SQLite.

Step 3: sync service

Each local change becomes an outbox operation. When the network is up the service sends them in order and clears the pending flag of successful notes. This is the idea from Offline First and Sync, applied to the notes model.

JS Persist then sync, with a flaky network

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 4: the pages

The list page reads from the store and calls actions. In Ionic Angular with signals:

TypeScript
@Component({
  standalone: true,
  imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonSearchbar, IonList, IonItem,
            IonLabel, IonItemSliding, IonItemOptions, IonItemOption, IonFab, IonFabButton, IonIcon, IonBadge],
  template: `
    <ion-header><ion-toolbar><ion-title>Notes</ion-title></ion-toolbar>
      <ion-toolbar><ion-searchbar (ionInput)="query.set($event.detail.value ?? '')" /></ion-toolbar>
    </ion-header>
    <ion-content>
      <ion-list>
        @for (note of store.list(query()); track note.id) {
          <ion-item-sliding>
            <ion-item [routerLink]="['/notes', note.id]">
              <ion-label>{{ note.title }}</ion-label>
              @if (note.pending) { <ion-badge slot="end" color="medium">pending</ion-badge> }
            </ion-item>
            <ion-item-options side="end">
              <ion-item-option color="danger" (click)="store.remove(note.id)">Delete</ion-item-option>
            </ion-item-options>
          </ion-item-sliding>
        }
      </ion-list>
      <ion-fab slot="fixed" vertical="bottom" horizontal="end">
        <ion-fab-button routerLink="/notes/new"><ion-icon name="add" /></ion-fab-button>
      </ion-fab>
    </ion-content>`,
})
export class NotesPage {
  store = inject(NotesStore);
  query = signal('');
}

The edit page uses a reactive form with title required (see the forms chapter) and calls store.add or store.update, then navigates back. Because the store is shared and pages stay alive, the list updates by itself.

Step 5: finishing touches

  • Persist the theme with Preferences and apply it on startup before the first render.
  • Show an offline chip using the Network plugin and trigger sync() on networkStatusChange.
  • Add haptic feedback on delete and pin.
  • Write unit tests for the store and the sync service; one end-to-end test for "add a note offline, go online, see no pending mark".
  • Prepare icons and permission texts (no sensitive permissions are needed here, which is a plus in review).

Stretch goals

  1. Replace Preferences with SQLite and add a migration that adds a color column.
  2. Add a conflict rule: if the server version is newer, keep both and mark the note.
  3. Export all notes as a text file with the Filesystem plugin and the share sheet.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a new note get its id on the device?

    Client-side ids let offline items exist and be referenced immediately.
  2. 2. What is the job of the repository layer?

    Swapping Preferences for SQLite should not affect pages or the store.
  3. 3. Why keep the outbox operation until the request succeeds?

    Removing it only after success means a failure leaves the change queued for retry.
  4. 4. Where should sorting and filtering logic live?

    Pure logic outside the template is reusable and simple to test.

Summary

  • Separate pages, store, repository and sync service.
  • Local first: save, then queue, then sync.
  • Mark pending items and keep the outbox in order.
  • Test the logic without the UI; add one end-to-end test for the offline flow.

Next: Project: Photo Journal