diff --git a/src/apis/frontend_development.md b/src/apis/frontend_development.md new file mode 100644 index 00000000..0e8a6f2c --- /dev/null +++ b/src/apis/frontend_development.md @@ -0,0 +1,71 @@ +# Frontend/UI Development + +Kinode OS can serve a website or web app just like any HTTP webserver. +The preferred method is to upload your static assets on install by placing them in the `pkg` folder. +By convention, `kit` bundles these assets into a directory inside `pkg` called `ui`, but you can call it anything. +You **must** place your `index.html` in the top-level folder. +The structure should look like this: + +``` +my_package +└── pkg + └── ui (can have any name) + ├── assets (can have any name) + └── index.html +``` + +## Serving a Website + +The simplest way to serve a UI is using the `serve_ui` function from `process_lib`: + +``` +serve_ui(&our, "ui").unwrap(); +``` + +This will serve the `index.html` in the specified folder (here, `"ui"`) at the home path of your process. +If your process is called `my_process:my_package:template.os` and your Kinode is running locally on port 8080, +then the UI will be served at `http://localhost:8080/my_process:my_package:template.os`. + +`serve_ui` takes two arguments: `&our` (&Address) and the directory where the UI assets are stored. + +## Development without kit + +The `kit` UI template uses the React framework compiled with Vite. +But you can use any UI framework as long as it generates an `index.html` and associated assets. +To make development easy, your setup should support a base URL and http proxying. + +### Base URL + +All processes in Kinode OS are namespaced by process name in the standard format of `process:package:publisher`. +So if your process is called `my_process:my_package:template.os`, then your process can only bind HTTP paths that start with `/my_process:my_package:template.os`. +Your UI should be developed and compiled with the base URL set to the appropriate process path. + +#### Vite + +In `vite.config.ts` (or `.js`) set `base` to your full process name, i.e. `base: '/my_process:my_package:template.os'`. + +#### Create React App + +In `package.json` set `homepage` to your full process name, i.e. `homepage: '/my_process:my_package:template.os'`. + +### Proxying HTTP Requests + +In UI development, it is very useful to proxy HTTP requests from the in-dev UI to your Kinode. +Below are some examples. + +#### Vite + +Follow the `server` entry in the [kit template](https://github.com/kinode-dao/kit/blob/master/src/new/templates/ui/chat/ui/vite.config.ts#L31-L47) in your own `vite.config.ts`. + +#### Create React App + +In `package.json` set `proxy` to your Kinode's URL, i.e. `proxy: 'http://localhost:8080'`. + +### Making HTTP Requests + +When making HTTP requests in your UI, make sure to prepend your base URL to the request. +For example, if your base URL is `/my_process:my_package:template.os`, then a `fetch` request to `/my-endpoint` would look like this: + +``` +fetch('/my_process:my_package:template.os/my-endpoint') +``` diff --git a/src/chess_app/frontend.md b/src/chess_app/frontend.md index 2577ede9..78c9a686 100644 --- a/src/chess_app/frontend.md +++ b/src/chess_app/frontend.md @@ -14,6 +14,7 @@ When files found in the `ui/` directory, if a `package.json` file is found with The `build:copy` in that file builds the UI and then places the resulting files into the `pkg/ui/` directory where they will be installed by `kit start-package`. This allows your process to fetch them from the virtual filesystem, as all files in `pkg/` are mounted. See the [VFS API overview](../apis/vfs.md) to see how to use files mounted in `pkg/`. +Additional UI dev info can be found [here](./apis/frontend_development.md). Get the chess UI files and place them in the proper place (next to `pkg/`): ```bash diff --git a/src/cookbook/publish_to_web.md b/src/cookbook/publish_to_web.md index e0c62334..f29822c2 100644 --- a/src/cookbook/publish_to_web.md +++ b/src/cookbook/publish_to_web.md @@ -24,6 +24,10 @@ The simplest way to serve a UI is using the `serve_ui` function from `process_li serve_ui(&our, "ui").unwrap(); ``` +This will serve the `index.html` in the specified folder at the home path of your process. +If your process is called `main:my_package:myusername.os` and your Kinode is running locally on port 8080, +then the UI will be served at `http://localhost:8080/main:my_package:myusername.os`. + `serve_ui` takes two arguments: `&our` (&Address) and the directory where the UI assets are stored. By convention, this is the `ui` directory inside of the `pkg` directory that will be uploaded when you install the process. There must be an `index.html` in the `"ui"` directory (or whatever your top-level directory is called). diff --git a/src/kit/build.md b/src/kit/build.md index 79d99208..133161a0 100644 --- a/src/kit/build.md +++ b/src/kit/build.md @@ -34,6 +34,7 @@ There must exist a `ui/package.json` file with `scripts` defined like: "build:copy": "npm run build && npm run copy", ``` +Additional UI dev info can be found [here](./apis/frontend_development.md). To both `build` and `start-package` in one command, use `kit build-start-package`. ## Arguments diff --git a/src/my_first_app/chapter_4.md b/src/my_first_app/chapter_4.md index ba2d4ec2..94554ad1 100644 --- a/src/my_first_app/chapter_4.md +++ b/src/my_first_app/chapter_4.md @@ -346,6 +346,7 @@ Create a new file in `ui/index.html` with the following contents. ``` This is a super barebones `index.html` that provides a form to make requests to the `/api` endpoint. +Additional UI dev info can be found [here](./apis/frontend_development.md). Finally, add one more entry to `manifest.json`: messaging capabilities to the VFS which is required to store and access the UI `index.html`: ```json