From 3f4b775464353c76ddd49fdc40a3485dc9ad4dff Mon Sep 17 00:00:00 2001
From: Logan Jones <logan@ljones.me>
Date: Fri, 28 Mar 2025 11:36:38 -0500
Subject: [PATCH] added frontend readme

---
 frontend/README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 frontend/README.md

diff --git a/frontend/README.md b/frontend/README.md
new file mode 100644
index 0000000..0a2c721
--- /dev/null
+++ b/frontend/README.md
@@ -0,0 +1,59 @@
+# YellowJacket Frontend
+
+This directory contains the frontend for YellowJacket.
+
+## Dependencies
+
+There are a couple of tools that are required to build and use the frontend.
+
+- `vite` for
+  - transpiling typescript
+  - bundling the final "package" that is useb by the webview
+  - running a dev server with hot-reloading
+  - configured with the `vite.config.ts` file in this directory
+- `pnpm` for managing frontend dependency packages
+
+There are a handful of dependency packages that we use directly in the frontend.
+
+- `picocss` for basic CSS while developing
+- `lit` for a simple but powerful wrapper around Web Components
+
+Lastly, there are some dependencies that only benefit development
+
+- `typescript-server` comes bundled with vscode and can be used as an LSP with other editors using `ts_ls`
+  - Used for autocomplete, syntax highlighting, etc.
+  - This can be configured with the `tsconfig.json` file in the root of the project
+    - NOTE: your configuration should align with the `vite` config so you get in-editor feedback that aligns with how the build will be done.
+
+## Development
+
+Ideally, you would use the frontend in the wails app as the frontend depends on the Go bindings generated by Wails.
+You can do this by running `wails dev` in the root of the YellowJacket repo.
+
+If you want to run the frontend standalone, make sure the Wails go bindings have been generated with `wails generate modules`.
+Then, you can run `pnpm dev` to run the vite dev server.
+For more information on what commands are available, refer to `package.json`.
+
+## Code
+
+### Web Components
+
+Our frontend is based off of Web Components, a standard that provides native browser encapsulation of components that can include HTML, CSS and Javascript all together.
+Instead of writing these components manually in Javascript, we utilize `lit` as a wrapper library.
+
+### Typescript
+
+To better integrate with our tooling and to provide a better developer experience with strong typing, we have written all functional frontend code in Typescript.
+Vite serves as our Typescript transpiler.
+
+### Important Files and Directories
+
+NOTE: most of these directories have aliases defined in `tsconfig.json` and `vite.config.ts` so that we may refer to them by shorthand when importing.
+
+- `index.html` and `index.js` is the entrypoint for the frontend. The first page that loads.
+- `wailsjs/go` Go code bindings generated by wails reside here
+- `wailsjs/runtime` the Wails runtime code needed to use Wails features
+- `src` all app code resides here
+- `src/assets` static assets like fonts, images and icons
+- `src/components` lit components that are used to compose the application
+- `src/pages` pages that serve as other entrypoints for the application that can be navigated to