Skip to content

Commit d52fd6c

Browse files
chrispaderclaude
andcommitted
docs: document the Nitro V1 setup
Update the requirements and install steps for React Native 0.88, Nitro V1 and Swift Package Manager, replace the Podfile examples with iosSqliteFlags, and note that React Native macOS is not supported. The API reference tooling now recognizes Nitro V1 hybrid objects. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent dfa9964 commit d52fd6c

14 files changed

Lines changed: 60 additions & 76 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,10 @@ To run the example app on Android:
2424
bun example android
2525
```
2626

27-
To run the example app on iOS:
27+
To run the example app on iOS, generate its Swift packages first. Run this again after changing native dependencies:
2828

2929
```sh
30+
bun example spm
3031
bun example ios
3132
```
3233

@@ -49,7 +50,7 @@ Remember to add tests for your change if possible. Run the unit tests by:
4950
bun test
5051
```
5152

52-
To edit the Objective-C files, open `example/ios/SequelExample.xcworkspace` in XCode and find the source files at `Pods > Development Pods > react-native-nitro-sqlite`.
53+
To edit the Objective-C++ and C++ files, open `example/ios/NitroSQLiteExample.xcodeproj` in Xcode and find the source files in the `RNNitroSQLite` package.
5354

5455
To edit the Kotlin files, open `example/android` in Android studio and find the source files at `rnnitrosqlite` under `Android`.
5556

‎README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,21 @@
88

99
<br />
1010

11-
Nitro SQLite is a SQLite library for React Native on iOS, macOS, visionOS, and Android, built with [Nitro Modules](https://nitro.margelo.com/). It provides synchronous and asynchronous queries, transactions, and batch operations.
11+
Nitro SQLite is a SQLite library for React Native on iOS and Android, built with [Nitro Modules](https://nitro.margelo.com/). It provides synchronous and asynchronous queries, transactions, and batch operations.
1212

13-
The bundled SQLite build enables [R\*Tree indexes](https://sqlite.margelo.com/docs/concepts/queries-and-indexes#query-spatial-ranges) by default on Apple platforms and Android. Set `nitroSQLite.enableRTree` to `false` in your app's `package.json` to omit it from the native build.
13+
The bundled SQLite build enables [R\*Tree indexes](https://sqlite.margelo.com/docs/concepts/queries-and-indexes#query-spatial-ranges) by default on iOS and Android. Set `nitroSQLite.enableRTree` to `false` in your app's `package.json` to omit it from the native build.
1414

1515
**[Read the documentation](https://sqlite.margelo.com/docs)** for setup, guides, integrations, and the API reference.
1616

1717
If you use a coding agent, give it the [NitroSQLite skill](https://github.com/margelo/react-native-skills/blob/nitro-sqlite/skills/react-native-nitro-sqlite/SKILL.md). It links to focused guidance for connections, queries, transactions, concurrency, and migration. See the [AI agent guide](https://sqlite.margelo.com/docs/guides/ai-agents) for what to check in generated code.
1818

1919
## Installation
2020

21-
Requires React Native 0.75 or newer and `react-native-nitro-modules` 0.37.1 or newer.
21+
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.
2222

2323
```sh
24-
npm install react-native-nitro-sqlite react-native-nitro-modules
24+
npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041
25+
npx react-native spm
2526
```
2627

2728
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.

‎docs/content/docs/configuration/index.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Configuration
33
description: Shared SQLite settings in package.json.
44
---
55

6-
Add the options you want to change to your app's `package.json`. These are the defaults for bundled SQLite on iOS, Android, macOS, and visionOS:
6+
Add the options you want to change to your app's `package.json`. These are the defaults for bundled SQLite on iOS and Android:
77

88
```json
99
{
@@ -15,7 +15,7 @@ Add the options you want to change to your app's `package.json`. These are the d
1515
}
1616
```
1717

18-
All values are booleans. Rebuild your app after changes; on Apple platforms, install Pods again first.
18+
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.
1919

2020
## Thread safety
2121

@@ -33,4 +33,4 @@ WAL databases default to `synchronous = NORMAL`, which can lose recent commits a
3333

3434
When supplying custom flags, omit `SQLITE_ENABLE_RTREE` to disable it. Defining it as `0` still enables the module.
3535

36-
For platform settings and alternative build flags, see [iOS](/docs/configuration/ios), [Android](/docs/configuration/android), or [macOS](/docs/configuration/macos).
36+
For platform settings and alternative build flags, see [iOS](/docs/configuration/ios) or [Android](/docs/configuration/android).

‎docs/content/docs/configuration/ios.mdx‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: iOS
3-
description: Database storage, app groups, and CocoaPods overrides.
3+
description: Database storage, app groups, and Swift Package Manager build options.
44
---
55

66
<span id="rtree-support" />
@@ -29,35 +29,38 @@ Enable the App Groups capability for your app and extension, then add the group
2929

3030
The group container takes precedence over the database location setting. An invalid or inaccessible container causes initialization to throw.
3131

32+
## Build settings
33+
34+
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.
35+
3236
## Bundled or system SQLite
3337

34-
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.
38+
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.
3539

3640
## Thread safety and performance mode
3741

38-
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`.
42+
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`.
3943

4044
## Additional compile flags
4145

42-
To enable FTS5 full-text search, add this inside your existing `post_install` block in `ios/Podfile`:
46+
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:
4347

44-
```ruby
45-
installer.pods_project.targets.each do |target|
46-
next unless target.name == 'RNNitroSQLite'
47-
48-
target.build_configurations.each do |config|
49-
definitions = Array(config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || '$(inherited)')
50-
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = definitions + ['SQLITE_ENABLE_FTS5=1']
51-
end
52-
end
48+
```json
49+
{
50+
"nitroSQLite": {
51+
"iosSqliteFlags": "-DSQLITE_ENABLE_FTS5=1"
52+
}
53+
}
5354
```
5455

56+
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.
57+
5558
## Vector search
5659

57-
Install `react-native-nitro-sqlite-vec`, then run:
60+
Install `react-native-nitro-sqlite-vec`, then refresh the Swift packages from your app directory:
5861

5962
```sh
60-
NITRO_SQLITE_VEC=1 npx pod-install
63+
npx react-native spm
6164
```
6265

6366
Rebuild and follow the [vector search guide](/docs/integrations/vector-search). For SEE build settings, see [encryption](/docs/guides/encryption).
Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,6 @@
11
---
22
title: macOS
3-
description: Installation, database storage, and Apple build options.
3+
description: React Native macOS support.
44
---
55

6-
Use [Configuration](/docs/configuration) for shared `package.json` settings. Install `react-native-nitro-sqlite` and `react-native-nitro-modules`, then install Pods and rebuild:
7-
8-
```sh
9-
cd macos && pod install
10-
```
11-
12-
Databases use an app-specific Application Support directory. See [file locations](/docs/guides/database-lifecycle#file-location-and-prepopulated-databases) for the `location` option. Sandboxed apps can access only their permitted containers.
13-
14-
## Apple build options
15-
16-
Use the [iOS build options](/docs/configuration/ios#bundled-or-system-sqlite), running CocoaPods from `macos`.
17-
18-
For vector search, install `react-native-nitro-sqlite-vec` and run `NITRO_SQLITE_VEC=1 pod install` from `macos`. Rebuild and follow the [vector search guide](/docs/integrations/vector-search).
19-
20-
## Run the example
21-
22-
The repository example requires macOS 14 or later. Install its workspace and Ruby dependencies, then run the `pods:macos` and `macos` scripts. To run Metro separately, use the `start` script and pass `--no-packager` to `macos`. For a release build, pass `--mode Release --no-packager`.
6+
This version of Nitro SQLite is built with Nitro V1, which does not support React Native macOS. Use Nitro SQLite 10 for macOS apps.

‎docs/content/docs/guides/database-lifecycle.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Only pass database names and locations you control. The library does not validat
4747

4848
To open a prepopulated database, copy the SQLite file into the intended app directory before calling `open()`. Use the same `name` and `location` when you open it. A missing file creates a new, empty database, so verify the copy if your schema must already exist. See [file lifetimes](/docs/concepts/databases-and-connections#file-lifetimes) for WAL companion files.
4949

50-
The platform pages describe the database roots and storage settings for [iOS](/docs/configuration/ios#database-location), [Android](/docs/configuration/android#database-location), and [macOS](/docs/configuration/macos). The generated [`NitroSQLiteConnection` reference](/api/react-native-nitro-sqlite/interfaces/NitroSQLiteConnection) lists the lifecycle methods.
50+
The platform pages describe the database roots and storage settings for [iOS](/docs/configuration/ios#database-location) and [Android](/docs/configuration/android#database-location). The generated [`NitroSQLiteConnection` reference](/api/react-native-nitro-sqlite/interfaces/NitroSQLiteConnection) lists the lifecycle methods.
5151

5252
## Runtime teardown
5353

‎docs/content/docs/guides/encryption.mdx‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,20 +22,17 @@ Pass `encryptionKey` to `open()` to use an encrypted database. This requires a n
2222
nitroSqliteFlags="-DSQLITE_ENABLE_SEE=1"
2323
```
2424

25-
On Apple platforms, add the definition to the `RNNitroSQLite` target inside your existing Podfile `post_install` block:
26-
27-
```ruby
28-
installer.pods_project.targets.each do |target|
29-
next unless target.name == 'RNNitroSQLite'
30-
31-
target.build_configurations.each do |config|
32-
definitions = Array(config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || '$(inherited)')
33-
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = definitions + ['SQLITE_ENABLE_SEE=1']
34-
end
35-
end
25+
On iOS, set this in your app's `package.json`:
26+
27+
```json
28+
{
29+
"nitroSQLite": {
30+
"iosSqliteFlags": "-DSQLITE_ENABLE_SEE=1"
31+
}
32+
}
3633
```
3734

38-
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.
35+
Use the bundled SQLite build on iOS. `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. See [iOS configuration](/docs/configuration/ios#additional-compile-flags) and [Android configuration](/docs/configuration/android#sqlite-compile-flags) for the platform build settings.
3936

4037
## Open an encrypted database
4138

‎docs/content/docs/guides/migrate-from-quick-sqlite.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ description: Move from react-native-quick-sqlite 8.x to the Nitro SQLite 9.x pac
99

1010
```sh
1111
npm uninstall react-native-quick-sqlite
12-
npm install react-native-nitro-sqlite react-native-nitro-modules
13-
npx pod-install
12+
npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041
13+
npx react-native spm
1414
```
1515

16+
See [Getting Started](/docs) for the platform requirements and the Swift Package Manager setup on iOS.
17+
1618
## Update calls to use a connection
1719

1820
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:

‎docs/content/docs/index.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,25 @@ title: Getting Started
33
description: Install Nitro SQLite, rebuild your React Native app, and run your first query.
44
---
55

6-
Nitro SQLite gives React Native apps a local SQLite database on iOS, macOS, visionOS, and Android. Start by installing its native package and Nitro Modules, then open a database with `open()`.
6+
Nitro SQLite gives React Native apps a local SQLite database on iOS and Android. Start by installing its native package and Nitro Modules, then open a database with `open()`.
77

88
## 1. Install the packages
99

10-
Nitro SQLite requires React Native 0.75 or newer, React 17 or newer, and `react-native-nitro-modules` 0.37.1 or newer.
10+
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:
1111

1212
```sh
13-
npm install react-native-nitro-sqlite react-native-nitro-modules
13+
npm install react-native-nitro-sqlite react-native-nitro-modules@1.0.0-alpha.nightly.86.g15e19db42041
1414
```
1515

1616
## 2. Set up the native project
1717

18-
The default database location needs no custom SQLite settings. If your project has an `ios` directory, install the native pods after adding the packages:
18+
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:
1919

2020
```sh
21-
npx pod-install
21+
npx react-native spm
2222
```
2323

24-
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.
24+
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. Use [Configuration](/docs/configuration) for the shared `package.json` options. The [iOS](/docs/configuration/ios) and [Android](/docs/configuration/android) pages cover platform settings and build alternatives.
2525

2626
## 3. Rebuild the app
2727

‎docs/content/docs/integrations/vector-search.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Use `createVectorTable()` and `knnSearch()` from `react-native-nitro-sqlite-vec`
77

88
## Enable vector search
99

10-
Install `react-native-nitro-sqlite-vec` alongside `react-native-nitro-sqlite`. Enable it for each platform you ship using the [iOS](/docs/configuration/ios#vector-search), [macOS](/docs/configuration/macos#apple-build-options), or [Android](/docs/configuration/android#vector-search) configuration page, then rebuild the native app. Check availability with `isVecAvailable(db)` before running vector queries. A JavaScript update alone cannot enable the extension.
10+
Install `react-native-nitro-sqlite-vec` alongside `react-native-nitro-sqlite`. Enable it for each platform you ship using the [iOS](/docs/configuration/ios#vector-search) or [Android](/docs/configuration/android#vector-search) configuration page, then rebuild the native app. Check availability with `isVecAvailable(db)` before running vector queries. A JavaScript update alone cannot enable the extension.
1111

1212
## Create and search a vector table
1313

0 commit comments

Comments
 (0)