Cursor rule

1---
2description: TypeScript coding guidelines / style – check when working on TypeScript files
3globs: *.ts, *.tsx
4alwaysApply: false
5---
6# General
7 
8- Prefer 'const myFunc = () => {}' over function declarations.
9- Parallelize async calls where appropriate via `Promise.all` instead of sequential fetches in a `for` loop.
10- No `any` allowed. If the input type is genuinely unknown, use `unknown` and write appropriate logic to narrow the type.
11- Prefer `??` over `||`
12- No unchecked index access (`array[0]` might be `undefined`). Optional chain or check and throw and error (depending on whether it is acceptable for the result to be undefined or not).
13- Don't make formatting corrections to lines you aren't already modifying. Auto-fixing will handle it.
14- Avoid single-letter variable names. e.g. `event`, not `e`. Exception: in `for` loops (e.g. `i` is fine).
15- Variable names are all in `camelCase`. No `SCREAMING_SNAKE_CASE`.
16- Check function and type signatures carefully to understand APIs and what fields are available.
17  For external libraries, these should be available in a type declaration file.
18  Don't guess APIs! Check the signatures.
19 
20# Avoid these!
21 
22- Don't make changes unrelated to the user's requests. You can suggest further changes at the end of your work.
23- Don't get stuck fixing linting errors – stop and ask for help sooner.
24- Don't attempt to run the app. Let the user handle testing.
25 
26# Workspaces
27 
28- The project uses yarn workspaces.
29- If you want to install a dependency, you need to do it in the relevant workspace. e.g. `apps/hash-frontend`.
30- The project
31 
32# Frontend
33 
34- Use React function components
35- Use MUI components for all HTML elements (import from `@mui/material`)
36  - Style using the `sx` prop
37  - Flex boxes should use the `Stack` component
38- Use ApolloClient hooks for fetching from the API (e.g. `useQuery`)
39 
40# Entities
41 
42- An `Entity` is a key primitive in the system. They have types which describe their properties. Each entity can have multiple types.
43 
44## Types
45 
46- A `ClosedMultiEntityType` is the combined schema of the entity types an entity has.
47- When requesting entities from the GraphQL API, via `getEntitySubgraphQuery`, a map of `ClosedMultiEntityType`s is available on
48  `closedMultiEntityTypes` in the return field (so long as `includeEntityTypes: "resolved"` has been passed in the `variables.request` object)
49- To retrieve a specific `ClosedMultiEntityType` from the map, use `getClosedMultiEntityTypeFromMap` imported from `@local/hash-graph-sdk/entity`
50- The property and data types for a given `ClosedMultiEntityType` are available in the `definitions` field returned from the API.
51- Labels for entities (human-readable display strings) can be generated by calling `generateEntityLabel(closedMultiEntityType, entity)`
52- If a `ClosedMultiEntityType` is needed for an arbitrary set of `entityTypeIds`, e.g. for draft/proposed entities, use `getClosedMultiEntityTypesQuery`.
53  It also returns a `closedMultiEntityTypes` and `definitions` fields.
54  This should be an array of arrays, where each entry in the array is a set of entityTypeIds you require a closed type for.
55- To get the `icon` for an entity if required, call `getDisplayFieldsForClosedEntityType(closedMultiEntityType)`.
56 
57## Linked entities
58 
59- A 'subgraph' will contain details of entities and entities linked to it.
60 
61# File organization
62 
63- When exports from a module are only used in one other file, they should be created in a subfolder named after the importing file.
64  e.g.
65 
66```md
67- page.tsx
68- page/header.tsx
69- page/header/header-button.tsx
70- page/sidebar.tsx
71```
72 
73- If a module is used by multiple other files, it should be in a `shared` folder at the highest point at which it is needed in the file tree. e.g.
74 
75```md
76- page.tsx
77- api.tsx
78- shared/types.ts // types is used by both page and api
79```
80