1 | # Upgrade Guide
|
2 |
|
3 | ### 0.18.x -> 0.19.0
|
4 |
|
5 | #### HTTPS Proxies
|
6 |
|
7 | Routing through an https proxy now requires setting the `protocol` attribute of the proxy configuration to `https`
|
8 |
|
9 | ### 0.15.x -> 0.16.0
|
10 |
|
11 | #### `Promise` Type Declarations
|
12 |
|
13 | The `Promise` type declarations have been removed from the axios typings in favor of the built-in type declarations. If you use axios in a TypeScript project that targets `ES5`, please make sure to include the `es2015.promise` lib. Please see [this post](https://blog.mariusschulz.com/2016/11/25/typescript-2-0-built-in-type-declarations) for details.
|
14 |
|
15 | ### 0.13.x -> 0.14.0
|
16 |
|
17 | #### TypeScript Definitions
|
18 |
|
19 | The axios TypeScript definitions have been updated to match the axios API and use the ES2015 module syntax.
|
20 |
|
21 | Please use the following `import` statement to import axios in TypeScript:
|
22 |
|
23 | ```typescript
|
24 | import axios from 'axios';
|
25 |
|
26 | axios.get('/foo')
|
27 | .then(response => console.log(response))
|
28 | .catch(error => console.log(error));
|
29 | ```
|
30 |
|
31 | #### `agent` Config Option
|
32 |
|
33 | The `agent` config option has been replaced with two new options: `httpAgent` and `httpsAgent`. Please use them instead.
|
34 |
|
35 | ```js
|
36 | {
|
37 | // Define a custom agent for HTTP
|
38 | httpAgent: new http.Agent({ keepAlive: true }),
|
39 | // Define a custom agent for HTTPS
|
40 | httpsAgent: new https.Agent({ keepAlive: true })
|
41 | }
|
42 | ```
|
43 |
|
44 | #### `progress` Config Option
|
45 |
|
46 | The `progress` config option has been replaced with the `onUploadProgress` and `onDownloadProgress` options.
|
47 |
|
48 | ```js
|
49 | {
|
50 | // Define a handler for upload progress events
|
51 | onUploadProgress: function (progressEvent) {
|
52 | // ...
|
53 | },
|
54 |
|
55 | // Define a handler for download progress events
|
56 | onDownloadProgress: function (progressEvent) {
|
57 | // ...
|
58 | }
|
59 | }
|
60 | ```
|
61 |
|
62 | ### 0.12.x -> 0.13.0
|
63 |
|
64 | The `0.13.0` release contains several changes to custom adapters and error handling.
|
65 |
|
66 | #### Error Handling
|
67 |
|
68 | Previous to this release an error could either be a server response with bad status code or an actual `Error`. With this release Promise will always reject with an `Error`. In the case that a response was received, the `Error` will also include the response.
|
69 |
|
70 | ```js
|
71 | axios.get('/user/12345')
|
72 | .catch((error) => {
|
73 | console.log(error.message);
|
74 | console.log(error.code); // Not always specified
|
75 | console.log(error.config); // The config that was used to make the request
|
76 | console.log(error.response); // Only available if response was received from the server
|
77 | });
|
78 | ```
|
79 |
|
80 | #### Request Adapters
|
81 |
|
82 | This release changes a few things about how request adapters work. Please take note if you are using your own custom adapter.
|
83 |
|
84 | 1. Response transformer is now called outside of adapter.
|
85 | 2. Request adapter returns a `Promise`.
|
86 |
|
87 | This means that you no longer need to invoke `transformData` on response data. You will also no longer receive `resolve` and `reject` as arguments in your adapter.
|
88 |
|
89 | Previous code:
|
90 |
|
91 | ```js
|
92 | function myAdapter(resolve, reject, config) {
|
93 | var response = {
|
94 | data: transformData(
|
95 | responseData,
|
96 | responseHeaders,
|
97 | config.transformResponse
|
98 | ),
|
99 | status: request.status,
|
100 | statusText: request.statusText,
|
101 | headers: responseHeaders
|
102 | };
|
103 | settle(resolve, reject, response);
|
104 | }
|
105 | ```
|
106 |
|
107 | New code:
|
108 |
|
109 | ```js
|
110 | function myAdapter(config) {
|
111 | return new Promise(function (resolve, reject) {
|
112 | var response = {
|
113 | data: responseData,
|
114 | status: request.status,
|
115 | statusText: request.statusText,
|
116 | headers: responseHeaders
|
117 | };
|
118 | settle(resolve, reject, response);
|
119 | });
|
120 | }
|
121 | ```
|
122 |
|
123 | See the related commits for more details:
|
124 | - [Response transformers](https://github.com/axios/axios/commit/10eb23865101f9347570552c04e9d6211376e25e)
|
125 | - [Request adapter Promise](https://github.com/axios/axios/commit/157efd5615890301824e3121cc6c9d2f9b21f94a)
|
126 |
|
127 | ### 0.5.x -> 0.6.0
|
128 |
|
129 | The `0.6.0` release contains mostly bug fixes, but there are a couple things to be aware of when upgrading.
|
130 |
|
131 | #### ES6 Promise Polyfill
|
132 |
|
133 | Up until the `0.6.0` release ES6 `Promise` was being polyfilled using [es6-promise](https://github.com/jakearchibald/es6-promise). With this release, the polyfill has been removed, and you will need to supply it yourself if your environment needs it.
|
134 |
|
135 | ```js
|
136 | require('es6-promise').polyfill();
|
137 | var axios = require('axios');
|
138 | ```
|
139 |
|
140 | This will polyfill the global environment, and only needs to be done once.
|
141 |
|
142 | #### `axios.success`/`axios.error`
|
143 |
|
144 | The `success`, and `error` aliases were deprecated in [0.4.0](https://github.com/axios/axios/blob/master/CHANGELOG.md#040-oct-03-2014). As of this release they have been removed entirely. Instead please use `axios.then`, and `axios.catch` respectively.
|
145 |
|
146 | ```js
|
147 | axios.get('some/url')
|
148 | .then(function (res) {
|
149 | /* ... */
|
150 | })
|
151 | .catch(function (err) {
|
152 | /* ... */
|
153 | });
|
154 | ```
|
155 |
|
156 | #### UMD
|
157 |
|
158 | Previous versions of axios shipped with an AMD, CommonJS, and Global build. This has all been rolled into a single UMD build.
|
159 |
|
160 | ```js
|
161 | // AMD
|
162 | require(['bower_components/axios/dist/axios'], function (axios) {
|
163 | /* ... */
|
164 | });
|
165 |
|
166 | // CommonJS
|
167 | var axios = require('axios/dist/axios');
|
168 | ```
|