|
| 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