Skip to content

Commit b44faef

Browse files
committed
feat(config): add shared configuration architecture for monorepo
Create centralized configuration in .config/ directory: - tsconfig.base.json - Base TypeScript settings (ES2024, strict mode) - tsconfig.build.json - For package builds with declarations - tsconfig.test.json - Relaxed rules for test files - vitest.config.base.mts - Base test runner config with optimal settings - eslint.config.mjs - Comprehensive ESLint flat config v9 - esbuild-inject-import-meta.mjs - Import.meta polyfill for CommonJS Add comprehensive usage documentation: - README.md (145 lines) - Configuration usage guide with examples - QUICK_REFERENCE.md (280 lines) - Developer quick reference - INDEX.md - File index and directory structure Features: - Single source of truth for shared configuration - Packages extend base configs with minimal duplication - TypeScript strict mode with modern best practices - Vitest with isolate:false for performance (2-3x faster) - ESLint with import ordering and Node.js rules Impact: - 50-100 lines saved per package - Consistent configuration across monorepo - Easy maintenance - update once, applies everywhere
1 parent 482b4c1 commit b44faef

File tree

8 files changed

+1240
-0
lines changed

8 files changed

+1240
-0
lines changed

.config/INDEX.md

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Configuration Index
2+
3+
Comprehensive index of all shared configuration files and documentation for the socket-cli monorepo.
4+
5+
## Quick Links
6+
7+
- [Quick Reference](./QUICK_REFERENCE.md) - Copy-paste examples for common use cases
8+
- [Usage Guide](./README.md) - Detailed usage documentation and examples
9+
- [Architecture](../docs/shared-configuration-architecture.md) - Design principles and rationale
10+
- [Migration Guide](../docs/configuration-migration.md) - Step-by-step migration instructions
11+
- [Summary](../docs/configuration-summary.md) - Overview and roadmap
12+
13+
## Configuration Files
14+
15+
### TypeScript
16+
17+
| File | Purpose | Extends | Use When |
18+
|------|---------|---------|----------|
19+
| `tsconfig.base.json` | Base TypeScript configuration | - | All packages should extend this |
20+
| `tsconfig.build.json` | Build outputs with declarations | `tsconfig.base.json` | Need to emit .d.ts files |
21+
| `tsconfig.test.json` | Test files with relaxed rules | `tsconfig.base.json` | Test-specific type checking |
22+
23+
**Key Settings**:
24+
- Target: ES2024
25+
- Module: nodenext
26+
- Strict: true
27+
- exactOptionalPropertyTypes: true
28+
- noUncheckedIndexedAccess: true
29+
30+
### Testing
31+
32+
| File | Purpose | Use When |
33+
|------|---------|----------|
34+
| `vitest.config.base.mts` | Base test runner configuration | All packages with tests |
35+
36+
**Key Settings**:
37+
- Environment: node
38+
- Pool: threads (isolate: false for performance)
39+
- Timeout: 30 seconds
40+
- Coverage: v8 provider with comprehensive settings
41+
42+
### Linting
43+
44+
| File | Purpose | Use When |
45+
|------|---------|----------|
46+
| `eslint.config.mjs` | ESLint flat config for entire monorepo | Applies automatically to all packages |
47+
48+
**Key Features**:
49+
- TypeScript support
50+
- Import ordering (eslint-plugin-import-x)
51+
- Node.js rules (eslint-plugin-n)
52+
- Sort destructured keys
53+
- Biome and .gitignore pattern integration
54+
55+
### Build Utilities
56+
57+
| File | Purpose | Use When |
58+
|------|---------|----------|
59+
| `esbuild-inject-import-meta.mjs` | Import.meta.url polyfill | esbuild configs bundling to CommonJS |
60+
61+
## Documentation Files
62+
63+
### In .config/
64+
65+
| File | Lines | Purpose |
66+
|------|-------|---------|
67+
| `README.md` | 145 | Usage documentation with examples |
68+
| `QUICK_REFERENCE.md` | 280 | Quick copy-paste reference |
69+
| `INDEX.md` | This file | Index of all configuration files |
70+
71+
### In docs/
72+
73+
| File | Lines | Purpose |
74+
|------|-------|---------|
75+
| `shared-configuration-architecture.md` | 287 | Design principles, rationale, patterns |
76+
| `configuration-migration.md` | 297 | Step-by-step migration guide |
77+
| `configuration-summary.md` | 295 | Overview and migration roadmap |
78+
79+
## Common Use Cases
80+
81+
### New Package
82+
83+
1. Create `tsconfig.json` extending base config
84+
2. Create `vitest.config.mts` merging base config
85+
3. No ESLint config needed (root config applies)
86+
87+
See: [Quick Reference](./QUICK_REFERENCE.md) for examples
88+
89+
### Existing Package Migration
90+
91+
1. Read current configs to identify custom settings
92+
2. Replace with extended/merged configs
93+
3. Keep only package-specific overrides
94+
4. Test builds and tests
95+
96+
See: [Migration Guide](../docs/configuration-migration.md) for details
97+
98+
### Custom TypeScript Paths
99+
100+
1. Extend base config
101+
2. Add `compilerOptions.paths` for custom mappings
102+
3. Keep include/exclude specific to package
103+
104+
See: [README.md](./README.md) - "TypeScript - Type Checking Config"
105+
106+
### Custom Test Settings
107+
108+
1. Merge base vitest config
109+
2. Override specific settings (timeout, coverage, etc.)
110+
3. Add setupFiles if needed
111+
112+
See: [README.md](./README.md) - "Vitest - Package Config"
113+
114+
## Directory Layout
115+
116+
```
117+
.config/
118+
├── INDEX.md # This file
119+
├── README.md # Usage guide
120+
├── QUICK_REFERENCE.md # Quick reference
121+
├── tsconfig.base.json # Base TypeScript
122+
├── tsconfig.build.json # Build TypeScript
123+
├── tsconfig.test.json # Test TypeScript
124+
├── vitest.config.base.mts # Base Vitest
125+
├── eslint.config.mjs # ESLint flat config
126+
└── esbuild-inject-import-meta.mjs # Import.meta polyfill
127+
128+
docs/
129+
├── shared-configuration-architecture.md # Design doc
130+
├── configuration-migration.md # Migration guide
131+
└── configuration-summary.md # Summary & roadmap
132+
```
133+
134+
## Configuration Matrix
135+
136+
### TypeScript Config Usage
137+
138+
| Package Type | Config | Extends | Custom Settings |
139+
|-------------|--------|---------|-----------------|
140+
| Simple package | tsconfig.json | `../../.config/tsconfig.base.json` | include/exclude only |
141+
| Package with paths | tsconfig.json | `../../.config/tsconfig.base.json` | + compilerOptions.paths |
142+
| Build package | tsconfig.json | `../../.config/tsconfig.build.json` | + outDir, rootDir |
143+
144+
### Vitest Config Usage
145+
146+
| Package Type | Config | Merges | Custom Settings |
147+
|-------------|--------|---------|-----------------|
148+
| Simple package | vitest.config.mts | `../../.config/vitest.config.base.mts` | include only |
149+
| With setup | vitest.config.mts | base | + setupFiles |
150+
| Custom timeout | vitest.config.mts | base | + testTimeout |
151+
| Custom coverage | vitest.config.mts | base | + coverage.thresholds |
152+
153+
## Key Decisions
154+
155+
### Why isolate: false in Vitest?
156+
157+
- 2-3x performance improvement
158+
- Required for nock HTTP mocking
159+
- Required for vi.mock() module mocking
160+
- Test pollution prevented by proper cleanup
161+
- See [Architecture](../docs/shared-configuration-architecture.md) for details
162+
163+
### Why noUncheckedIndexedAccess?
164+
165+
- Prevents runtime errors from undefined access
166+
- TypeScript best practice
167+
- Enforces defensive programming
168+
- See [Architecture](../docs/shared-configuration-architecture.md) for details
169+
170+
### Why type-aware linting disabled?
171+
172+
- Causes performance issues on large codebases
173+
- Can hang for minutes
174+
- Most type errors caught by TypeScript anyway
175+
- See [Architecture](../docs/shared-configuration-architecture.md) for details
176+
177+
## Migration Status
178+
179+
### Completed
180+
181+
- [x] Shared configuration architecture designed
182+
- [x] Configuration files created
183+
- [x] Documentation written
184+
- [x] Examples provided
185+
186+
### Next Steps
187+
188+
- [ ] Migrate simple packages (socketbin-*, cli-with-sentry, socket)
189+
- [ ] Migrate complex package (cli)
190+
- [ ] Align root configs
191+
- [ ] Update CI/CD if needed
192+
193+
### Migration Order
194+
195+
1. **Phase 2**: Simple packages (4 packages, low risk)
196+
2. **Phase 3**: Complex package (cli, medium risk)
197+
3. **Phase 4**: Root alignment (optional)
198+
199+
## Support
200+
201+
### For Usage Questions
202+
203+
1. Check [Quick Reference](./QUICK_REFERENCE.md) for common patterns
204+
2. Review [README.md](./README.md) for detailed examples
205+
3. Compare with similar packages
206+
207+
### For Migration Questions
208+
209+
1. Check [Migration Guide](../docs/configuration-migration.md)
210+
2. Review [Summary](../docs/configuration-summary.md) for roadmap
211+
3. Check migrated packages for examples
212+
213+
### For Design Questions
214+
215+
1. Review [Architecture](../docs/shared-configuration-architecture.md)
216+
2. Check rationale sections for key decisions
217+
3. Document edge cases for future reference
218+
219+
## Updates
220+
221+
When updating shared configuration:
222+
223+
1. Update the relevant config file in `.config/`
224+
2. Test with a sample package
225+
3. Document breaking changes
226+
4. Update this index if structure changes
227+
5. Notify team of changes
228+
229+
## Version History
230+
231+
- **2024-10-24**: Initial shared configuration architecture created
232+
- 8 configuration files
233+
- 3 documentation files
234+
- Migration guide and roadmap
235+
236+
## See Also
237+
238+
- [Root tsconfig.json](../tsconfig.json) - Root TypeScript config
239+
- [Root vitest.config.mts](../vitest.config.mts) - Root Vitest config
240+
- [Root biome.json](../biome.json) - Biome formatter config
241+
- [packages/cli/.config/](../packages/cli/.config/) - Example of package-specific configs

0 commit comments

Comments
 (0)