From e02d1974e6195df1efc1c7d02b340d409de804eb Mon Sep 17 00:00:00 2001 From: paanSinghCoder Date: Wed, 3 Jun 2026 17:10:37 +0530 Subject: [PATCH 1/4] 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) --- 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 c63e2497dc..ea1fbc6c3a 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 0000000000..8f9c5227f3 --- /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) From 79b576fee973bb7a16fae00e7d5826dd4973079b Mon Sep 17 00:00:00 2001 From: paanSinghCoder Date: Mon, 8 Jun 2026 14:19:10 +0530 Subject: [PATCH 2/4] docs(web): document embedding the admin app in the server Explain that the Frontier server embeds apps/admin/dist via //go:embed at build time and that the Go build does not rebuild the frontend, so the admin app (and its SDK dependency) must be built first with `make admin-app` to embed the latest UI. Addresses PR review feedback. Co-Authored-By: Claude Opus 4.8 (1M context) --- web/README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/web/README.md b/web/README.md index 8f9c5227f3..c905c94cca 100644 --- a/web/README.md +++ b/web/README.md @@ -77,6 +77,23 @@ 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. +## Embedding the admin app in the server + +The Frontier server embeds the admin dashboard into its binary at build time via +`//go:embed` (see `apps/admin/embed.go`, which embeds `apps/admin/dist`). The Go +build does **not** rebuild the frontend, so the binary serves whatever was last +built into `apps/admin/dist`. To embed the latest admin UI, rebuild it before +building the server. From the repo root: + +```sh +make admin-app # builds apps/admin/dist (the SDK is rebuilt first as a dependency) +make build # builds the Frontier server binary, embedding the fresh dist +``` + +`make admin-app` runs `pnpm build --filter=admin` under the hood; because `admin` +depends on the `@raystack/frontier` SDK, Turbo rebuilds the SDK first, so the +embedded app always picks up the current SDK. + ## Common scripts Run from `frontier/web`: From 35b4c58db90742f038bb9a5ebb6c89f220497803 Mon Sep 17 00:00:00 2001 From: paanSinghCoder Date: Mon, 8 Jun 2026 14:26:33 +0530 Subject: [PATCH 3/4] docs(web): drop client-demo env vars from README Remove the apps/client-demo .env block per review feedback; the client-demo env config is out of scope here. Keeps the backend-config section focused on the admin app's FRONTIER_CONNECTRPC_URL. Co-Authored-By: Claude Opus 4.8 (1M context) --- web/README.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/web/README.md b/web/README.md index c905c94cca..2b3850f128 100644 --- a/web/README.md +++ b/web/README.md @@ -57,9 +57,9 @@ requests to a running Frontier server (see [Configure the backend](#configure-th ### 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`): +The `admin` app talks to a running Frontier instance via a `.env` file at its +root. This file is git-ignored, so create it before starting the dev server. For +a Frontier server running locally with ConnectRPC on `:8002`: `apps/admin/.env` (an `apps/admin/.env.example` is provided as a template): @@ -67,13 +67,6 @@ Frontier server running locally (REST on `:8000`, ConnectRPC on `:8002`): 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. From aca3ccf8312860521082a24793876502518e3ca9 Mon Sep 17 00:00:00 2001 From: paanSinghCoder Date: Mon, 8 Jun 2026 14:28:29 +0530 Subject: [PATCH 4/4] docs(web): restore client-demo env, drop only FRONTIER_ENDPOINT Per review, keep the apps/client-demo .env block but remove only FRONTIER_ENDPOINT; FRONTIER_CONNECT_ENDPOINT stays. Co-Authored-By: Claude Opus 4.8 (1M context) --- web/README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/web/README.md b/web/README.md index 2b3850f128..7e517e78a0 100644 --- a/web/README.md +++ b/web/README.md @@ -57,9 +57,9 @@ requests to a running Frontier server (see [Configure the backend](#configure-th ### Configure the backend -The `admin` app talks to a running Frontier instance via a `.env` file at its -root. This file is git-ignored, so create it before starting the dev server. For -a Frontier server running locally with ConnectRPC on `:8002`: +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 with ConnectRPC on `:8002`: `apps/admin/.env` (an `apps/admin/.env.example` is provided as a template): @@ -67,6 +67,12 @@ a Frontier server running locally with ConnectRPC on `:8002`: FRONTIER_CONNECTRPC_URL=http://localhost:8002/ ``` +`apps/client-demo/.env`: + +```sh +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.