@@ -0,0 +1,51 @@
1+# Support for ghcjs
2+
3+This branch of servant implements experimental support for
4+[ghcjs](https://github.com/ghcjs/ghcjs) for `servant-client`.
5+This means it allows you to write Haskell code in terms of `servant-client`,
6+compile it with `ghcjs` to javascript and then use it to execute XHRs from a
7+browser. The idea is that this should work transparently for the programmer,
8+i.e. from a user's perspective it should work exactly as it does when compiled
9+with `ghc`.
10+
11+## Status
12+
13+This branch is experimental.
14+
15+Known caveats:
16+
17+- Sending bodies in requests doesn't work when using methods `GET` and `HEAD`.
18+ At least when running the test-suite with node. `GET` and `HEAD` requests are
19+ not supposed to have request bodies and [xhr2](https://www.npmjs.com/package/xhr2)
20+ -- which we use to issue XHRs from node -- discards the request bodies for `GET` and
21+ `HEAD` requests. (This might actually work in some browsers, no clue.) This causes one
22+ failing test in the test-suite.
23+- We don't have CI for running the test-suite with `ghcjs`. We tried to make
24+ that work, but failed miserably. That's the main reason why this is not merged
25+ to `master`.
26+- `servant-client` uses libraries that are not optimized for `ghcjs`. I haven't
27+ investigated this much, but I could imagine that e.g. a native javascript JSON
28+ parser would be much faster than `aeson` compiled by `ghcjs`.
29+
30+## Getting it to work
31+
32+The `stack` file that is used to run the test-suite with `ghcjs` may provide
33+some inspiration: `servant-client/test/ghcjs/stack-ghcjs.yaml`.
34+
35+## Running the tests
36+
37+You can run the tests by doing:
38+
39+``` bash
40+./servant-client/test/ghcjs/run-tests.sh
41+```
42+
43+## Further development
44+
45+I propose to use the branch `client-ghcjs` as a place for further development
46+on `ghcjs` support for `servant-client`. We could
47+
48+- create PRs against the branch,
49+- for releases on `master` merge `master` into this branch to not fall behind,
50+- maybe even create tags, e.g. `ghcjs-v0.6` and `ghcjs-v0.7.1` to give people
51+ fixed commits to stick to.