Capacitor and Ionic

Electron · Tauri · Qt · Flutter · React Native · Capacitor and Ionic · .NET MAUI

Capacitor and Ionic applications use a dedicated plugin binding the native SDK on iOS and Android. It exposes the Node package’s application API with the same names. The web view calls it through the Capacitor bridge, so every call returns a promise.

The database lives in the application’s document directory, as for every other mobile SDK. It does not live in the web view’s storage. The web build uses the browser package.

Requirements

Capacitor 7 or newer. Use JDK 21 for Android builds. Use CocoaPods for iOS builds. Install CocoaPods before the iOS steps, and check it with pod --version. The Ruby that macOS includes (2.6) cannot install the current CocoaPods. Use Ruby 3.4 or newer.

Platform	Minimum version
iOS	15
Android	13 (API level 33)

What ships

The TypeScript column of the compatibility matrix, packaged for Capacitor and Ionic. Each release runs the quickstart on the platforms in this table. Other platforms have no verification for this integration.

Platform	Targets	Package
iOS and iPadOS	apple-mobile-device-arm64, apple-mobile-simulator-arm64, apple-mobile-simulator-x86_64	@potluckdb/potluckdb-capacitor
Android	android-arm64-v8a, android-x86_64	@potluckdb/potluckdb-capacitor

Install

Create a web application with Vite. Add Capacitor and the plugin. Initialize Capacitor with the app ID com.example.notes and Vite’s output directory dist. Then add the native platforms.

npm create vite@latest notes -- --template vanilla-ts --no-immediate
cd notes
npm install
npm install @capacitor/core @capacitor/android @capacitor/ios @potluckdb/potluckdb-capacitor
npm install -D @capacitor/cli
npx cap init Notes com.example.notes --web-dir dist
npx cap add android
npx cap add ios --packagemanager CocoaPods

Use CocoaPods for iOS. The plugin supplies a podspec. It supplies no Swift package. The option above selects CocoaPods in Capacitor 7 and newer.

On Android, set minSdkVersion = 33 in android/variables.gradle.

Replace android/app/src/main/java/com/example/notes/MainActivity.java with MainActivity.java from the Quickstart section. It sets POTLUCKDB_CONFIG_DIR under the application’s files directory before the bridge starts. The licensing page explains this requirement.

Quickstart

The application opens the database in the document directory the plugin reports, inserts a note and renders the table.

Replace src/main.ts with main.ts below. In index.html, replace <div id="app"></div> with <ul id="notes"></ul>. Then build the web application and copy it into the native projects.

npm run build
npx cap sync

npx cap sync copies the web build into both platform projects and registers the plugin in each.

For iOS, run npx cap run ios in the notes directory. It starts the app in the iOS Simulator. For Android, build and install only the app module on a connected device or emulator.

cd android
./gradlew :app:installDebug

Start Notes on the device. You can also run npx cap open android in the notes directory and start the app with Android Studio.

npx cap run android does not work with this plugin in potluckdb 0.1.0.

The application prints quickstart: ok in the web view’s console once the database is open.

main.ts

// potluckdb in a Capacitor application: the plugin binds the native SDK, so the database is
// a file in the application's document directory and every call crosses the bridge as a promise.

import { documentDirectory, open, Remote } from "@potluckdb/potluckdb-capacitor";

const list = document.getElementById("notes") as HTMLUListElement;

const directory = await documentDirectory();
const remote = await Remote.fromDirectory(`${directory}/remote`); // a bucket replaces this in production; see the Node installation page
const db = await open(`${directory}/notes.potluckdb`, remote);
await db.execute("CREATE TABLE IF NOT EXISTS note(id INTEGER PRIMARY KEY, body TEXT NOT NULL)");
await db.execute("INSERT INTO note(body) VALUES(?)", ["buy milk"]);
const { rows } = await db.query("SELECT id, body FROM note ORDER BY id");
for (const row of rows) {
  const item = document.createElement("li");
  item.textContent = `${row.id}: ${row.body}`;
  list.append(item);
}
console.log("quickstart: ok");

MainActivity.java

package com.example.notes;

import android.os.Bundle;
import android.system.ErrnoException;
import android.system.Os;
import android.util.Log;
import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        // The bridge starts in super.onCreate and can open the database at once.
        try {
            Os.setenv("POTLUCKDB_CONFIG_DIR", getFilesDir() + "/configuration", false);
        } catch (ErrnoException error) {
            Log.e("Notes", "could not place the configuration directory", error);
        }
        super.onCreate(savedInstanceState);
    }
}

Verified by the release

Each release verifies persisted notes in this application on the iOS simulator and Android emulator after a process restart. The iOS device, Intel simulator, and arm64-v8a Android libraries compile but do not run in these checks.