convex_flutter 1.0.2

A Flutter package for Convex backend integration, enabling developers to interact with Convex services, manage data, and build applications with real-time synchronization.

Convex Flutter

A Flutter package that provides a seamless way to connect your Flutter applications to a Convex backend database using Rust-based Foreign Function Interface (FFI). This package enables developers to perform queries, mutations, actions, and real-time subscriptions with a Convex backend service.

Features

• Singleton Client: Ensures a single instance of the Convex client for efficient resource management.
• Query Execution: Retrieve data from your Convex backend with ease.
• Mutations: Perform updates or changes to your Convex database.
• Actions: Execute custom server-side logic on your Convex backend.
• Real-Time Subscriptions: Subscribe to live updates from your Convex database.
• Authentication: Set authentication tokens for secure communication.
• Rust-Powered: Leverages Rust for high-performance communication with the Convex backend.

Installation

Add the package to your pubspec.yaml:

dependencies:
  convex_flutter: ^1.0.2 # Replace with the actual version

copied to clipboard

Usage

Initialize the Client

First, initialize the ConvexClient with your Convex deployment URL and a unique client ID:

final client = await ConvexClient.init(
  deploymentUrl: 'https://your-convex-deployment.com',
  clientId: 'your-unique-client-id',
);

copied to clipboard

Query the Backend

Use the query method to retrieve data from your Convex backend:

final client = ConvexClient.instance;
final result = await client.query(
  "messages:list",
  {"limit": "10"},
);
print("Query Result: $result");

copied to clipboard

Mutate the Backend

Perform updates or changes to your Convex database using the mutation method:

await client.mutation(
  "messages:send",
  {"body": "Hello, Convex!", "author": "Flutter Developer"},
);

copied to clipboard

Execute Actions

Execute custom server-side logic using the action method:

await client.action(
  "messages:send",
  {"body": "Hello, Convex!", "author": "Flutter Developer"},
);

copied to clipboard

Real-Time Subscriptions

Subscribe to live updates from your Convex database using the subscribe method:

final subscription = await client.subscribe(
  "messages:list",
  {"limit": "10"},
  onUpdate: (data) {
    print("Subscription Update: $data");
  },
  onError: (error) {
    print("Subscription Error: $error");
  },
);

copied to clipboard

Authentication

Set an authentication token for secure communication:

await client.setAuth(token: 'your-auth-token');

copied to clipboard

Cancelling Subscriptions

Cancel an active subscription using the provided subscription handle:

client.cancelSubscription(subscription);

copied to clipboard

Example: Chat Application Below is a complete example of a simple chat application using convex_flutter:

import 'dart:convert';
import 'package:convex_flutter/convex_flutter.dart';
import 'package:flutter/material.dart';

late ConvexClient convexClient;

Future<void> main() async {
  convexClient = await ConvexClient.init(
    deploymentUrl: "https://your-app.convex.cloud",
    clientId: "flutter-app-1.0",
  );
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  TextEditingController messageController = TextEditingController();
  ArcSubscriptionHandle? subscriptionHandle;
  List<Map<String, dynamic>> messages = [];

  @override
  void initState() {
    super.initState();
    _subscribeToMessages();
  }

  Future<void> _subscribeToMessages() async {
    subscriptionHandle = await convexClient.subscribe(
      name: "messages:list",
      args: {},
      onUpdate: (value) {
        final List<dynamic> jsonList = jsonDecode(value);
        setState(() {
          messages = jsonList.map((e) => e as Map<String, dynamic>).toList();
        });
      },
      onError: (message, value) {
        print("Subscription Error: $message");
      },
    );
  }

  Future<void> _sendMessage(String text) async {
    await convexClient.mutation(
      name: "messages:send",
      args: {"body": text, "author": "FlutterUser"},
    );
    messageController.clear();
  }

  @override
  void dispose() {
    if (subscriptionHandle != null) convexClient.cancelSubscription(subscriptionHandle!);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text("Convex Chat")),
        body: Column(
          children: [
            Expanded(
              child: ListView.builder(
                itemCount: messages.length,
                itemBuilder: (context, index) {
                  final msg = messages[index];
                  return ListTile(
                    title: Text(msg["body"]),
                    subtitle: Text("By: ${msg["author"]}"),
                  );
                },
              ),
            ),
            Padding(
              padding: const EdgeInsets.all(8.0),
              child: Row(
                children: [
                  Expanded(
                    child: TextField(
                      controller: messageController,
                      decoration: const InputDecoration(hintText: "Type a message..."),
                    ),
                  ),
                  IconButton(
                    icon: const Icon(Icons.send),
                    onPressed: () => _sendMessage(messageController.text),
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }
}

copied to clipboard

Prerequisites

• Flutter: Ensure you have Flutter installed and configured.
• Convex Backend: Set up a Convex deployment and define your query, mutation, and action functions.
• Rust: Required only for development or modification of the Rust FFI layer.

Contributing

Contributions are welcome! Please fork the repository, make your changes, and submit a pull request. Ensure your code follows Dart and Rust conventions.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m "Add your feature")
4. Push to the branch (git push origin feature/your-feature)
5. Open a pull request

License

This package is licensed under the MIT License. See the LICENSE file for details.

copied to clipboard