Axios next

[jasonsaayman]

Over the next few months I will be working on a new version of Axios, a v1 release bringing a vast amount of modernisations and bringing the library up to date with modern JS practices.

I would like people to please add any suggestions they have to this mega thread for discussion.

During this period I will also start closing any issues/pull requests that are related to future proposals or new features that are not backward compatible.

[jasonsaayman]

I have created a public Trello to help track all the tasks https://trello.com/b/SBqOxCst/axios-next

[DigitalBrainJS]

@jasonsaayman Isn't it too early to try to release v1.0? This is not as easy as it might seem. This is work up to a year, as there are many major issues that need to be solved in order to call this version stable, at least:

• fetch adapter + streams support + progress capturing (through streams)
• progress capturing support for node.js
  Some minor issues:
• The codebase is legacy, v1.0 should be refactored to ESM & ES5+, but currently, we have a lot of things from ES3.
• The build pipeline uses webpack instead of modern rollup, which is better for building modules.

IMHO it would be nice to have a dev(?) branch in the repo:

• dev branch - next minor/major release
• master - hotfixes/not breaking patches for the current minor version

BTW we already have AbortController support.
#2351 - solved by #3645

[jasonsaayman]

@DigitalBrainJS yeah for sure but I think we need to attempt to get to a working project. I want to stop breaking BC even though we are pre v1 we need to start keeping Axios as stable as possible in its current form.

I will add the branches but that does not largely impact starting a discussion around version 1, also the clutter on the repo really needs to be fixed, it is very difficult with the amount of issues and pull requests that are out there to keep on top of things.

For now I am collecting issues here that I believe are a version 1 material and then closing them as this will start to clean up the issue pool and help bring manageability back while not loosing the ideas mentioned in them.

Version 1 will very easily be a year long project, we can still add features, make fixes etc as long as we don't break anything in terms of BC.

[web-apply]

thanks

[MartinMuzatko]

Are you considering TypeScript for Axios next? Or are you keeping d.ts files separate on purpose?

[sttvld]

Flexible timeout settings might be handy, but for me, only connectTimeout is extremely important because working with some API methods that respond in hours.
Using Got on backend only because of this.
https://github.com/sindresorhus/got/blob/main/documentation/6-timeout.md

[aladdin-add]

👍 to publish esm.

[xHyroM]

👍 to publish esm.

What for? Alternatively... let there be a CJS version, because I think it's a mistake to switch to this one. Thousands of people are on CJS and even with node-fetch this was not the best move. If so, I would do both ESM and CJS, but definitely not just ESM. For upgrading, I would also use TypeScript, which would help a lot of typing and make using the module even easier.

[MartinMuzatko]

Even with providing both CJS and ESM, it is still painful to integrate with universal apps like NextJS, where one package might be required as cjs serverside, and then forces esm clientside.
ESM is cool when building in the browser, but for modern apps it caused me more pain than relief ^^"

[jasonsaayman]

@xHyroM we will have to see about a full TypeScript project, one of the great things about axios is it is a very small package. This will have to be investigated.

@MartinMuzatko I am not familiar with NextJS but if the module is published in ESM and includes the current checks to see if we are in the browser or not then the build process should take care of compilation into whatever the target is.

[aladdin-add]

yes, good to have a cjs export too, as esm cannot be required.

I recommended using dual mode:
https://nodejs.org/api/packages.html#packages_dual_commonjs_es_module_packages

{
  "name": "axios",
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "import": "./index.mjs",
    "require": "./index.cjs"
  }
}

and drop node < 12.22.0:

[xHyroM]

yes, good to have a cjs export too, as esm cannot be required.

I recommended using dual mode: https://nodejs.org/api/packages.html#packages_dual_commonjs_es_module_packages

{
  "name": "axios",
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "import": "./index.mjs",
    "require": "./index.cjs"
  }
}

and drop node < 12.22.0:

This is a good solution. I also know of a builder, https://esbuild.github.io/getting-started/ that might help with building for cjs/esm.

[Rolanddoda]

Ohh that sounds great!

One suggestion or request from me is to NOT introduce breaking changes. By using libraries in general, I hate seeing breaking changes all around.

If breaking changes are the only way for -> "bringing a vast amount of modernisations and bringing the library up to date with modern JS practices" I suggest you do that in a smart way.

I am not sure what "smart-way" means, but "right now" one thought I have is of releasing breaking changes one-by-one and not going from v0.24.0 to v1 directly.

Also... I think having RFCs (request for comments) for each breaking change or new design for features is always a good thing.

Axios is awesome! 🥳

[binki]

If breaking changes are the only way for -> "bringing a vast amount of modernisations and bringing the library up to date with modern JS practices" I suggest you do that in a smart way.

I am not sure what "smart-way" means, but "right now" one thought I have is of releasing breaking changes one-by-one and not going from v0.24.0 to v1 directly.

If you actually want to avoid things breaking with API level breaking changes, using a new package name is the only safe way. That’d let you install it side by side with the old version and allow consumers to switch to the new version as they desire any features which could not be delivered without breaking the old API.

[popuguytheparrot]

Fixes broken types for response, config

[arthurfiorette]

Are you considering TypeScript for Axios next? Or are you keeping d.ts files separate on purpose?

It would be so much better to write the new axios natively in typescript. If we take a look at the most amount of current open PR's, they are just to fix the index.d.ts file. A thing that with the new typescript codebase would be caught early.

Plus, with webpack, the inpact of typescript to the transpiled javascript can be literally 0.

[CatsMiaow]

How about support undici in Node.js environment

• https://nodejs.medium.com/introducing-undici-4-1e321243e007
• https://github.com/nodejs/undici

[cgarrovillo]

How about support undici in Node.js environment

• https://nodejs.medium.com/introducing-undici-4-1e321243e007
• https://github.com/nodejs/undici

Not supported on the browser no?

[CatsMiaow]

Not supported on the browser no?

See nodejs/undici#968

undici is a module rewritten by the Node.js team to replace the core HTTP stack.
I don't know what's good about using undici in the browser.

axios is also used a lot in the backend, so supporting undici can lead to better performance.
The HTTP module of NestJS, the representative Node.js backend framework, is also combined with axios.

https://github.com/nestjs/axios

[arthurfiorette]

The undici adapter is the same as the HarmonyOS one. It will just depends on how the axios maintainers would do it, either by sticking it into the main package (like the xhr or node) or creating a @axios/undici-adapter, for example.

Splitting into different packages may be a better way to handle code size and bundling, but that will require either a monorepo structure (preferred?) or maintaining multiple repositories under axios organization

[jasonsaayman]

An official adapter might be a good option, actually it is part of the ideas i have here, more official adapters that make you able to choose what you want and don't want in your axios experience

[hughns]

@jasonsaayman have the maintainers considered making a v1 release based on the current codebase? (Essentially taking the current v0.26.0 and promoting it to v1.0.0).

Yes, it may have never been the intention that the library is considered v1 worthy in its current form, but due to the quality of this API it has been adopted by many (71k+ public dependents and 26M weekly downloads according to https://www.npmjs.com/package/axios).

By immediately moving to major releases the maintainers might actually become freer to make the more invasive changes as they can more clearly signal to the users what is a breaking change or not.

Alongside the releases the maintainers could also choose to publish a support schedule which makes it clear about the level of support (or lack of support) that is to be provided for current versions.

So, this would make Axios next be something like v2.0.0. ...or you could choose to take a more incremental approach and release in smaller major releases (Axios next could be thought of as a series of vN+1 releases).

[jasonsaayman]

I like this idea, ok @hughns I think you are correct, the next release I cut will be 0.27 and then a v1. We will then work towards next which is whatever version +1 as mentioned above.

[jasonsaayman]

Additionally I am going to close this issue and we can move this to a discussion at #4477