[docs] Setting devServer.proxy to a string value can be confusing

[lbogdan]

What problem does this docs change solve?

When setting devServer.proxy to a string value, proxying only happens for XHR requests, which can be confusing:

• configure devServer.proxy to 'http://localhost:3000';
• open http://localhost:8080/api/users from the address bar in the browser;
  • expectation: the request is proxyed to http://localhost:3000/api/users, the browser shows the API response;
  • reality: the browser shows the app (it loads index.html, because of webpack-dev-server's historyApiFallback);
• the same request works fine (gets proxyed and returns the API response) if it's done using XMLHttpRequest (axios) or fetch.

If setting devServer.proxy explicitly to { '^/api': { target: 'http://localhost:3000' } }, the same URL - http://localhost:8080/api/users - will work as expected both when opened from the address bar and when loading it from an XHR request.

What should the docs change look like?

Make this distinction clear in the docs, as users might set devServer.proxy to a string, test that it works by loading an API URL from the browser's address bar, see the app instead of the API response, and conclude that it doesn't work.

[LinusBorg]

Looks rather like a bug, I would say ... I doubt that this is intended, and know no reason why it could be.

[lbogdan]

Looks like it's intended, according to prepareProxy.js:75 .

[LinusBorg]

I mean I don't see why the behaviour should be different between the string and object notation.

[lbogdan]

Because by using object notation, you can match part of the URL (e.g. proxy all URLs matching ^/api), while if using just a string, you have to proxy everything except a valid URL, but because of historyApiFallback, every URL is valid, hence the need for that heuristic. I imagine the initial thought was convenience, but it ended up being more confusing than convenient, imo.

[LinusBorg]

Thanks, you're completely right. Maybe time for bed for me...