Overview #

A cross-platform dart:io that works in all platforms (browsers, Flutter, and VM).

Licensed under the Apache License 2.0. Much of the source code is derived from Dart SDK, which was obtained under the BSD-style license of Dart SDK. See LICENSE file for details.

Links #

• Pub package
• Issue tracker
• Create a pull request

Similar packages #

• universal_html (cross-platform dart:html)

Getting started #

pubspec.yaml #

dependencies:
  universal_io: ^1.0.1

The may also consider chrome_os_io (if you use Chrome OS) and nodejs_io (if you use Node.JS).

main.dart #

import 'package:universal_io/io.dart';

Future<void> main() async {
  final httpClient = HttpClient();
  final request = await httpClient.getUrl(Uri.parse("http://google.com"));
  final response = await request.close();
}

Getting warnings? In some situations, Dart development tools (your IDE) may give warnings, but your application should compile normally. It's possible to eliminate such warnings by importing 'package:universal_io/prefer_universal/io.dart', but we recommend that you always stick to 'package:universal_io/io.dart'.

Browser driver #

HTTP client #

HTTP client is implemented using XMLHttpRequest (XHR) (in dart:html, the class is HttpRequest). In future, we may support Fetch API too.

XHR causes the following differences with dart:io:

• HTTP connection is created only after request.close() has been called.
• Same-origin policy limitations. For making cross-origin requests, see documentation below.

CORS #

If the HTTP request is cross-origin and Authorization header is present, the request will automatically use CORS credentials mode. For other requests, you can manually enable credentials mode using:

import 'package:universal_io/io.dart';

Future<void> main() async {
  final request = HttpClient().getUrl(Uri.parse('https://example.com/path'));

  if (request is BrowserHttpClientRequest) {
    request.credentialsMode = BrowserHttpClientCredentialsMode.include;
  }

  final response = await request.close();
  // ...
}

If any cross-origin request fails, error message contains a detailed description how to fix possible issues like missing cross-origin headers. The error messages look like:

BrowserHttpClient received an error from XMLHttpRequest (which doesn't tell
reason for the error).

HTTP method:   PUT
URL:           http://destination.com/path/example
Origin:        http://source.com

Cross-origin request!
CORS 'credentials mode' is disabled (the browser will not send cookies).
You can enable 'credentials mode' with:

    if (httpRequest is BrowserHttpClientRequest) {
      httpRequest.credentialsMode = BrowserHttpClientCredentialsMode.include;
    }

Did the server send the following mandatory headers?
  * Access-Control-Allow-Origin: http://source.com
    * OR '*'
  * Access-Control-Allow-Methods: PUT

Streaming responses #

XHR in browsers supports streaming HTTP response when the response type is 'text'.

You can enable this behavior with the following trick:

import 'package:universal_io/io.dart';

Future<void> main() async {
    final request = HttpClient().getUrl(Uri.parse('https://example.com/path'));

    // Define response type in browsers
    if (request is BrowserHttpClientRequest) {
      request.responseType = BrowserHttpClientResponseType.text;
    }

    // Listen streaming response
    final response = await request.close();
    response.listen((chunk) {
      // ...
    });
}

Platform #

The implementation supports APIs such as:

• Platform.isWindows
• Platform.operatingSystem
• Platform.locale