@@ -1,64 +1,14 @@
11# servant-reflex
22
3−[](https://travis-ci.org/imalsogreg/servant-reflex)
3+[](https://travis-ci.org/imalsogreg/servant-reflex)
44
5+## The problem `servant-reflex` solves
56
6−This library lets you automatically derive [`reflex-dom`](https://github.com/reflex-frp/reflex-dom) clients that query each endpoint of a [`servant`](htps://github.com/haskell-servant/servant) webservice.
7+Keeping your frontend in sync with your API server can be difficult - when the API changes its input parameters or return type, XHR requests from the frontend will fail at runtime. If your API is defined by [servant](haskell-servant.readthedocs.io) combinators, you can use `servant-reflex` to share the API between the server and frontend.
8+Syncronization between is checked at compile time, and rather than building XHR requests by hand, API endpoints are available behind `reflex`'s FRP semantics.
79
8−## Building the library and test server
9−
10−### With `reflex-platform`:
11−
12−First build the library:
13−
14−```
15−git clone https://github.com/imalsogreg/servant-reflex
16−cd servant-reflex
17−git submodule update --init --recursive
18−./build.sh
19−./toSite.sh
20−```
21−
22−(the `toSite.sh` script copies the generated javascript to the server's static assets directory)
23−
24−
25−Then build the test server (not in a nix-shell):
26−
27−```
28−./init-sandbox.sh
29−cd testserver && cabal install --only-dep && cabal build && cd ..
30−
31−```
3210
3311
34−### Or, with a system-wide ghcjs
35−
36−You will need a recent [GHCJS installation](https://github.com/ghcjs/ghcjs), or use the [reflex-platform](https://github.com/reflex-frp/reflex-platform). A [snap](https://github.com/snapframework) server using [servant-snap](https://github.com/haskell-servant/servant-snap) is provided for serving the api. `Snap 1.0` is not yet on Hackage (and servant-snap is still experimental), but we bundle the sources as a git submodule. To install everything with cabal:
37−
38−```
39−git clone https://github.com/imalsogreg/servant-reflex
40−cd servant-reflex
41−git submodule update --init --recursive
42−./init-sandbox.sh
43−cd testserver && cabal install --only-dep && cabal build && cd ..
44−cabal install --only-dep
45−cabal build
46−./toSite
47−```
48−
49−The `toSite.hs` script copies the ghcjs-generated files into the server's static directory.
50−
51−## Running the example site
52−
53−The server must be run from the directory where static assets live:
54−
55−```
56−cd testserver
57−dist/build/back/back -p 8001
58−```
59−
60−And simply browse to `localhost:8001`
61−
6212## Example
6313
6414We have a webservice API defined in a module where both the server (compiled with ghc) and the frontend (compiled with ghcjs) can see it:
@@ -156,8 +106,35 @@ This example builds some input fields to enter API parameters, buttons to trigge
156106
157107For a great introduction to recative DOM building, see the [README](https://github.com/reflex-frp/reflex-platform) for the `reflex-platform`. For more information about servant, see their [documentation](http://haskell-servant.readthedocs.io/en/stable/). Thanks to the respective authors of these fabulous libraries.
158108
159−## TODOs
160109
161− - Request Headers
162− - Tests
163− - Code cleanup
110+## Building the library and test server
111+
112+This repository comes with a small example of an API shared between a ghcjs-compiled frontend ([exec/](https://github.com/imalsogreg/servant-reflex/tree/master/exec)) and a ghc-compiled backend ([testserver/](https://github.com/imalsogreg/servant-reflex/tree/master/testserver). To build these components:
113+
114+
115+First build the library:
116+
117+```
118+git submodule update --init --recursive
119+./build.sh
120+```
121+
122+Then build the test server:
123+
124+```
125+deps/reflex-platform/work-on ./overrides-ghc.nix ./testserver --command "cd testserver && cabal build"
126+```
127+
128+
129+## Running the example site
130+
131+The server must be run from the directory where static assets live:
132+
133+```
134+cd testserver
135+dist/build/back/back -p 8001
136+```
137+
138+And simply browse to `localhost:8001`
139+
140+**For a larger example of a project that shares types between backend and frontend, see [hsnippet](https://github.com/mightybyte/hsnippet).**