docs: add frontend developer documentation #6486

Zaimwa9 · 2026-01-07T10:25:24Z

Thanks for submitting a PR! Please check the boxes below:

I have added information to docs/ if required so people know about the feature!
I have filled in the "Changes" section below?
I have filled in the "How did you test this code" section below?
I have used a Conventional Commit title for this Pull Request

Changes

Difference from initial version #6153

All commands in yaml
Added couple of cross-references (mostly RTK)
Split chunky context files
Drafted irrelevant context files
Added .local gateway for environment and configuration files
Added AGENTS.md for Cursor
Refreshed frontend/README.md

How did you test this code?

Yet to be tested with real features
Ran couple of benchmarks related to context token consumption:

Task: Create banner component + API request for buildVersion

  What I need:
  1. How to create an RTK Query endpoint
  2. How to find/check the backend endpoint
  3. Basic component structure

  ---
  BEFORE (flat structure)

  | File                   | Lines | Why loaded                     |
  |------------------------|-------|--------------------------------|
  | quick-reference.md     | 293   | Component patterns, API basics |
  | api-integration.md     | 220   | RTK Query patterns             |
  | backend-integration.md | 277   | Find buildVersion endpoint     |
  | patterns.md            | 545   | API service patterns           |
  | ui-patterns.md         | 171   | Component structure            |

  Total: ~1,506 lines

  ❌ patterns.md loads everything - mobile patterns, CRUD modals, pagination - even though I only need basic API service patterns.

  ---
  AFTER (atomic structure)

  | File                   | Lines | Why loaded                 |
  |------------------------|-------|----------------------------|
  | quick-reference.md     | ~250  | Simplified, cross-refs     |
  | api-integration.md     | 220   | RTK Query patterns         |
  | backend-integration.md | 277   | Find buildVersion endpoint |
  | patterns/api.md        | ~160  | Only API patterns          |
  | ui-patterns.md         | 171   | Component structure        |

  Total: ~1,078 lines

  NOT loaded:
  - patterns/index.md - full example not needed
  - patterns/mobile.md.draft - irrelevant
  - feature-flags/* - not requested
  - forms.md.draft - not a form

  ---
  Comparison

  | Metric             | Before                                   | After | Saved           |
  |--------------------|------------------------------------------|-------|-----------------|
  | Lines              | 1,506                                    | 1,078 | 428 lines (28%) |
  | Irrelevant content | Mobile patterns, CRUD modals, pagination | None  | ✅              |

 Task: Auth form (sign-in + sign-up), email + password, responsive

  What I need:
  1. Form patterns (Yup + Formik validation)
  2. API endpoints for sign-in/sign-up
  3. Responsive UI patterns (Bootstrap)
  4. Error handling for auth failures
  5. State management for switching sign-in ↔ sign-up

  ---
  BEFORE (flat structure)

  | File                   | Lines | Why loaded                              |
  |------------------------|-------|-----------------------------------------|
  | quick-reference.md     | 293   | Bootstrap classes, general patterns     |
  | api-integration.md     | 220   | RTK Query mutations for auth            |
  | backend-integration.md | 277   | Find auth endpoints                     |
  | ui-patterns.md         | 171   | Responsive patterns, tabs for switching |
  | patterns.md            | 545   | Error handling, API patterns            |
  | forms.md               | 130   | Yup + Formik validation                 |

  Total: ~1,636 lines

  ❌ patterns.md loads mobile CRUD patterns, pagination, file downloads - none relevant for auth form
  ❌ forms.md loaded entirely even if only need validation schema example

  ---
  AFTER (atomic structure)

  | File                   | Lines | Why loaded                      |
  |------------------------|-------|---------------------------------|
  | quick-reference.md     | ~250  | Bootstrap classes, simplified   |
  | api-integration.md     | 220   | RTK Query mutations             |
  | backend-integration.md | 277   | Find auth endpoints             |
  | ui-patterns.md         | 171   | Tabs for sign-in/sign-up switch |
  | patterns/api.md        | ~160  | Error handling only             |

  Total: ~1,078 lines

  NOT loaded:
  - patterns/index.md - full example overkill for form
  - patterns/mobile.md.draft - irrelevant
  - feature-flags/* - not requested
  - forms.md.draft - drafted (would need to un-draft if forms are common)

  ---
  Comparison

  | Metric             | Before                                        | After | Saved           |
  |--------------------|-----------------------------------------------|-------|-----------------|
  | Lines              | 1,636                                         | 1,078 | 558 lines (34%) |
  | Irrelevant content | Mobile, pagination, file downloads, full CRUD | None  | ✅              |

for more information, see https://pre-commit.ci

…/claude-context

for more information, see https://pre-commit.ci

…/claude-context

- Add missing developer documentation - Refresh CONTRIBUTING.md - Refresh the PR template - Import developer docs and CONTRIBUTING.md to docs.flagsmith.com

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Matthew Elwell <matthew.elwell@flagsmith.com>

… into docs/backend-frontend-agents-context

vercel · 2026-01-07T10:25:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
flagsmith-frontend-preview	Ready	Preview, Comment	Jan 7, 2026 10:54am
flagsmith-frontend-staging	Ready	Preview, Comment	Jan 7, 2026 10:54am

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
docs	Ignored	Preview	Jan 7, 2026 10:54am

github-actions · 2026-01-07T10:26:38Z

Docker builds report

Image	Build Status	Security report
`ghcr.io/flagsmith/flagsmith-api-test:pr-6486`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-e2e:pr-6486`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-api:pr-6486`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith:pr-6486`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-private-cloud:pr-6486`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-frontend:pr-6486`	Finished ✅	Results ✅

Zaimwa9 · 2026-01-07T10:26:45Z

frontend/.claude/context/feature-flags/project-config.local.md.example

@@ -0,0 +1,25 @@
+# Flagsmith Project Configuration


This part was hardcoded in feature-flags so here it allows for local configuration without leaking

Zaimwa9 · 2026-01-07T10:27:11Z

frontend/.claude/context/forms.md.draft

@@ -0,0 +1,130 @@
+# Form Patterns (Yup + Formik)


Drafted it as it uses Hoxton Mix guidelines I understood 😄

Zaimwa9 · 2026-01-07T10:28:23Z

frontend/.claude/commands/api.md

+description: Generate a new RTK Query API service
+---
+
+<!-- TODO: Update /api-types-sync once OpenAPI schema is ready -->


worth waiting and having it complete

kyle-ssg · 2026-01-07T10:31:25Z

frontend/.claude/context/mobile.md.draft

Sorry, this can be deleted

khvn26 · 2026-01-07T10:46:32Z

@Zaimwa9 Can you check the docs build error? See https://vercel.com/flagsmith/docs/AovF2aVgZoAEMZrYYcnj4uGipEZz#L38

  
  Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
  Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.
  
  Exhaustive list of all broken links found:
  - Broken link on source page path = /project-and-community/development:
     -> linking to CLAUDE.md (resolved as: /project-and-community/CLAUDE.md)
  
      at throwError (/vercel/path0/docs/node_modules/@docusaurus/logger/lib/logger.js:80:11)
      at reportBrokenLinks (/vercel/path0/docs/node_modules/@docusaurus/core/lib/server/brokenLinks.js:250:47)
      at handleBrokenLinks (/vercel/path0/docs/node_modules/@docusaurus/core/lib/server/brokenLinks.js:282:5)
      at executeBrokenLinksCheck (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/buildLocale.js:119:47)
      at /vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/buildLocale.js:94:67
      at Object.async (/vercel/path0/docs/node_modules/@docusaurus/logger/lib/perfLogger.js:42:47)
      at buildLocale (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/buildLocale.js:94:31)
      at async runBuildLocaleTask (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/build.js:98:5)
      at async /vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/build.js:79:13
      at async tryToBuildLocale (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/build.js:75:9)
      at async /vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/build.js:35:9
      at async mapAsyncSequential (/vercel/path0/docs/node_modules/@docusaurus/utils/lib/jsUtils.js:21:24)
      at async Command.build (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/build/build.js:34:5)
      at async Promise.all (index 0)
      at async runCLI (/vercel/path0/docs/node_modules/@docusaurus/core/lib/commands/cli.js:56:5)
      at async file:///vercel/path0/docs/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3
}

kyle-ssg and others added 30 commits October 14, 2025 14:13

Claude context

ba3b42e

Claude context

9746d13

Claude context

5955f25

Add api-sync / optmimise contexts

efedbdc

[pre-commit.ci] auto fixes from pre-commit.com hooks

cae73d7

for more information, see https://pre-commit.ci

Add api-sync / optimise contexts

23a6495

Merge remote-tracking branch 'origin/chore/claude-context' into chore…

af5bfda

…/claude-context

Update contexts

ac641db

Update contexts

0c03b8f

Update contexts

fb2df65

Update contexts

b064e81

Update contexts

27019de

Update contexts

96c81d6

Update contexts

4a3bafa

Update contexts

4b846d9

Merge branch 'main' into chore/claude-context

6cbde85

Update contexts

dd7b743

Update claude contexts

df85873

[pre-commit.ci] auto fixes from pre-commit.com hooks

d4809c4

for more information, see https://pre-commit.ci

Simplify contexts

885cfe0

Merge remote-tracking branch 'origin/chore/claude-context' into chore…

91b542e

…/claude-context

Merge branch 'main' into chore/claude-context

7edc926

Revert makefile changes

5b64f88

- Add AGENTS.md

d9132b3

- Add missing developer documentation - Refresh CONTRIBUTING.md - Refresh the PR template - Import developer docs and CONTRIBUTING.md to docs.flagsmith.com

rename api/README.md

3d7a4aa

fix typo

6df6fc0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix path separators

31e3c5e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix typo

fb75a62

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

clarify migrations squashing recommendation

30a7158

fix grammar

5feac3c

Co-authored-by: Matthew Elwell <matthew.elwell@flagsmith.com>

Zaimwa9 added 3 commits January 7, 2026 09:57

Merge branch 'chore/claude-context' of github.com:Flagsmith/flagsmith…

1fcdb88

… into docs/backend-frontend-agents-context

docs: split-heavy-context-and-created-agents

9c4a74b

docs: basic-readme-for-frontend

6c2fcaf

Zaimwa9 requested review from a team as code owners January 7, 2026 10:25

Zaimwa9 requested review from kyle-ssg and removed request for a team January 7, 2026 10:25

Zaimwa9 requested a review from talissoncosta January 7, 2026 10:25

github-actions bot added front-end Issue related to the React Front End Dashboard docs Documentation updates labels Jan 7, 2026

Zaimwa9 commented Jan 7, 2026

View reviewed changes

kyle-ssg reviewed Jan 7, 2026

View reviewed changes

frontend/.claude/context/mobile.md.draft

Copy link

Member

kyle-ssg Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, this can be deleted

vercel bot had a problem deploying to Preview – docs January 7, 2026 10:45 Failure

docs: fixed-broken-link

ce3e9d4

github-actions bot added docs Documentation updates and removed docs Documentation updates labels Jan 7, 2026

vercel bot deployed to Preview – flagsmith-frontend-preview January 7, 2026 10:53 View deployment

vercel bot deployed to Preview – flagsmith-frontend-staging January 7, 2026 10:54 View deployment

Base automatically changed from docs/agents-and-humans to main January 7, 2026 14:22

matthewelwell requested review from a team as code owners January 7, 2026 14:22

matthewelwell requested review from Holmus and emyller and removed request for a team January 7, 2026 14:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add frontend developer documentation #6486

docs: add frontend developer documentation #6486

Zaimwa9 commented Jan 7, 2026

Uh oh!

vercel bot commented Jan 7, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 7, 2026 •

edited

Loading

Uh oh!

Zaimwa9 Jan 7, 2026

Uh oh!

Zaimwa9 Jan 7, 2026

Uh oh!

Zaimwa9 Jan 7, 2026

Uh oh!

kyle-ssg Jan 7, 2026

Uh oh!

khvn26 commented Jan 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

docs: add frontend developer documentation #6486

Are you sure you want to change the base?

docs: add frontend developer documentation #6486

Conversation

Zaimwa9 commented Jan 7, 2026

Changes

How did you test this code?

Uh oh!

vercel bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docker builds report

Uh oh!

Zaimwa9 Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

kyle-ssg Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

khvn26 commented Jan 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Jan 7, 2026 •

edited

Loading

github-actions bot commented Jan 7, 2026 •

edited

Loading