DOCSEARCHbyAlgolia
Submit Docs

Localflare Documentation

repository·main·Indexed 23 days ago

https://github.com/rohanprasadofficial/localflare

A local development dashboard for Cloudflare Workers that allows developers to visualize and interact with D1 databases, KV namespaces, R2 buckets, Durable Objects, and Queues without changing application code. Includes the localflare CLI, localflare-core for parsing Wrangler configurations, and a React-based dashboard for data management and SQL querying.

Tokens
21.2K
Snippets
46
Records
144
Agent score
81%

What's inside Localflare

  2. How Localflare's sidecar architecture works

    main

    Localflare uses a sidecar architecture that runs alongside your worker within the same wrangler dev process. This allows the Localflare API worker to share the exact same binding instances as your application code.

    Key Benefits:

    • Zero Code Changes: Your application code remains untouched; no SDKs or modifications are required.
    • Real Bindings: It uses actual working bindings (D1, KV, R2, etc.) rather than mocks.
    • Full Interaction: You can interact with real Queue messages and Durable Object instances.

    Architecture Model:

    Single wrangler dev Process
├── Your Worker (http://localhost:8787)
│   └── Your application code unchanged
├── Localflare API Worker
│   └── Dashboard API routes (/__localflare/*)
└── Shared Bindings
    ├── D1 databases (same instance)
    ├── KV namespaces (same instance)
    ├── R2 buckets (same instance)
    ├── Queues (same in-memory queue)
    └── Durable Objects (same instances)

  3. Manage D1 Databases with the D1 Database Explorer

    main

    The D1 Database Explorer allows for comprehensive management of local D1 databases through three main interfaces:

    Data Browser

    • Navigation: Paginated tables with page sizes of 25, 50, 100, or 250.
    • Column Management: Resizable columns (up to 400px), visibility toggles, and global search.
    • Filtering: Column-level filtering using operators like Equals, Not equals, Contains, Starts with, Is null, and Is not null.
    • Sorting: Supports both client-side (current page) and server-side (ORDER BY) sorting.
    • Editing: Inline cell editing with auto-save, row actions (Edit, Copy as JSON, Delete), and bulk row selection/deletion.
    • Dummy Data: Generate 1-100 rows of realistic fake data using Faker.js. It supports all SQLite/D1 types: INTEGER, REAL, TEXT, DATE, DATETIME, TIMESTAMP, TIME, BOOLEAN, NUMERIC, DECIMAL, and BLOB. It automatically skips auto-increment primary keys.

    SQL Query Editor

    • Features: Syntax highlighting (CodeMirror), SQL autocomplete for tables/columns/keywords, and query history stored in localStorage.
    • Execution: Use Cmd/Ctrl + Enter to execute queries.

    Schema Viewer

    • Features: View table structures, column types, primary key indicators, and row counts per table.

  4. Manage KV, R2, Queues, and Durable Objects

    main

    The dashboard provides specialized browsers for other Cloudflare bindings:

    • KV Browser: View all key-value pairs, edit values (with JSON support), perform bulk deletes, and search/filter keys.
    • R2 File Manager: Browse bucket objects, upload/download files, view metadata, and delete objects.
    • Queue Inspector: View messages, send test messages, and monitor activity.
    • Durable Objects: List namespaces, view active instances, and inspect instance state.

  6. Use Attach Mode for custom dev workflows

    main

    For projects using custom development commands (like OpenNext, Nuxt, or specific wrangler dev setups), use Attach Mode. This runs the Localflare API separately, sharing the same persistence directory as your dev server.

    Workflow:

    1. Terminal 1: Start your existing dev server (e.g., pnpm dev, opennext dev, nuxt dev, or wrangler dev).
    2. Terminal 2: Run localflare attach to connect the Localflare API.

    Example:

    # Terminal 1: Your dev server
pnpm dev

# Terminal 2: Localflare API
localflare attach
    # Terminal 1: Your dev server
pnpm dev        # or: opennext dev, nuxt dev, wrangler dev, etc.

# Terminal 2: Localflare API
localflare attach

# Custom port for Localflare API
localflare attach --port 9000

  7. Quick Start with Localflare

    main

    To start using Localflare for your Cloudflare Worker project, navigate to your project directory and run it using npx. Localflare will automatically detect your wrangler.toml, start your worker at http://localhost:8787, and open the dashboard at https://studio.localflare.dev.

    Requirements:

    • Node.js 18+
    • A Cloudflare Workers project with a wrangler.toml
    • wrangler dev must be functional for your project.
    # Navigate to your Cloudflare Worker project
cd your-worker-project

# Run Localflare
npx localflare

  8. Run Localflare in your project

    main

    To use Localflare, navigate to your Cloudflare Worker project directory (where your wrangler.toml is located) and run the localflare command.

    This process automatically:

    1. Detects your wrangler.toml configuration.
    2. Starts your worker at http://localhost:8787 (or your specified port).
    3. Opens the dashboard at https://studio.localflare.dev (or a local dashboard if --dev is used).
    localflare

  9. Deploy the Localflare Website to Cloudflare Workers

    main

    The website is deployed using Cloudflare Workers. Ensure you are logged in via Wrangler before running the deployment command. Once deployed, the site is accessible at https://localflare-www.<your-subdomain>.workers.dev.

    # Login to Cloudflare (if not already)
npx wrangler login

# Deploy
pnpm deploy

  11. Pass Wrangler options to Localflare

    main

    You can pass arguments directly to wrangler by using the -- delimiter. This is useful for specifying environments or setting variables during the development session.

    Examples:

    • Use a specific environment: localflare -- --env staging
    • Set environment variables: localflare -- --var API_KEY:secret
    • Combine Localflare and Wrangler options: localflare --port 9000 -- --env production
    # Use a specific environment
localflare -- --env staging

# Set environment variables
localflare -- --var API_KEY:secret

# Combine options
localflare --port 9000 -- --env production

  12. How to parse Wrangler configurations with localflare-core

    main

    To extract Cloudflare binding configurations from a project, use findWranglerConfig to locate the configuration file in a directory, then pass that path to parseWranglerConfig. This allows you to programmatically access D1, KV, R2, Durable Objects, and Queue bindings.

    import {
  parseWranglerConfig,
  findWranglerConfig,
  WRANGLER_CONFIG_FILES
} from 'localflare-core';

// Find wrangler config in current directory
const configPath = findWranglerConfig(process.cwd());
// Returns: ./wrangler.toml, ./wrangler.json, or ./wrangler.jsonc

// Parse the configuration
const config = parseWranglerConfig(configPath);

// Access binding configurations
console.log(config.d1_databases);    // D1 database bindings
console.log(config.kv_namespaces);   // KV namespace bindings
console.log(config.r2_buckets);      // R2 bucket bindings
console.log(config.durable_objects); // Durable Object bindings
console.log(config.queues);          // Queue producer/consumer config