From fb786edfe7edb1d95fee1e1ea71bc1a8f0158cda Mon Sep 17 00:00:00 2001 From: Christoph Pader Date: Thu, 22 Oct 2026 19:12:12 +0100 Subject: [PATCH] docs: document the Nitro V1 setup Update the installation steps, the iOS configuration page and the encryption guide for Nitro V1 and Swift Package Manager, including the nitroSQLite.iosSqliteFlags setting and the manifest cache that applies package.json changes only after it's cleared. Co-Authored-By: Claude Opus 5.5 --- README.md | 5 +-- docs/content/docs/configuration/index.mdx | 2 +- docs/content/docs/configuration/ios.mdx | 33 ++++++++++--------- docs/content/docs/guides/encryption.mdx | 14 ++++++-- .../docs/guides/migrate-from-quick-sqlite.mdx | 6 ++-- docs/content/docs/index.mdx | 10 +++--- .../react-native-nitro-sqlite-vec/README.md | 8 ++--- 7 files changed, 47 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index c3cf2332..fe810023 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,11 @@ If you use a coding agent, give it the [NitroSQLite skill](https://github.com/ma ## Installation -Requires React Native 0.75 or newer and `react-native-nitro-modules` 0.37.1 or newer. +Requires React Native 0.88 or newer and Nitro V1. iOS builds use Swift Package Manager and require Xcode with Swift 6.4 or newer. ```sh -npm install react-native-nitro-sqlite react-native-nitro-modules +npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041 +npx react-native spm ``` Rebuild the native app after installing. Expo projects need a development build; Expo Go cannot load this native module. See [Getting Started](https://sqlite.margelo.com/docs) for details. diff --git a/docs/content/docs/configuration/index.mdx b/docs/content/docs/configuration/index.mdx index 736bb5d5..2a19449f 100644 --- a/docs/content/docs/configuration/index.mdx +++ b/docs/content/docs/configuration/index.mdx @@ -15,7 +15,7 @@ Add the options you want to change to your app's `package.json`. These are the d } ``` -All values are booleans. Rebuild your app after changes; on Apple platforms, install Pods again first. +All values are booleans. Rebuild your app after changes. On iOS, Swift Package Manager caches the package manifest that reads these settings, so delete `~/Library/Caches/org.swift.swiftpm/manifests` before rebuilding. On macOS, install Pods again first. ## Thread safety diff --git a/docs/content/docs/configuration/ios.mdx b/docs/content/docs/configuration/ios.mdx index 9d852af4..6a3a4a65 100644 --- a/docs/content/docs/configuration/ios.mdx +++ b/docs/content/docs/configuration/ios.mdx @@ -1,6 +1,6 @@ --- title: iOS -description: Database storage, app groups, and CocoaPods overrides. +description: Database storage, app groups, and Swift Package Manager build options. --- @@ -29,35 +29,38 @@ Enable the App Groups capability for your app and extension, then add the group The group container takes precedence over the database location setting. An invalid or inaccessible container causes initialization to throw. +## Build settings + +Swift Package Manager reads the SQLite build settings when it resolves Nitro SQLite's package, and it caches the result. Changed environment variables are picked up automatically, but changes to [`package.json` settings](/docs/configuration) are not. After changing them, delete `~/Library/Caches/org.swift.swiftpm/manifests` and rebuild. + ## Bundled or system SQLite -To use system SQLite instead of the bundled library, install Pods with `NITRO_SQLITE_USE_PHONE_VERSION=1`. The shared build settings cannot change system SQLite's capabilities. +To use system SQLite instead of the bundled library, set `NITRO_SQLITE_USE_PHONE_VERSION=1` in the environment of the command that builds the app, for example `NITRO_SQLITE_USE_PHONE_VERSION=1 npx react-native run-ios`. Builds started from the Xcode app do not read your shell environment. The shared build settings cannot change system SQLite's capabilities. ## Thread safety and performance mode -For one Pod installation, `NITRO_SQLITE_THREADSAFE` and `NITRO_SQLITE_PERFORMANCE_MODE` override the corresponding [`package.json` settings](/docs/configuration). Both accept `true`, `false`, `1`, or `0`. +When set in the environment of the command that builds the app, `NITRO_SQLITE_THREADSAFE` and `NITRO_SQLITE_PERFORMANCE_MODE` override the corresponding [`package.json` settings](/docs/configuration). Both accept `true`, `false`, `1`, or `0`. ## Additional compile flags -To enable FTS5 full-text search, add this inside your existing `post_install` block in `ios/Podfile`: +Use `iosSqliteFlags` in your app's `package.json` for additional SQLite features or to override individual build defaults. For example, to enable FTS5 full-text search: -```ruby -installer.pods_project.targets.each do |target| - next unless target.name == 'RNNitroSQLite' - - target.build_configurations.each do |config| - definitions = Array(config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || '$(inherited)') - config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = definitions + ['SQLITE_ENABLE_FTS5=1'] - end -end +```json +{ + "nitroSQLite": { + "iosSqliteFlags": "-DSQLITE_ENABLE_FTS5=1" + } +} ``` +The value accepts only `-DNAME` and `-DNAME=VALUE` definitions, separated by spaces. Custom definitions take precedence over the defaults from your other `package.json` settings. + ## Vector search -Install `react-native-nitro-sqlite-vec`, then run: +Install `react-native-nitro-sqlite-vec`, then refresh the Swift packages from your app directory: ```sh -NITRO_SQLITE_VEC=1 npx pod-install +npx react-native spm ``` Rebuild and follow the [vector search guide](/docs/integrations/vector-search). For SEE build settings, see [encryption](/docs/guides/encryption). diff --git a/docs/content/docs/guides/encryption.mdx b/docs/content/docs/guides/encryption.mdx index 82b63e77..d2a55edd 100644 --- a/docs/content/docs/guides/encryption.mdx +++ b/docs/content/docs/guides/encryption.mdx @@ -22,7 +22,17 @@ Pass `encryptionKey` to `open()` to use an encrypted database. This requires a n nitroSqliteFlags="-DSQLITE_ENABLE_SEE=1" ``` - On Apple platforms, add the definition to the `RNNitroSQLite` target inside your existing Podfile `post_install` block: + On iOS, set this in your app's `package.json`: + + ```json + { + "nitroSQLite": { + "iosSqliteFlags": "-DSQLITE_ENABLE_SEE=1" + } + } + ``` + + On macOS, add the definition to the `RNNitroSQLite` target inside your existing Podfile `post_install` block: ```ruby installer.pods_project.targets.each do |target| @@ -35,7 +45,7 @@ Pass `encryptionKey` to `open()` to use an encrypted database. This requires a n end ``` - Use the bundled SQLite build on Apple platforms. `NITRO_SQLITE_USE_PHONE_VERSION=1` links the system SQLite library, which does not include your SEE source. Install Pods again and rebuild the native app after changing the source or flags. See [iOS configuration](/docs/configuration/ios#additional-compile-flags) and [Android configuration](/docs/configuration/android#sqlite-compile-flags) for the platform build settings. + Use the bundled SQLite build on Apple platforms. `NITRO_SQLITE_USE_PHONE_VERSION=1` links the system SQLite library, which does not include your SEE source. Rebuild the native app after changing the source or flags. On iOS, delete `~/Library/Caches/org.swift.swiftpm/manifests` first, so Swift Package Manager reads the new flags. On macOS, install Pods again first. See [iOS configuration](/docs/configuration/ios#additional-compile-flags) and [Android configuration](/docs/configuration/android#sqlite-compile-flags) for the platform build settings. ## Open an encrypted database diff --git a/docs/content/docs/guides/migrate-from-quick-sqlite.mdx b/docs/content/docs/guides/migrate-from-quick-sqlite.mdx index 8c1d67c3..e523785a 100644 --- a/docs/content/docs/guides/migrate-from-quick-sqlite.mdx +++ b/docs/content/docs/guides/migrate-from-quick-sqlite.mdx @@ -9,10 +9,12 @@ description: Move from react-native-quick-sqlite 8.x to the Nitro SQLite 9.x pac ```sh npm uninstall react-native-quick-sqlite -npm install react-native-nitro-sqlite react-native-nitro-modules -npx pod-install +npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041 +npx react-native spm ``` +See [Getting Started](/docs) for the platform requirements and the Swift Package Manager setup on iOS. + ## Update calls to use a connection The recommended 9.x API is the connection returned by `open()`. It binds the database name once, so query calls on that connection no longer pass the name each time: diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx index 73e68616..fe4dfca8 100644 --- a/docs/content/docs/index.mdx +++ b/docs/content/docs/index.mdx @@ -7,21 +7,21 @@ Nitro SQLite gives React Native apps a local SQLite database on iOS, macOS, visi ## 1. Install the packages -Nitro SQLite requires React Native 0.75 or newer, React 17 or newer, and `react-native-nitro-modules` 0.37.1 or newer. +Nitro SQLite is built with Nitro V1, which requires React Native 0.88 or newer with the New Architecture. iOS builds require Xcode with Swift 6.4 or newer. Install the Nitro version that Nitro SQLite was built with, because the generated native bindings must match it: ```sh -npm install react-native-nitro-sqlite react-native-nitro-modules +npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041 ``` ## 2. Set up the native project -The default database location needs no custom SQLite settings. If your project has an `ios` directory, install the native pods after adding the packages: +The default database location needs no custom SQLite settings. Nitro V1 builds iOS dependencies with Swift Package Manager. If your project has an `ios` directory, set up or refresh the Swift packages from your app directory after adding the packages: ```sh -npx pod-install +npx react-native spm ``` -Android needs no additional Nitro SQLite configuration for the default setup. For a React Native macOS project, install CocoaPods from its `macos` directory. Use [Configuration](/docs/configuration) for the shared `package.json` options. The [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), and [macOS](/docs/configuration/macos) pages cover platform settings and build alternatives. +If your iOS project still uses CocoaPods, convert it first with `npx react-native spm add --deintegrate`. Android needs no additional Nitro SQLite configuration for the default setup. For a React Native macOS project, install CocoaPods from its `macos` directory. Use [Configuration](/docs/configuration) for the shared `package.json` options. The [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), and [macOS](/docs/configuration/macos) pages cover platform settings and build alternatives. ## 3. Rebuild the app diff --git a/packages/react-native-nitro-sqlite-vec/README.md b/packages/react-native-nitro-sqlite-vec/README.md index d1487a74..60d1edac 100644 --- a/packages/react-native-nitro-sqlite-vec/README.md +++ b/packages/react-native-nitro-sqlite-vec/README.md @@ -4,17 +4,17 @@ Opt-in [sqlite-vec](https://github.com/asg017/sqlite-vec) support for [`react-na ## Installation -Install both this package and `react-native-nitro-sqlite`, then enable the native build flag. +Install both this package and `react-native-nitro-sqlite`, then enable it in the native build. ```bash npm install react-native-nitro-sqlite react-native-nitro-sqlite-vec ``` -- **Apple platforms (iOS, macOS, visionOS):** +- **iOS:** refresh the Swift packages from your app directory: ```bash - NITRO_SQLITE_VEC=1 npx pod-install + npx react-native spm ``` - For React Native macOS, run `NITRO_SQLITE_VEC=1 pod install` from `macos/`. +- **macOS:** run `NITRO_SQLITE_VEC=1 pod install` from `macos/`. - **Android:** add this to `android/gradle.properties` and rebuild: ```properties nitroSqliteVec=true