> ## Documentation Index
> Fetch the complete documentation index at: https://cindel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Cindel in a Flutter or Dart Project — Setup

> Add Cindel's four packages to your Flutter project, configure build_runner, and choose between MDBX and SQLite native backends for local storage.

Setting up Cindel requires four packages, a one-time code-generation step, and — optionally — a backend selection for native platforms. This page covers each piece in detail so your project is configured correctly before you write any model code.

## The four packages

Cindel is split across four packages, each with a distinct role:

| Package               | Type                   | Purpose                                                                                            |
| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| `cindel`              | `dependencies`         | Runtime library — database API, annotations, query types, transaction helpers, and watcher streams |
| `cindel_flutter_libs` | `dependencies`         | Native binaries for all Flutter platforms, plus the SQLite Worker and Wasm assets for Flutter Web  |
| `cindel_generator`    | `dev_dependencies`     | Code generator — run by `build_runner` to produce schemas, collection getters, and query helpers   |
| `cindel_annotations`  | Pulled in transitively | Annotation types (`@Collection`, `@Index`, `@embedded`, etc.) — no need to add this explicitly     |

You do not need to add `cindel_annotations` directly to your `pubspec.yaml`. It is pulled in transitively by `cindel`. Import it in model files with `package:cindel_annotations/cindel_annotations.dart` if you prefer a minimal import, or use `package:cindel/cindel.dart` which re-exports everything you need.

## pubspec.yaml

Add the following to your `pubspec.yaml`, then run `flutter pub get`:

```yaml pubspec.yaml theme={null}
dependencies:
  cindel: ^1.0.0
  cindel_flutter_libs: ^1.0.0

dev_dependencies:
  build_runner: ^2.15.0
  cindel_generator: ^1.0.0
```

<Note>
  Every model file that Cindel should generate code for must include a `part` directive pointing to the generated file. For a model defined in `todo.dart`, add the following line directly below your imports:

  ```dart theme={null}
  part 'todo.g.dart';
  ```

  Without this directive, `build_runner` cannot attach the generated schema, collection getter, and query helpers to your model class.
</Note>

## Running the code generator

Run the generator once before you first open a database, and again after any model change:

```bash theme={null}
dart run build_runner build
```

During active development, keep the generator watching for changes so generated files stay in sync automatically:

```bash theme={null}
dart run build_runner watch
```

The generator produces a `*.g.dart` file next to each annotated model. These files contain:

* a schema constant (e.g. `TodoSchema`) to pass to `Cindel.open`,
* a typed collection getter (e.g. `db.todos`) on the database handle,
* serializers for reading and writing objects,
* typed `where()` and `filter()` query helper chains.

Never hand-edit the generated `*.g.dart` files. They are overwritten every time you run the generator.

## Choosing a backend

### MDBX (default)

MDBX is the default native backend on Android, iOS, macOS, Linux, and Windows. You do not need to pass a `backend` parameter to use it:

```dart theme={null}
final db = await Cindel.open(
  directory: dir.path,
  schemas: [TodoSchema],
);
```

MDBX is the recommended starting point for new native Flutter apps.

### SQLite native

To use the native SQLite backend instead of MDBX, pass `CindelStorageBackend.sqlite` explicitly:

```dart theme={null}
final db = await Cindel.open(
  directory: dir.path,
  schemas: [TodoSchema],
  backend: CindelStorageBackend.sqlite,
);
```

Switching between MDBX and SQLite does not change your application-level code. Generated schemas, collection getters, CRUD operations, queries, transactions, and watchers have the same shape with both backends.

### SQLite Web / OPFS (browser)

Flutter Web uses SQLite in a Worker with OPFS persistence automatically. You do not select a backend for Web — MDBX is not available in the browser and the SQLite Web runtime is loaded from `cindel_flutter_libs` assets.

On Web, pass a logical database name as the `directory` parameter instead of a filesystem path:

```dart theme={null}
final db = await Cindel.open(
  directory: 'app.db',
  schemas: [TodoSchema],
);
```

<Note>
  The `directory` value on Web is the logical browser database name, not a filesystem path. Use a stable name — changing it means opening a different browser database and any previously persisted data will not be visible to the new name.
</Note>

Keep both `cindel` and `cindel_flutter_libs` in your `dependencies` for Web apps; `cindel_flutter_libs` bundles the Worker and Wasm assets that `Cindel.open` loads at runtime in the browser.

## Platform support

Cindel supports all Flutter target platforms:

| Platform | Supported | Backend                  |
| -------- | --------- | ------------------------ |
| Android  | ✓         | MDBX (default) or SQLite |
| iOS      | ✓         | MDBX (default) or SQLite |
| macOS    | ✓         | MDBX (default) or SQLite |
| Linux    | ✓         | MDBX (default) or SQLite |
| Windows  | ✓         | MDBX (default) or SQLite |
| Web      | ✓         | SQLite / OPFS            |

Web support requires a browser context with Workers, Wasm, and OPFS available. Validate Web behavior in your target browsers, focusing on startup, asset loading, persistence after reopen, queries, transactions, and watcher behavior.

## Next steps

With packages installed and the generator configured, you are ready to define your first model and open a database:

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the step-by-step guide to annotate a model, generate code, and run your first typed query.
  </Card>

  <Card title="Data Modeling" icon="layer-group" href="/modeling/collections">
    Learn how to define collections, choose field types, add indexes, and use embedded objects.
  </Card>
</CardGroup>