Skip to content

Commit ce17feb

Browse files
committed
Update coding conventions documentation
1 parent 097a3c0 commit ce17feb

1 file changed

Lines changed: 21 additions & 16 deletions

File tree

  • apps/web/src/app/(docs)/docs/conventions

apps/web/src/app/(docs)/docs/conventions/page.mdx

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -36,22 +36,6 @@ export const trySync = ...;
3636
// isBetweenBigInt
3737
```
3838

39-
## Internal code organization
40-
41-
Separate public and internal code. Use package.json exports to define boundaries clearly.
42-
43-
```ts
44-
// Evolu "public" code.
45-
export * from "./Evolu/Public.js";
46-
47-
// Evolu "internal" code is exported in `package.json`.
48-
"exports": {
49-
"./evolu": {
50-
"import": "./dist/src/local-first/Internal.js"
51-
}
52-
},
53-
```
54-
5539
## Order (top-down readability)
5640

5741
Many developers naturally write code bottom-up, starting with small helpers and building up to the public API. However, Evolu optimizes for reading, not writing, because source code is read far more often than it is written. By presenting the public API first—interfaces and types—followed by the implementation and implementation details, we ensure that the developer-facing contract is immediately clear, making it easier to understand the purpose and structure of the code.
@@ -96,3 +80,24 @@ interface Example {
9680
readonly items: ReadonlyArray<string>;
9781
}
9882
```
83+
84+
## Interface over type
85+
86+
Prefer `interface` over `type` for object shapes. TypeScript shows the interface name rather than expanding the whole structure, making types more readable.
87+
88+
Use `type` only when necessary:
89+
90+
- Union types: `type Status = "pending" | "done"`
91+
- Mapped types, tuples, or type utilities
92+
93+
```ts
94+
// Prefer interface for object shapes.
95+
interface User {
96+
readonly id: string;
97+
readonly name: string;
98+
}
99+
100+
// Use type for unions and utilities.
101+
type Status = "pending" | "done";
102+
type UserKeys = keyof User;
103+
```

0 commit comments

Comments
 (0)