Throw together a quick readme on building the web app

1 files changed, 57 insertions, 0 deletions

diff --git a/application/README.md b/application/README.md
new file mode 100644
index 0000000..6b967e1
--- /dev/null
+++ b/application/README.md
@@ -0,0 +1,57 @@
+# Keymap Editor - Web Application
+
+This is a single page application currently written in Vue (but I'm starting to
+experiment with porting it to React) to integrate with the Keymap Editor API.
+
+It handles keyboard selection and rendering of parsed keymap data into a visual
+editor. This application is _aware_ of some of the particulars of ZMK, but it
+receives key bindings already parsed into a tree of values and parameters.
+
+## Building
+
+The easiest way to use this is the [hosted version](https://nickcoutsos.github.io/keymap-editor).
+The second easiest is locally, served up via the API itself (in the repo root,
+run `npm run dev` and open `http://localhost:8080` in your browser).
+
+If you must deploy this app to the web then you'll need to take care of building
+it. This requires some configuration, as seen in the [config module](./config.js).
+
+All configuration is provided via environment variables.
+
+Variable          | Description
+------------------|-------------
+`API_BASE_URL`    | Fully qualified publicly accessible URL of the backend API.
+`APP_BASE_URL`    | Fully qualified publicly accessible URL of _this_ app.
+`GITHUB_APP_NAME` | The app name (slug?) of the GitHub app integration (only required if using with GitHub).
+`ENABLE_GITHUB`   | Whether to enable fetching keyboard data from GitHub. Default is false, values `"1"`, `"on"`, `"yes"`, `"true"` are interpreted as `true`.
+`ENABLE_LOCAL`    | Whether to enable fetching keyboard data from locally. Default is false, values `"1"`, `"on"`, `"yes"`, `"true"` are interpreted as `true`.
+
+_Note: choosing to use the GitHub integration in your own environment isn't a
+matter of flipping a switch, you will need to set up your own app in GitHub and
+configure your API accordingly._
+
+With these set you can run the npm build script, e.g.
+
+```bash
+export API_BASE_URL=...
+export APP_BASE_URL=...
+export GITHUB_APP_NAME=...
+export ENABLE_GITHUB=...
+export ENABLE_LOCAL=...
+npm run build
+```
+
+_(make sure you're in this directory, not the repository root!)_
+
+This will have webpack produce bundles in the `dist/` directory which you can
+deploy however you like.
+
+### Deploying to GitHub Pages
+
+On your GitHub repository's settings page, select _Pages_ in the sidebar. Pick a
+branch you want to serve the app from (I use `pages`) and choose the `/ (root)`
+directory. Check out that branch (I have another working repository locally for
+this) locally, or make a new orphaned branch if such a branch doesn't exist, and
+copy the contents of `dist/` to it. Commit and push to the GitHub remote.
+
+If you're not familiar with this it's worth reading up on the [GitHub Pages docs](https://docs.github.com/en/pages).
\ No newline at end of file