From e02d1974e6195df1efc1c7d02b340d409de804eb Mon Sep 17 00:00:00 2001
From: paanSinghCoder <gaurav3017@gmail.com>
Date: Wed, 3 Jun 2026 17:10:37 +0530
Subject: [PATCH] docs(web): add getting-started README for frontier/web

Add a getting-started guide for the web monorepo (apps/admin,
apps/client-demo, the @raystack/frontier SDK, and shared tools), covering
prerequisites, install, dev servers, and per-app .env backend config.
Link to it from the root README under Usage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md     |   4 ++
 web/README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 web/README.md

diff --git a/README.md b/README.md
index c63e2497d..ea1fbc6c3 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,10 @@ frontier reference
 
 Frontier provides a fully-featured GRPC and HTTP API to interact with Frontier server. Both APIs adheres to a set of standards that are rigidly followed. Please refer to [proton](https://github.com/raystack/proton/tree/main/raystack/frontier/v1beta1) for GRPC API definitions.
 
+#### Web
+
+The web frontend — the admin dashboard, the `@raystack/frontier` JS SDK, and a client demo app — lives in [`web/`](web/README.md). See its [README](web/README.md) for setup and local development.
+
 ## Contribute
 
 Development of Frontier happens on GitHub, and we are grateful to the community for contributing bugfixes and
diff --git a/web/README.md b/web/README.md
new file mode 100644
index 000000000..8f9c5227f
--- /dev/null
+++ b/web/README.md
@@ -0,0 +1,101 @@
+# Frontier Web
+
+Frontend monorepo for [Frontier](https://github.com/raystack/frontier). Managed with [pnpm](https://pnpm.io/) workspaces and [Turborepo](https://turbo.build/).
+
+## What's inside
+
+| Package            | Description                                                              |
+| ------------------ | ------------------------------------------------------------------------ |
+| `apps/admin`       | Admin dashboard (Vite + React 19, ConnectRPC, Apsara). Embedded into the Frontier server binary via `embed.go`. |
+| `apps/client-demo` | Reference app demonstrating the `@raystack/frontier` SDK (Vite + React 19). |
+| `sdk`              | `@raystack/frontier` — the JS/React SDK for auth and account components.  |
+| `tools/*`          | Shared `eslint-config` and `tsconfig` presets.                           |
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) `>= 22`
+- [pnpm](https://pnpm.io/) `>= 10.19.0`
+
+## Getting started
+
+```sh
+# from frontier/web
+pnpm install
+```
+
+### Run a dev server
+
+Run everything in parallel:
+
+```sh
+pnpm dev
+```
+
+Or target a single app with a Turbo filter:
+
+```sh
+pnpm dev --filter=admin
+pnpm dev --filter=client-demo
+```
+
+Or run each package directly from its own directory. Build the SDK first, then
+start whichever app you're working on:
+
+```sh
+cd web/sdk
+pnpm build
+
+cd web/apps/admin
+pnpm dev
+
+cd web/apps/client-demo
+pnpm dev
+```
+
+`client-demo` runs at [http://localhost:3000](http://localhost:3000) and proxies API
+requests to a running Frontier server (see [Configure the backend](#configure-the-backend)).
+
+### Configure the backend
+
+Each app talks to a running Frontier instance via a `.env` file at its own root.
+These files are git-ignored, so create them before starting a dev server. For a
+Frontier server running locally (REST on `:8000`, ConnectRPC on `:8002`):
+
+`apps/admin/.env` (an `apps/admin/.env.example` is provided as a template):
+
+```sh
+FRONTIER_CONNECTRPC_URL=http://localhost:8002/
+```
+
+`apps/client-demo/.env`:
+
+```sh
+FRONTIER_ENDPOINT=http://localhost:8000/
+FRONTIER_CONNECT_ENDPOINT=http://localhost:8002/
+```
+
+The `admin` app also reads `configs.dev.json` (served at `/configs` in dev) for
+local config and terminology overrides.
+
+## Common scripts
+
+Run from `frontier/web`:
+
+```sh
+pnpm build      # build all packages
+pnpm lint       # lint all packages
+pnpm clean      # clean build outputs
+pnpm changeset  # create a changeset for releases
+```
+
+The `Makefile` provides shortcuts, including an admin-only build:
+
+```sh
+make build        # install deps + build everything
+make build-admin  # install deps + build only the admin app
+```
+
+## Learn more
+
+- [Frontier documentation](https://frontier.raystack.org/)
+- [`@raystack/frontier` SDK README](./sdk/README.md)