Cursor rule

1---
2description: 
3globs: *.tsx,*.ts
4alwaysApply: false
5---
6 
7# Any inside generic functions
8 
9When building generic functions, you may need to use any inside the function
10body.
11 
12This is because TypeScript often cannot match your runtime logic to the logic
13done inside your types.
14 
15One example:
16 
17```ts
18const youSayGoodbyeISayHello = <TInput extends "hello" | "goodbye">(
19  input: TInput
20): TInput extends "hello" ? "goodbye" : "hello" => {
21  if (input === "goodbye") {
22    return "hello"; // Error!
23  } else {
24    return "goodbye"; // Error!
25  }
26};
27```
28 
29On the type level (and the runtime), this function returns `goodbye` when the
30input is `hello`.
31 
32There is no way to make this work concisely in TypeScript.
33 
34So using `any` is the most concise solution:
35 
36```ts
37const youSayGoodbyeISayHello = <TInput extends "hello" | "goodbye">(
38  input: TInput
39): TInput extends "hello" ? "goodbye" : "hello" => {
40  if (input === "goodbye") {
41    return "hello" as any;
42  } else {
43    return "goodbye" as any;
44  }
45};
46```
47 
48Outside of generic functions, use `any` extremely sparingly.
49 
50# Default exports
51 
52Unless explicitly required by the framework, do not use default exports.
53 
54```ts
55// BAD
56export default function myFunction() {
57  return <div>Hello</div>;
58}
59```
60 
61```ts
62// GOOD
63export function myFunction() {
64  return <div>Hello</div>;
65}
66```
67 
68Default exports create confusion from the importing file.
69 
70```ts
71// BAD
72import myFunction from "./myFunction";
73```
74 
75```ts
76// GOOD
77import { myFunction } from "./myFunction";
78```
79 
80There are certain situations where a framework may require a default export. For
81instance, Next.js requires a default export for pages.
82 
83```tsx
84// This is fine, if required by the framework
85export default function MyPage() {
86  return <div>Hello</div>;
87}
88```
89 
90# Discriminated unions
91 
92Proactively use discriminated unions to model data that can be in one of a few
93different shapes.
94 
95For example, when sending events between environments:
96 
97```ts
98type UserCreatedEvent = {
99  type: "user.created";
100  data: { id: string; email: string };
101};
102 
103type UserDeletedEvent = {
104  type: "user.deleted";
105  data: { id: string };
106};
107 
108type Event = UserCreatedEvent | UserDeletedEvent;
109```
110 
111Use switch statements to handle the results of discriminated unions:
112 
113```ts
114const handleEvent = (event: Event) => {
115  switch (event.type) {
116    case "user.created":
117      console.log(event.data.email);
118      break;
119    case "user.deleted":
120      console.log(event.data.id);
121      break;
122  }
123};
124```
125 
126Use discriminated unions to prevent the 'bag of optionals' problem.
127 
128For example, when describing a fetching state:
129 
130```ts
131// BAD - allows impossible states
132type FetchingState<TData> = {
133  status: "idle" | "loading" | "success" | "error";
134  data?: TData;
135  error?: Error;
136};
137 
138// GOOD - prevents impossible states
139type FetchingState<TData> =
140  | { status: "idle" }
141  | { status: "loading" }
142  | { status: "success"; data: TData }
143  | { status: "error"; error: Error };
144```
145 
146# Enums
147 
148Do not introduce new enums into the codebase. Retain existing enums.
149 
150If you require enum-like behaviour, use an `as const` object:
151 
152```ts
153const backendToFrontendEnum = {
154  xs: "EXTRA_SMALL",
155  sm: "SMALL",
156  md: "MEDIUM",
157} as const;
158 
159type LowerCaseEnum = keyof typeof backendToFrontendEnum; // "xs" | "sm" | "md"
160 
161type UpperCaseEnum = (typeof backendToFrontendEnum)[LowerCaseEnum]; // "EXTRA_SMALL" | "SMALL" | "MEDIUM"
162```
163 
164Remember that numeric enums behave differently to string enums. Numeric enums
165produce a reverse mapping:
166 
167```ts
168enum Direction {
169  Up,
170  Down,
171  Left,
172  Right,
173}
174 
175const direction = Direction.Up; // 0
176const directionName = Direction[0]; // "Up"
177```
178 
179This means that the enum `Direction` above will have eight keys instead of four.
180 
181```ts
182enum Direction {
183  Up,
184  Down,
185  Left,
186  Right,
187}
188 
189Object.keys(Direction).length; // 8
190```
191 
192# Import type
193 
194Use import type whenever you are importing a type.
195 
196Prefer top-level `import type` over inline `import { type ... }`.
197 
198```ts
199// BAD
200import { type User } from "./user";
201```
202 
203```ts
204// GOOD
205import type { User } from "./user";
206```
207 
208The reason for this is that in certain environments, the first version's import
209will not be erased. So you'll be left with:
210 
211```ts
212// Before transpilation
213import { type User } from "./user";
214 
215// After transpilation
216import "./user";
217```
218 
219# Installing packages
220 
221When installing libraries, do not rely on your own training data.
222 
223Your training data has a cut-off date. You're probably not aware of all of the
224latest developments in the JavaScript and TypeScript world.
225 
226This means that instead of picking a version manually (via updating the
227`package.json` file), you should use a script to install the latest version of a
228library.
229 
230```bash
231bun add -D @typescript-eslint/eslint-plugin
232```
233 
234This will ensure you're always using the latest version.
235 
236Prefer to install packages, not in the root, but in the mono repo packages
237 
238# Interface extends
239 
240ALWAYS prefer interfaces when modelling inheritance.
241 
242The `&` operator has terrible performance in TypeScript. Only use it where
243`interface extends` is not possible.
244 
245```ts
246// BAD
247 
248type A = {
249  a: string;
250};
251 
252type B = {
253  b: string;
254};
255 
256type C = A & B;
257```
258 
259```ts
260// GOOD
261 
262interface A {
263  a: string;
264}
265 
266interface B {
267  b: string;
268}
269 
270interface C extends A, B {
271  // Additional properties can be added here
272}
273```
274 
275# Jsdoc
276 
277Use JSDoc comments to annotate functions and types.
278 
279Be concise in JSDoc comments, and only provide JSDoc comments if the function's
280behaviour is not self-evident for a novice developer.
281 
282Use the JSDoc inline `@link` tag to link to other functions and types within the
283same file.
284 
285```ts
286/**
287 * Subtracts two numbers
288 */
289const subtract = (a: number, b: number) => a - b;
290 
291/**
292 * Does the opposite to {@link subtract}
293 */
294const add = (a: number, b: number) => a + b;
295```
296 
297# Naming conventions
298 
299- Use kebab-case for file names (e.g., `my-component.ts`)
300- Use camelCase for variables and function names (e.g., `myVariable`,
301  `myFunction()`)
302- Use UpperCamelCase (PascalCase) for classes, types, and interfaces (e.g.,
303  `MyClass`, `MyInterface`)
304- Use ALL_CAPS for constants and enum values (e.g., `MAX_COUNT`, `Color.RED`)
305- Inside generic types, functions or classes, prefix type parameters with `T`
306  (e.g., `TKey`, `TValue`)
307 
308```ts
309type RecordOfArrays<TItem> = Record<string, TItem[]>;
310```
311 
312# No unchecked access
313 
314If the user has this rule enabled in their `tsconfig.json`, indexing into
315objects and arrays will behave differently from how you expect.
316 
317```ts
318const obj: Record<string, string> = {};
319 
320// With noUncheckedIndexedAccess, value will
321// be `string | undefined`
322// Without it, value will be `string`
323const value = obj.key;
324```
325 
326```ts
327const arr: string[] = [];
328 
329// With noUncheckedIndexedAccess, value will
330// be `string | undefined`
331// Without it, value will be `string`
332const value = arr[0];
333```
334 
335# Optional properties
336 
337Use optional properties extremely sparingly. Only use them when the property is
338truly optional, and consider whether bugs may be caused by a failure to pass the
339property.
340 
341In the example below we always want to pass user ID to `AuthOptions`. This is
342because if we forget to pass it somewhere in the code base, it will cause our
343function to be not authenticated.
344 
345```ts
346// BAD
347type AuthOptions = {
348  userId?: string;
349};
350 
351const func = (options: AuthOptions) => {
352  const userId = options.userId;
353};
354```
355 
356```ts
357// GOOD
358type AuthOptions = {
359  userId: string | undefined;
360};
361 
362const func = (options: AuthOptions) => {
363  const userId = options.userId;
364};
365```
366 
367# Readonly properties
368 
369Use `readonly` properties for object types by default. This will prevent
370accidental mutation at runtime.
371 
372Omit `readonly` only when the property is genuinely mutable.
373 
374```ts
375// BAD
376type User = {
377  id: string;
378};
379 
380const user: User = {
381  id: "1",
382};
383 
384user.id = "2";
385```
386 
387```ts
388// GOOD
389type User = {
390  readonly id: string;
391};
392 
393const user: User = {
394  id: "1",
395};
396 
397user.id = "2"; // Error
398```
399 
400# Return types
401 
402When declaring functions on the top-level of a module, declare their return
403types. This will help future AI assistants understand the function's purpose.
404 
405```ts
406const myFunc = (): string => {
407  return "hello";
408};
409```
410 
411One exception to this is components which return JSX. No need to declare the
412return type of a component, as it is always JSX.
413 
414```tsx
415const MyComponent = () => {
416  return <div>Hello</div>;
417};
418```
419 
420# Throwing
421 
422Think carefully before implementing code that throws errors.
423 
424If a thrown error produces a desirable outcome in the system, go for it. For
425instance, throwing a custom error inside a backend framework's request handler.
426 
427However, for code that you would need a manual try catch for, consider using a
428result type instead:
429 
430```ts
431type Result<T, E extends Error> =
432  | { ok: true; value: T }
433  | { ok: false; error: E };
434```
435 
436For example, when parsing JSON:
437 
438```ts
439const parseJson = (input: string): Result<unknown, Error> => {
440  try {
441    return { ok: true, value: JSON.parse(input) };
442  } catch (error) {
443    return { ok: false, error: error as Error };
444  }
445};
446```
447 
448This way you can handle the error in the caller:
449 
450```ts
451const result = parseJson('{"name": "John"}');
452 
453if (result.ok) {
454  console.log(result.value);
455} else {
456  console.error(result.error);
457}
458```
459