Backpack

Introduction

Backpack is an in-memory singleton storage system in Nylo Website. It provides fast, synchronous access to data during your app's runtime. Unlike NyStorage which persists data to the device, Backpack stores data in memory and is cleared when the app is closed.

Backpack is used internally by the framework to store critical instances like the Nylo app object, EventBus, and authentication data. You can also use it to store your own data that needs to be accessed quickly without async calls.

import 'package:nylo_framework/nylo_framework.dart';

// Save a value
Backpack.instance.save("user_name", "Anthony");

// Read a value (synchronous)
String? name = Backpack.instance.read("user_name");

// Delete a value
Backpack.instance.delete("user_name");

Basic Usage

Backpack uses the singleton pattern -- access it through Backpack.instance:

// Save data
Backpack.instance.save("theme", "dark");

// Read data
String? theme = Backpack.instance.read("theme"); // "dark"

// Check if data exists
bool hasTheme = Backpack.instance.contains("theme"); // true

Reading Data

Read values from Backpack using the read<T>() method. It supports generic types and an optional default value:

// Read a String
String? name = Backpack.instance.read<String>("name");

// Read with a default value
String name = Backpack.instance.read<String>("name", defaultValue: "Guest") ?? "Guest";

// Read an int
int? score = Backpack.instance.read<int>("score");

Backpack automatically deserializes JSON strings to model objects when a type is provided:

// If a User model is stored as JSON, it will be deserialized
User? user = Backpack.instance.read<User>("current_user");

Saving Data

Save values using the save() method:

Backpack.instance.save("api_token", "abc123");
Backpack.instance.save("is_premium", true);
Backpack.instance.save("cart_count", 3);

Appending Data

Use append() to add values to a list stored at a key:

// Append to a list
Backpack.instance.append("recent_searches", "Flutter");
Backpack.instance.append("recent_searches", "Dart");

// Append with a limit (keeps only the last N items)
Backpack.instance.append("recent_searches", "Nylo", limit: 10);

Deleting Data

Delete a Single Key

Backpack.instance.delete("api_token");

Delete All Data

The deleteAll() method removes all values except reserved framework keys (nylo and event_bus):

Backpack.instance.deleteAll();

Sessions

Backpack provides session management for organizing data into named groups. This is useful for storing related data together.

Update a Session Value

Backpack.instance.sessionUpdate("cart", "item_count", 3);
Backpack.instance.sessionUpdate("cart", "total", 29.99);

Get a Session Value

int? itemCount = Backpack.instance.sessionGet<int>("cart", "item_count"); // 3
double? total = Backpack.instance.sessionGet<double>("cart", "total"); // 29.99

Remove a Session Key

Backpack.instance.sessionRemove("cart", "item_count");

Flush an Entire Session

Backpack.instance.sessionFlush("cart");

Get All Session Data

Map<String, dynamic>? cartData = Backpack.instance.sessionData("cart");
// {"item_count": 3, "total": 29.99}

Accessing the Nylo Instance

Backpack stores the Nylo application instance. You can retrieve it using:

Nylo nylo = Backpack.instance.nylo();

Check if the Nylo instance has been initialized:

bool isReady = Backpack.instance.isNyloInitialized(); // true

Helper Functions

Nylo Website provides global helper functions for common Backpack operations:

Example

// Using helper functions
backpackSave("locale", "en");

String? locale = backpackRead<String>("locale"); // "en"

backpackDelete("locale");

// Access the Nylo instance
Nylo nylo = backpackNylo();

Integration with NyStorage

Backpack integrates with NyStorage for combined persistent + in-memory storage:

// Save to both NyStorage (persistent) and Backpack (in-memory)
await NyStorage.save("auth_token", "abc123", inBackpack: true);

// Now accessible synchronously via Backpack
String? token = Backpack.instance.read("auth_token");

// When deleting from NyStorage, also clear from Backpack
await NyStorage.deleteAll(andFromBackpack: true);

This pattern is useful for data like authentication tokens that need both persistence and fast synchronous access (e.g., in HTTP interceptors).

Examples

Storing Auth Tokens for API Requests

// In your auth interceptor
class BearerAuthInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    String? userToken = Backpack.instance.read(StorageKeysConfig.auth);

    if (userToken != null) {
      options.headers.addAll({"Authorization": "Bearer $userToken"});
    }

    return super.onRequest(options, handler);
  }
}

Session-Based Cart Management

// Add items to a cart session
Backpack.instance.sessionUpdate("cart", "items", ["item_1", "item_2"]);
Backpack.instance.sessionUpdate("cart", "total", 49.99);

// Read cart data
Map<String, dynamic>? cart = Backpack.instance.sessionData("cart");

// Clear the cart
Backpack.instance.sessionFlush("cart");

Quick Feature Flags

// Store feature flags in Backpack for fast access
backpackSave("feature_dark_mode", true);
backpackSave("feature_notifications", false);

// Check a feature flag
bool darkMode = backpackRead<bool>("feature_dark_mode") ?? false;