flutter_dotenv_remote #

Use the hosted portal at https://flutterdotenv.com to create, manage and publish environment configs, then load them in your Flutter app by ID.

This package provides an extension on flutter_dotenv that fetches a JSON-based environment, loads it into dotenv, and caches the last successful result for offline fallback.

Why use the portal #

• Fast setup: sign up, create a config, copy the config ID and use it in your app.
• Centralized management: edit environment sets in a web UI and have client apps pick up latest changes by ID.
• Optional paid features & team management (coming soon).

Quick start (recommended) #

1. Sign up at https://www.flutterdotenv.com and create a config. Copy the generated config ID.
2. Add the package to your pubspec.yaml:

dependencies:
  flutter_dotenv_remote: ^0.0.1
  flutter_dotenv: ^6.0.0

3. Load the config at app startup:

import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:flutter_dotenv_remote/flutter_dotenv_remote.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await dotenv.loadRemote(
    // UUID from your environment entry on flutterdotenv.com
    configId: '699fb309-6c5c-44fb-8612-b6a8dda08296',
    useCacheOnFailure: true,
    onLoadFailure: () {
      // optional: UI fallback or logging
      debugPrint('Failed to load config from remote and cache');
    },
  );

  runApp(const MyApp());
}

The library defaults to the Supabase instance used by the portal; you do not need to provide keys when consuming portal configs.

Use the loaded environment variables #

See Flutter Dotenv documentation for how to use the variables in your app.

Advanced / self-hosted #

If you run your own Supabase instance you can pass supabaseUrl and supabaseAnonKey, or provide a SupabaseClient instance (useful for testing or advanced scenarios):

await dotenv.loadRemote(
  configId: 'your-id',
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseAnonKey: 'your-anon-key',
  // or
  // supabaseClient: SupabaseClient(...),
);

Caching and failure behaviour #

• On successful remote load the library caches the final dotenv string locally (SharedPreferences).
• If a remote load fails and useCacheOnFailure is true, the last cached config is loaded.
• If both remote and cache loading fail and an onLoadFailure callback is provided, it will be invoked so the app can handle the error.

Security note #

The portal's Supabase anon key is used solely for reading published environment configs. Do not store sensitive secrets in public configs; use appropriate server-side controls for secrets.

Contributing & support #

Open an issue or submit a PR. For portal support and account/tier questions use https://www.flutterdotenv.com.

License #

This project is licensed under the terms in the repository LICENSE file.