# universal_io 2.3.1 Cross-platform 'dart:io' that adds browser support for HttpClient and some other "dart:io" APIs. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir flutter pub add universal_io ``` Published: 2025-11-16T19:32:10.094594Z Expected archive SHA-256: f63cbc48103236abf48e345e07a03ce5757ea86285ed313a6a032596ed9301e2 Available in cache; verification: upstream_checksum ## Direct dependencies - collection: ^1.17.0 - meta: ^1.9.0 - typed_data: ^1.3.0 ## Package README (untrusted upstream documentation) [![Pub Package](https://img.shields.io/pub/v/universal_io.svg)](https://pub.dartlang.org/packages/universal_io) [![package publisher](https://img.shields.io/pub/publisher/universal_io.svg)](https://pub.dev/packages/universal_io/publisher) [![Github Actions CI](https://github.com/dint-dev/universal_io/workflows/Dart%20CI/badge.svg)](https://github.com/dint-dev/universal_io/actions) # Overview A cross-platform [dart:io](https://api.dart.dev/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](LICENSE). Some of the source code was derived [from Dart SDK](https://github.com/dart-lang/sdk/tree/master/sdk/lib/io), which was obtained under the BSD-style license of Dart SDK. See LICENSE file for details. ## APIs added on top of "dart:io" * [BrowserHttpClient](https://pub.dev/documentation/universal_io/latest/universal_io/BrowserHttpClient-class.html) * A subclass of "dart:io" [HttpClient](https://api.dart.dev/dart-io/HttpClient-class.html) that works in browsers. * See also [BrowserHttpClientRequest](https://pub.dev/documentation/universal_io/latest/universal_io/BrowserHttpClientRequest-class.html), [BrowserHttpClientResponse](https://pub.dev/documentation/universal_io/latest/universal_io/BrowserHttpClientResponse-class.html), and [BrowserHttpClientException](https://pub.dev/documentation/universal_io/latest/universal_io/BrowserHttpClientException-class.html). * Uses XMLHttpRequest in browsers. WASM-compatible. * [HttpClient](https://pub.dev/documentation/universal_io/latest/universal_io/HttpClient-class.html) * `HttpClient()` factory is changed so that it returns BrowserHttpClient on browsers. * [Platform](https://pub.dev/documentation/universal_io/latest/universal_io/Platform-class.html) * The package makes methods like `Platform.isAndroid` and `Platform.isMacOS` work in the browsers too. * [InternetAddress](https://pub.dev/documentation/universal_io/latest/universal_io/InternetAddress-class.html) * The package makes it works in the browsers too. * [BytesBuilder](https://pub.dev/documentation/universal_io/latest/universal_io/BytesBuilder-class.html) * The package makes it works in the browsers too. ## Links * [API reference](https://pub.dev/documentation/universal_io/latest/) * [Github project](https://github.com/dint-dev/universal_io) * We appreciate feedback, issue reports, and pull requests. ## Similar packages * [universal_html](https://pub.dev/packages/universal_html) (cross-platform DOM, CSS, etc.) # Getting started ## 1.Add dependency In pubspec.yaml: ```yaml dependencies: universal_io: ^2.3.0 ``` ## 2.Use HTTP client ```dart // Replace 'dart:io' imports with the following: import 'package:universal_io/universal_io.dart'; Future 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)](https://developer.mozilla.org/en/docs/Web/API/XMLHttpRequest) 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: ```text 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"](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). This can be achieved with the following pattern: ```dart import 'package:universal_io/universal_io.dart'; Future 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](https://pub.dev/documentation/universal_io/latest/universal_io/BrowserHttpClient/defaultTextMimes.html). If you want to disable streaming, use the following pattern: ```dart import 'package:universal_io/universal_io.dart'; Future main() async { final client = newUniversalHttpClient(); if (client is BrowserHttpClient) { client.onBrowserHttpClientRequestClose = (request) { if (someCondition) { request.browserResponseType = 'text'; } }; } // ... } ``` ## Changelog # 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](https://github.com/dint-dev/universal_io/issues/9)). # 2.0.3 * Fixes various issues. # 2.0.2 * Fixes issue [#17](https://github.com/dint-dev/universal_io/issues/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](https://github.com/dint-dev/universal_io/issues/11) (InternetAddress parameter). * Fixes issue [#12](https://github.com/dint-dev/universal_io/issues/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](https://github.com/dart-lang/sdk/blob/master/CHANGELOG.md). * Various APIs now return `Uint8List` instead of `List`. 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.