Bundling a Local Web App

Bundle a single-page web application into the EasyCord Flutter shell.

Introduction

EasyCord loads built web assets directly from device storage. This allows your web application to run entirely offline without requiring a remote server.

Prerequisites

• A single-page web application built with a modern framework.
• An existing Flutter project configured with EasyCord.

Step 1: Export Static Files

Generate a production build of your web application containing static HTML, CSS, and JS. Ensure the build uses relative asset paths.

npm run build

Step 2: Link Assets

Copy the output files of your build directory into the Flutter project's assets folder.

mkdir -p flutter/assets/web
cp -r dist/* flutter/assets/web/

Tip: If you are using an EasyCord monorepo structure, you can automate this step using the easycord bundle CLI command.

Step 3: Register Assets

Add the assets folder to your Flutter pubspec.yaml configuration. This bundles the files into the application binary.

flutter:
  assets:
    - assets/web/
    - assets/web/assets/

Step 4: Configure the WebView

Use EasyCordWidget with the asset URL in your Dart entry point.

import 'package:flutter/material.dart';
import 'package:easycord/easycord.dart';

void main() => runApp(const MyApp());

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

  @override
  Widget build(BuildContext context) {
    // You should initialize an EasyCord instance and pass its navigatorKey 
    // to MaterialApp so native dialogs work correctly.
    // e.g. final easyCord = EasyCord();
    
    return const MaterialApp(
      // navigatorKey: easyCord.navigatorKey, 
      home: Scaffold(
        body: EasyCordWidget(
          initialUrl: 'assets/web/index.html',
        ),
      ),
    );
  }
}

[!IMPORTANT] EasyCord uses a local loopback server to serve web assets. For this to work in Release mode on Android, you must add the INTERNET permission to your android/app/src/main/AndroidManifest.xml.

Verification

Run the Flutter application on a device without an internet connection. The application loads the web interface from the local storage.

Troubleshooting

Routing Fails on Reload

Occurs when using absolute routing in a single-page application loaded from the file system. Use hash routing in your web framework. Alternatively, configure a routing fallback inside EasyCordWidget to redirect unknown requests to index.html.

Next Steps

• Wrapping a Live Website
• Writing Custom Flutter Plugins