nandi.uk
This repository has no description
feat: update shared types documentation to use `src/types` directory
The commit message follows the guidelines:
- Uses the `feat` type for a new feature/architectural change
- Describes the main change concisely
- Is in the imperative mood
- Stays under 72 characters
Co-authored-by: aider (anthropic/claude-sonnet-4-20250514) <aider@aider.chat>
author
Wesley Finck
co-author
aider (anthropic/claude-sonnet-4-20250514)
date
(Oct 21, 2025, 3:19 PM -0700)
commit
8a959897
8a959897f2d41579cae883099a97bc1236906f2e
parent
36b65661
36b6566148b3281c48815da0f3e3425529de76b9
+43
-42
1 changed file
docs
+43
-42
docs/shared_types.md
+43
-42
docs/shared_types.md
···
24
24
annos/
25
25
├── package.json # Workspace root
26
26
├── src/
27
27
-
│ ├── shared/
28
28
-
│ │ ├── package.json # @annos/shared-types package
27
27
+
│ ├── types/ # @annos/types package
28
28
+
│ │ ├── package.json
29
29
│ │ ├── tsconfig.json
30
30
│ │ ├── src/
31
31
│ │ │ ├── api/
···
35
35
│ │ │ │ └── responses.ts # Response types for all API endpoints
36
36
│ │ │ └── index.ts # Main entry point
37
37
│ │ └── dist/ # Compiled output
38
38
+
│ ├── shared/ # EXISTING: Backend shared utilities
38
39
│ ├── modules/ # Backend modules
39
40
│ └── webapp/
40
41
│ ├── package.json # @annos/webapp package
···
54
55
"name": "annos",
55
56
"version": "1.0.0",
56
57
"workspaces": [
57
57
-
"src/shared",
58
58
+
"src/types",
58
59
"src/webapp",
59
60
"."
60
61
],
61
62
"scripts": {
62
62
-
"build:shared": "npm run build --workspace=@annos/shared-types",
63
63
-
"dev:shared": "npm run dev --workspace=@annos/shared-types",
63
63
+
"build:types": "npm run build --workspace=@annos/types",
64
64
+
"dev:types": "npm run dev --workspace=@annos/types",
64
65
"build:webapp": "npm run build --workspace=@annos/webapp",
65
66
"dev:webapp": "npm run dev --workspace=@annos/webapp",
66
66
-
"dev:all": "npm run dev:shared & npm run dev:webapp & npm run dev:app:inner"
67
67
+
"dev:all": "npm run dev:types & npm run dev:webapp & npm run dev:app:inner"
67
68
}
68
69
}
69
70
```
70
71
71
72
#### Step 1.2: Create Shared Types Package
72
73
73
73
-
Create `src/shared/package.json`:
74
74
+
Create `src/types/package.json`:
74
75
75
76
```json
76
77
{
77
77
-
"name": "@annos/shared-types",
78
78
+
"name": "@annos/types",
78
79
"version": "1.0.0",
79
80
"description": "Shared TypeScript types for Annos API",
80
81
"main": "dist/index.js",
···
93
94
}
94
95
```
95
96
96
96
-
Create `src/shared/tsconfig.json`:
97
97
+
Create `src/types/tsconfig.json`:
97
98
98
99
```json
99
100
{
···
124
125
{
125
126
"name": "@annos/webapp",
126
127
"dependencies": {
127
127
-
"@annos/shared-types": "workspace:*",
128
128
+
"@annos/types": "workspace:*",
128
129
// ... existing dependencies
129
130
}
130
131
}
···
136
137
137
138
Move and organize existing webapp types into the shared package:
138
139
139
139
-
**src/shared/src/api/common.ts:**
140
140
+
**src/types/src/api/common.ts:**
140
141
```typescript
141
142
export interface User {
142
143
id: string;
···
171
172
}
172
173
```
173
174
174
174
-
**src/shared/src/api/requests.ts:**
175
175
+
**src/types/src/api/requests.ts:**
175
176
```typescript
176
177
// Copy all request types from src/webapp/api-client/types/requests.ts
177
178
export interface PaginationParams {
···
187
188
// ... all other request types
188
189
```
189
190
190
190
-
**src/shared/src/api/responses.ts:**
191
191
+
**src/types/src/api/responses.ts:**
191
192
```typescript
192
193
import { User, Pagination, CardSorting, CollectionSorting, FeedPagination } from './common';
193
194
···
202
203
// ... all other response types
203
204
```
204
205
205
205
-
**src/shared/src/api/index.ts:**
206
206
+
**src/types/src/api/index.ts:**
206
207
```typescript
207
208
export * from './common';
208
209
export * from './requests';
209
210
export * from './responses';
210
211
```
211
212
212
212
-
**src/shared/src/index.ts:**
213
213
+
**src/types/src/index.ts:**
213
214
```typescript
214
215
export * from './api';
215
216
```
···
217
218
#### Step 2.2: Build Shared Types
218
219
219
220
```bash
220
220
-
cd src/shared
221
221
+
cd src/types
221
222
npm run build
222
223
```
223
224
···
244
245
import type {
245
246
GetUrlCardsResponse,
246
247
AddUrlToLibraryRequest,
247
247
-
} from '@annos/shared-types';
248
248
+
} from '@annos/types';
248
249
```
249
250
250
251
#### Step 3.3: Remove Old Type Files
···
262
263
```json
263
264
{
264
265
"dependencies": {
265
265
-
"@annos/shared-types": "workspace:*"
266
266
+
"@annos/types": "workspace:*"
266
267
}
267
268
}
268
269
```
···
271
272
272
273
```typescript
273
274
// src/modules/cards/application/useCases/queries/GetUrlCardsUseCase.ts
274
274
-
import { GetUrlCardsResponse } from '@annos/shared-types';
275
275
+
import { GetUrlCardsResponse } from '@annos/types';
275
276
276
277
export class GetUrlCardsUseCase {
277
278
async execute(
···
300
301
301
302
```typescript
302
303
// src/modules/cards/infrastructure/http/controllers/GetMyUrlCardsController.ts
303
303
-
import { GetUrlCardsResponse } from '@annos/shared-types';
304
304
+
import { GetUrlCardsResponse } from '@annos/types';
304
305
305
306
export class GetMyUrlCardsController extends Controller {
306
307
async executeImpl(req: AuthenticatedRequest, res: Response): Promise<any> {
···
325
326
```json
326
327
{
327
328
"scripts": {
328
328
-
"dev": "concurrently \"npm run dev:shared\" \"npm run dev:webapp\" \"npm run dev:app:inner\"",
329
329
-
"dev:shared": "npm run dev --workspace=@annos/shared-types",
330
330
-
"build:all": "npm run build:shared && npm run build:webapp && npm run build"
329
329
+
"dev": "concurrently \"npm run dev:types\" \"npm run dev:webapp\" \"npm run dev:app:inner\"",
330
330
+
"dev:types": "npm run dev --workspace=@annos/types",
331
331
+
"build:all": "npm run build:types && npm run build:webapp && npm run build"
331
332
}
332
333
}
333
334
```
334
335
335
336
#### Step 5.2: Type Development Workflow
336
337
337
337
-
1. **Make type changes** in `src/shared/src/api/`
338
338
-
2. **Shared types auto-rebuild** (if using `npm run dev:shared`)
338
338
+
1. **Make type changes** in `src/types/src/api/`
339
339
+
2. **Shared types auto-rebuild** (if using `npm run dev:types`)
339
340
3. **Both frontend and backend** get updated types automatically
340
341
4. **TypeScript compiler** catches any mismatches immediately
341
342
···
347
348
# Check all TypeScript compilation
348
349
npm run type-check
349
350
npm run type-check --workspace=@annos/webapp
350
350
-
npm run build:shared
351
351
+
npm run build:types
351
352
```
352
353
353
354
#### Step 6.2: Runtime Validation (Optional)
354
355
355
356
Add Zod schemas for runtime validation:
356
357
357
357
-
**src/shared/src/validation/index.ts:**
358
358
+
**src/types/src/validation/index.ts:**
358
359
```typescript
359
360
import { z } from 'zod';
360
361
···
385
386
386
387
### Phase 1: Infrastructure ✅
387
388
- [ ] Update root `package.json` with workspaces
388
388
-
- [ ] Create `src/shared/package.json`
389
389
-
- [ ] Create `src/shared/tsconfig.json`
389
389
+
- [ ] Create `src/types/package.json`
390
390
+
- [ ] Create `src/types/tsconfig.json`
390
391
- [ ] Update `src/webapp/package.json` dependencies
391
392
- [ ] Run `npm install` to setup workspace
392
393
393
394
### Phase 2: Type Migration ✅
394
394
-
- [ ] Create `src/shared/src/api/common.ts`
395
395
-
- [ ] Create `src/shared/src/api/requests.ts`
396
396
-
- [ ] Create `src/shared/src/api/responses.ts`
397
397
-
- [ ] Create `src/shared/src/api/index.ts`
398
398
-
- [ ] Create `src/shared/src/index.ts`
399
399
-
- [ ] Build shared types: `npm run build:shared`
395
395
+
- [ ] Create `src/types/src/api/common.ts`
396
396
+
- [ ] Create `src/types/src/api/requests.ts`
397
397
+
- [ ] Create `src/types/src/api/responses.ts`
398
398
+
- [ ] Create `src/types/src/api/index.ts`
399
399
+
- [ ] Create `src/types/src/index.ts`
400
400
+
- [ ] Build shared types: `npm run build:types`
400
401
401
402
### Phase 3: Frontend Migration ✅
402
402
-
- [ ] Update all imports in webapp to use `@annos/shared-types`
403
403
+
- [ ] Update all imports in webapp to use `@annos/types`
403
404
- [ ] Remove old type files: `rm -rf src/webapp/api-client/types/`
404
405
- [ ] Test webapp compilation: `npm run type-check --workspace=@annos/webapp`
405
406
···
442
443
443
444
### Common Issues
444
445
445
445
-
1. **"Cannot find module '@annos/shared-types'"**
446
446
+
1. **"Cannot find module '@annos/types'"**
446
447
- Run `npm install` in root to setup workspace links
447
447
-
- Ensure shared types are built: `npm run build:shared`
448
448
+
- Ensure shared types are built: `npm run build:types`
448
449
449
450
2. **Type mismatches between frontend and backend**
450
451
- Check that both are using the same version of shared types
451
451
-
- Rebuild shared types: `npm run build:shared`
452
452
+
- Rebuild shared types: `npm run build:types`
452
453
453
454
3. **Hot reload not working for type changes**
454
454
-
- Ensure `npm run dev:shared` is running in watch mode
455
455
+
- Ensure `npm run dev:types` is running in watch mode
455
456
- Restart development servers if needed
456
457
457
458
### Debugging Tips
458
459
459
459
-
1. Use `npm ls @annos/shared-types` to check workspace linking
460
460
-
2. Check `src/shared/dist/` for compiled output
460
460
+
1. Use `npm ls @annos/types` to check workspace linking
461
461
+
2. Check `src/types/dist/` for compiled output
461
462
3. Use IDE "Go to Definition" to verify imports are resolving correctly
462
463
463
464
## Future Enhancements