Skip to content
Skills Library
Programming · Building & coding

browser-module

/browser-module

Write or change a module's browser half (modules/<name>/browser): a screen, a drawer, a section, a hook, a slice of browser state, a cached read, or a data fetch in the UI. Use when someone says 'add a screen', 'add a drawer', 'where does this component go', 'browser state', 'global UI store', 'defineBrowserModule', 'stale read', 'cache this query', 'polling', 'auto-refresh', 'IndexedDB mirror', 'useUiDeployment', 'can I import another module's component', or 'ui/elements vs blocks vs sections'. Teaches the record (ARCHITECTURE.md section 3.4, 10, 10.2, ADR-169); for the typed data client see

Repository
langwatch ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Write or change a module's browser half (modules/<name>/browser): a screen, a drawer, a section, a hook, a slice of browser state, a cached read, or a data fetch in the UI. Use when someone says 'add a screen', 'add a drawer', 'where does this component go', 'browser state', 'global UI store', 'defineBrowserModule', 'stale read', 'cache this query', 'polling', 'auto-refresh', 'IndexedDB mirror', 'useUiDeployment', 'can I import another module's component', or 'ui/elements vs blocks vs sections'. Teaches the record (ARCHITECTURE.md section 3.4, 10, 10.2, ADR-169); for the typed data client see

Triggers from the description

add a screenadd a drawerwhere does this component gobrowser stateglobal UI storedefineBrowserModulestale readcache this query

Arguments

/browser-module <screen, drawer, hook or state question>
Original author description

Write or change a module's browser half (modules/<name>/browser): a screen, a drawer, a section, a hook, a slice of browser state, a cached read, or a data fetch in the UI. Use when someone says 'add a screen', 'add a drawer', 'where does this component go', 'browser state', 'global UI store', 'defineBrowserModule', 'stale read', 'cache this query', 'polling', 'auto-refresh', 'IndexedDB mirror', 'useUiDeployment', 'can I import another module's component', or 'ui/elements vs blocks vs sections'. Teaches the record (ARCHITECTURE.md section 3.4, 10, 10.2, ADR-169); for the typed data client see

How it works

  1. The shape
  2. Rules that matter
  3. Worked example: a hook over the derived client
  4. Worked example: a routed drawer
  5. Worked example: state and host services
  6. Traps
  7. References
Original SKILL.md headings · 133 lines, 990 words
SKILL.md preview
---
name: browser-module
description: "Write or change a module's browser half (modules/<name>/browser): a screen, a drawer, a section, a hook, a slice of browser state, a cached read, or a data fetch in the UI. Use when someone says 'add a screen', 'add a drawer', 'where does this component go', 'browser state', 'global UI store', 'defineBrowserModule', 'stale read', 'cache this query', 'polling', 'auto-refresh', 'IndexedDB mirror', 'useUiDeployment', 'can I import another module's component', or 'ui/elements vs blocks vs sections'. Teaches the record (ARCHITECTURE.md section 3.4, 10, 10.2, ADR-169); for the typed data client see module-client, for components and tokens see design-system."
user-invocable: true
argument-hint: "<screen, drawer, hook or state question>"
---

# A module's browser half

Read `dev/docs/ARCHITECTURE.md` §3.4, §10 and §10.2. This skill is the short
version. Exemplar: `modules/organization/browser` (screens, drawers, hooks,
features/ nesting, a colocated test). §16 says per row whether the new name has
landed; the declaration is `defineBrowserModule` from `@langwatch/browser`. The declaration stem stays `<name>.web.ts`.

## The shape

```
modules/organization/browser/src/
  organization.web.ts   the declaration; package.json exports ./declaration and nothing else
  model/                pure values and the module's *HostApi contract
  behavior/             hooks, the api binding, stores (organization-api.ts, use-*.ts)
  ui/elements|blocks|sections/
  features/<name>/      a feature owns model/behavior/ui again, one level, past 30 files
  testing.tsx           the module's test harness
```

Imports run one way: entry, then `model`, `behavior`, `ui/elements`,
`ui/blocks`, `ui/sections`. Elements and blocks take props or a query result and
never fetch. A section is where data meets layout. A feature that is one
component is a section, not a feature.

## Rules that matter

Each rule lives in the record; this table only points at it.

| Rule                                                                                          | Record |
| --------------------------------------------------------------------------------------------- | ------ |
| Closed package: exports `./declaration` only; types cross, values do not                      | §3.4   |
| No kits: shared UI to the design system, another module's data to its `<name>-client`         | §3.4   |
| Screens declared with `.withScreens`, guarded by the router, never self-guarded               | §10    |
| Drawers are URL-routed singletons (`?drawer.open=<name>`); the name is the wire               | §10    |
| A screen expects missing data: skeleton in final shape, held data stays, inline Retry         | §3.4   |
| Four state tiers: React Query, router, the one global UI store (`<module>:<key>`), `useState` | §10.2  |
| Every read cached (React Query + IndexedDB mirror); no `staleTime` at a call site             | §10    |
| No polling, but two bounded exceptions (below); visible tabs stay live, hidden tabs make none | §10    |
| Deployment facts from `useUiDeployment()` or the module's `*HostApi`, never env               | §6     |
| Reads take an opaque id plus tenant scope; mutations `setData`, never hand-invalidate         | §10.2  |

**The two polling exceptions** (§10): a refresh interval the user chooses, off by default
(`modules/analytics/browser/src/behavior/use-dashboard-auto-refresh.ts`), and suite freshness
polling only while the live stream is down
(`modules/scenario/browser/src/behavior/suites/use-suite-run-freshness.ts`). Anything else is
a hint over SSE or a cursor-backed read.

Two habits the table does not show: a sub-flow passes `onClose`, never
`closeDrawer` (it clears the stack); an in-app link is
`@langwatch/browser-host/link`, never a bare anchor.

## Worked example: a hook over the derived client

The owner's client is derived from its contract and holds no handwritten procedure map. Clean
example: `modules/identity/client/src/identity-client.ts` (`createModuleApi<ContractApiMap<...>>()`
over the contract's declared procedures, never `AppRouter`). A new module puts its derived hooks in
`modules/<name>/client` (§3.4) and the declaration installs it with
`.withApi(client, { contracts: [...] })` (`installedModuleApis`, §10.1). Every read is mirrored to
disk by default (§10.2); there is no per-read cache policy.

```ts
const query = identityClient.<router>.<procedure>.useQuery({ organizationId }, { enabled });
```

No `invalidate` at the call site: a cursor-backed read goes stale through its key, any other
through SSE hints (§10, "A write makes reads stale through the key").

**Debt, not a model.** `modules/organization/browser/src/behavior/organization-api.ts` calls the
same factory but intersects the derived map with a 500-line handwritten one, and
`use-department-column.ts` hand-invalidates. Do not copy either; when a procedure is missing, add
it to the owner's contract and client.

A read takes an opaque id plus its tenant scope (`projectId`, `organizationId`), never a slug
alone. A query never returns a credential; a secret comes back only from a mutation. A mutation
writes the entity with `setData` instead of invalidating by hand.

## Worked example: a routed drawer

The token (`openDrawer(Token, props)`) opens it; the drawer mounts only while open and passes the
router's callbacks to the design system's callable `Drawer` (props in the `design-system` skill,
`references/component-apis.md`):

```tsx
<Drawer title="Edit score" onClose={onClose} onBack={goBack} size="md" footer={{ primaryAction: { type: "submit", label: "Save" } }} onSubmit={save}>
```

A sub-flow gets `onClose` from its caller, so closing returns to the caller; only the root drawer
calls `closeDrawer`. `dev/docs/best_practices/drawers.md` has the routing detail.

## Worked example: state and host services

One global UI store, owned per module and namespaced `<module>:<key>`:
`defineSlice` from `@langwatch/browser-host/global-store` (`persist` keeps preferences only, never
server data); another module reads with `readSlice` and cannot write. Example:
`defineSlice` in `use-dashboard-auto-refresh.ts`.

A host service has two shapes. A module's own `*HostApi` mount is implemented by the shell and
refused at install if unmounted. A **service the owner provides** is declared with
`defineBrowserModule(name).provides(Service, { load })` and read with `useHostService`; example:
`modules/feature-flag/browser/src/feature-flag.web.ts` and `packages/browser-host/src/feature-flag.ts`.

## Traps

- **Importing a router, `browser-host` internals or another module's browser
  package from a screen.** Read host services through their tokens
  (`useLent`, `useUiDeployment`, `openDrawer(Token, props)`) or the module's `*HostApi`, which
  the shell implements. An unmounted `*HostApi` is refused at install, by name.
- **A `queryFn` that re-enters the cache under its own key** hangs the query
  for the life of the page (§10, by-path dispatch).
- **Sharing by `./surfaces/*` or `./screens/*` exports.** Deleted spellings (§15).
- **Slots, `withCapabilities` for a peer lend, `useDrawer` by bare name, a
  per-module `use-feature-flag.ts` copy.** All in §15. Use a lent component (§10.1),
  `openDrawer(Token, props)` with the owner's drawer token (`navigateToDrawer` is the
  address door) and `@langwatch/browser-host`'s `useFeatureFlag(flag, { projectId })`,
  which keeps its name and is off §15's deleted list (§10.1, Alex 2026-10-05).
- **Host services are not "capabilities".** §3.5 reserves that word for the
  four layers; §16 renames the browser-host list to host services.
- **Any component built by hand.** A banner or alert, dialog, drawer, empty
  state, menu, picker or table comes from `@langwatch/design-system`; a missing
  need is added there first. Errors use the code-keyed presentation (§12),
  never `error.message`.

## References

Host wiring (host services, lending, `*HostApi` mounts, entitlement): §3.3,
§10.1 and the `frontend` skill. Layout of a screen:
`dev/docs/design/guidelines.md` §4. Specs: `specs/ui/ui-page-composition.feature`,
`specs/ui/browser-query-caching.feature`, `specs/ui/in-app-links.feature`.
Tests sit in a colocated `__tests__/` beside the code (§13). The module
anatomy: the `module` skill. The browser half has no generated page yet (plan
`dev/docs/plans/module-readmes-2026-10-06.md` §2); who owns what is on the module's own `README.md`.

Versions

The database has no other skills named browser-module.

Database snapshot: 13.11.2026 · package version 7e3611bf8ae1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100module-client
    Create or use a <name>-client package (modules/<name>/client): the typed tRPC hooks another module's browser reads. Use when someone says 'read another module's data in the browser', 'prompt-client', 'dataset-client', 'a client package', 'createModuleApi', 'ContractApiMap',…
  • 95frontend
    Everything on the browser side of a LangWatch module: createUi and the shell, a module's browser-half layer order (model/behavior/ui), host services vs components (browser-host vs design-system), where shared code goes now that kits are gone (record §3.4), building a new browser…
  • 100create-module
    Step-by-step house pattern for building your own connector module under `modules/` — a self-contained package exporting a module definition plus tools, wired into the server composition. Use whenever integrating a new system ("build a connector for X", "add tools for our API",…
  • 100add-settings-section
    Step-by-step house pattern for giving a module its own user-settings slice — a schema under `profile.modules.<module>`, the show/data/save tool triple, and a settings-page section widget. Use whenever adding or changing persisted user preferences ("make X configurable per user",…
  • 95module-scaffold
    Use when creating a brand new module file in modules/ for a new tool category. Generates the boilerplate with correct array prefix, install_module_<name>() function, and ensures it integrates with install.sh, profiles, and MCP server. Triggers on "new module", "add a module for…
  • 90architecture-first
    Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Use when starting a project, service, site, API, or subsystem; adding a feature with no obvious home; resolving a circular import or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.