Overview

A cross-platform dart:io that works on all platforms, including browsers.

You can simply replace dart:io imports with package:universal_io/universal_io.dart.

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

APIs added on top of "dart:io"

• BrowserHttpClient
  • A subclass of "dart:io" HttpClient that works in browsers.
  • See also BrowserHttpClientRequest, BrowserHttpClientResponse, and BrowserHttpClientException.
  • Uses XMLHttpRequest in browsers. WASM-compatible.
• HttpClient
  • HttpClient() factory is changed so that it returns BrowserHttpClient on browsers.
• Platform
  • The package makes methods like Platform.isAndroid and Platform.isMacOS work in the browsers too.
• InternetAddress
  • The package makes it works in the browsers too.
• BytesBuilder
  • The package makes it works in the browsers too.

Links

• API reference
• Github project
  • We appreciate feedback, issue reports, and pull requests.

Similar packages

• universal_html (cross-platform DOM, CSS, etc.)

Getting started

1.Add dependency

In pubspec.yaml:

dependencies:
                  universal_io: ^2.3.0
                

2.Use HTTP client

// Replace 'dart:io' imports with the following:
                import 'package:universal_io/universal_io.dart';
                
                Future<void> main() async {
                  // HttpClient can now be used in browser too!
                  final httpClient = newUniversalHttpClient();
                  final request = await httpClient.getUrl(Uri.parse("https://dart.dev/"));
                  final response = await request.close();
                }
                

HTTP client behavior

HTTP client is implemented with XMLHttpRequest (XHR) API on browsers.

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.

Helpful error messages

When requests fail and assertions are enabled, error messages contains descriptions how to fix possible issues such as missing cross-origin headers.

The error messages look like the following:

XMLHttpRequest error.
                -------------------------------------------------------------------------------
                HTTP method:             PUT
                HTTP URL:                http://destination.com/example
                Origin:                  http://source.com
                Cross-origin:            true
                browserCredentialsMode:  false
                browserResponseType:     arraybuffer
                
                THE REASON FOR THE XHR ERROR IS UNKNOWN.
                (For security reasons, browsers do not explain XHR errors.)
                
                Is the server down? Did the server have an internal error?
                
                Enabling credentials mode would enable use of some HTTP headers in both the
                request and the response. For example, credentials mode is required for
                sending/receiving cookies. If you think you need to enable 'credentials mode',
                do the following:
                
                    final httpClientRequest = ...;
                    if (httpClientRequest is BrowserHttpClientRequest) {
                      httpClientRequest.browserCredentialsMode = true;
                    }
                
                Did the server respond to a cross-origin "preflight" (OPTIONS) request?
                
                Did the server send the following headers?
                  * Access-Control-Allow-Origin: http://source.com
                    * You can also use wildcard ("*").
                    * Always required for cross-origin requests!
                  * Access-Control-Allow-Methods: PUT
                    * You can also use wildcard ("*").
                

Sometimes when you do cross-origin requests in browsers, you want to use CORS "credentials mode". This can be achieved with the following pattern:

import 'package:universal_io/universal_io.dart';
                
                Future<void> main() async {
                    final client = newUniversalHttpClient();
                    final request = client.getUrl(Url.parse('http://example/url'));
                
                    // Enable credentials mode
                    if (request is BrowserHttpClientRequest) {
                      request.browserCredentialsMode = true;
                    }
                
                    // Close request
                    final response = await request.close();
                    // ...
                }
                

Streaming text responses

The underlying XMLHttpRequest (XHR) API supports response streaming only when responseType is "text". This works for responses that are UTF-8 text.

This package automatically uses responseType "text" based on value of the HTTP request header "Accept". These media types are defined BrowserHttpClient.defaultTextMimes.

If you want to disable streaming, use the following pattern:

import 'package:universal_io/universal_io.dart';
                
                Future<void> main() async {
                    final client = newUniversalHttpClient();
                    if (client is BrowserHttpClient) {
                      client.onBrowserHttpClientRequestClose = (request) {
                        if (someCondition) {
                          request.browserResponseType = 'text';
                        }
                      };
                    }
                    // ...
                }
                

2.3.1

• Improves documentation.

2.3.0

• Makes BrowserHttpClient WASM compatible by making it use "dart:js_interop" rather than "dart:html".
• Fixes various bugs.
• Adds Platform.lineTerminator.
• Lowers minimum SDK constraint to 3.6.

2.2.3

• Fixes a bug in new Dart SDK versions.

2.2.2

• Improve dependency constraints.

2.2.1

• Fixes pubspec.yaml for Dart 3.x.

2.2.0

• Refactoring, better documentation, and some additional APIs in BrowserHttpClient.

2.1.0

• Removes lots of unnecessary stuff.
• This has some breaking changes, but it's unlikely that anyone is using the removed stuff. The package continues to follow the Dart SDK "dart:io" API.

2.0.5

• Fixes various small issues.

2.0.4

• Fixes Platform.operatingSystemVersion (issue #9).

2.0.3

• Fixes various issues.

2.0.2

• Fixes issue #17.

2.0.1

• Fixes issues in Node.JS.

2.0.0

• Finishes migration to null safety.

2.0.0-nullsafety.2

• Eliminated unnecessary dependencies.

2.0.0-nullsafety.1

• Improves documentation.
• Improves BrowserHttpClientException messages.
• Deprecates libraries prefer_sdk/io.dart and prefer_universal/io.dart. Developers should import just io.dart.

2.0.0-nullsafety.0

• The first null-safe version.
• Makes changes in BrowserHttpClient / BrowserHttpClientRequest API:
  • The property for enabling credentials mode is now browserCredentialsMode. The default is false.
  • The property for setting response type is now browserResponseType ("arraybuffer", "text", etc.). By default, if HTTP request header "Accept" contains only text MIMEs ("text/plain", etc.), this package uses responseType "text".
  • HTTP client now has onBrowserHttpClientRequestClose for using your own logic for setting browserResponseType.
• Removes IO adapter API.

1.0.2

• Fixes issue #11 (InternetAddress parameter).
• Fixes issue #12 (CORS credentials mode). Eliminates legacy, complicated behavior. Developers should choose either omit or include. Improves error messages and documentation related to it.
• Replaces MD5/SHA1 implementations used by some of the source code copied from dart:io. It now uses package:crypto instead of implementations copied from dart:io.

1.0.0

• Implements recent changes in 'dart:io' (Dart SDK 2.8).
• HttpDriver is replaced by 'dart:io' HttpOverrides.
• FileSystemDriver is replaced by 'dart:io' IOOverrides.
• Various other driver APIs are renamed or removed.
• BrowserLikeHttpClientRequest is now BrowserHttpClientRequest.
• BrowserHttpClientRequest implementation is improved.

0.8.6

• Fixed documentation and small fixes related to nodejs_io.

0.8.5

• Raised minimum SDK to 2.6 and upgraded dependencies.
• Changed how CORS credentials mode is enabled. It was previously enabled with a header, but now we introduced subclasses for HttpClient and HttpClientRequest. This is a breaking change, but we decided not to bump the major version number.
• Improved analysis and test settings.

0.8.4

• Added 'prefer_sdk/io.dart' and 'prefer_universal/io.dart' libraries for dealing with conditional export issues.
• Library 'package:universal_io/io.dart' now exports SDK version by default.

0.8.3

• Replaced IP address parsing with the new Uri.parseIPv4Address / Uri.parseIPv6Address.
• Fixed missing HTTP status codes.

0.8.2

• Fixed problems introduced by Dart SDK 2.5.0-dev-2.0.

0.8.1

• Fixed pubspec.yaml and documented Dart SDK 2.5 breaking changes.

0.8.0

• Updated classes to Dart 2.5. See Dart SDK documentation about the changes.
  • Various APIs now return Uint8List instead of List<int>. Examples: File, Socket, HttpClientResponse.
  • Various other breaking changes such as Cookie constructor.

0.7.3

• Fixed the following error thrown by the Dart build system in some cases: "Unsupported conditional import of dart:io found in universal_io|lib/io.dart".

0.7.2

• Small fixes.

0.7.1

• Fixed various bugs.
• Improved the test suite.

0.7.0

• Improved driver base classes and the test suite.

0.6.0

• Major refactoring of IODriver API.

0.5.1

• Fixed small bugs.

0.5.0

• Fixed various bugs.
• Re-organized source code.
• Eliminated dependencies by doing IP parsing in this package.
• Improved the test suite for drivers.