204 lines
4.4 KiB
Markdown
204 lines
4.4 KiB
Markdown
# Project Scaffolder Reference
|
|
|
|
Complete reference for Grey Haven project scaffolding - conventions, specifications, and tooling.
|
|
|
|
---
|
|
|
|
## Navigation
|
|
|
|
| Reference | Description |
|
|
|-----------|-------------|
|
|
| [Grey Haven Conventions](grey-haven-conventions.md) | Naming, structure, and code standards |
|
|
| [Scaffold Specifications](scaffold-specifications.md) | Technical specs for each scaffold type |
|
|
| [Tooling Configurations](tooling-configurations.md) | Config files for Vite, Wrangler, pytest, etc. |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Grey Haven Stack
|
|
|
|
| Layer | Technology | Use Case |
|
|
|-------|------------|----------|
|
|
| **Frontend** | React + Vite + TanStack | Web applications |
|
|
| **Backend** | Cloudflare Workers + Hono | REST/GraphQL APIs |
|
|
| **Database** | PlanetScale PostgreSQL (or D1) | Relational data |
|
|
| **Validation** | Zod (TS), Pydantic (Python) | Type-safe validation |
|
|
| **Testing** | Vitest (TS), pytest (Python) | Unit & integration tests |
|
|
| **Deployment** | Cloudflare Pages + Workers | Global edge deployment |
|
|
|
|
### Naming Conventions
|
|
|
|
```
|
|
Components: PascalCase (Button, UserProfile)
|
|
Files: kebab-case (user-profile.tsx, api-client.ts)
|
|
Variables: camelCase (userId, isActive)
|
|
Constants: UPPER_SNAKE (API_URL, MAX_RETRIES)
|
|
Database: snake_case (user_profiles, api_keys)
|
|
Routes: kebab-case (/api/user-profiles)
|
|
```
|
|
|
|
### Folder Structure
|
|
|
|
```
|
|
src/
|
|
├── routes/ # API endpoints or page routes
|
|
├── components/ # Reusable UI components
|
|
├── services/ # Business logic
|
|
├── utils/ # Pure helper functions
|
|
├── types/ # TypeScript type definitions
|
|
└── lib/ # Third-party integrations
|
|
|
|
tests/ # Mirror src/ structure
|
|
├── routes/
|
|
├── components/
|
|
└── services/
|
|
```
|
|
|
|
### Configuration Standards
|
|
|
|
**TypeScript Projects**:
|
|
- Strict mode enabled
|
|
- ESLint with recommended rules
|
|
- Prettier for formatting
|
|
- Vitest for testing
|
|
- Path aliases (`@/` for src/)
|
|
|
|
**Python Projects**:
|
|
- Python 3.11+
|
|
- uv for package management
|
|
- Ruff for linting
|
|
- mypy for type checking
|
|
- pytest for testing
|
|
|
|
---
|
|
|
|
## Scaffold Templates
|
|
|
|
### Minimum Files Required
|
|
|
|
**Cloudflare Worker**:
|
|
- wrangler.toml
|
|
- package.json
|
|
- tsconfig.json
|
|
- src/index.ts
|
|
- tests/
|
|
|
|
**React App**:
|
|
- package.json
|
|
- vite.config.ts
|
|
- tsconfig.json
|
|
- src/main.tsx
|
|
- src/routes/
|
|
- tests/
|
|
|
|
**Python API**:
|
|
- pyproject.toml
|
|
- app/main.py
|
|
- app/schemas/
|
|
- app/models/
|
|
- tests/
|
|
|
|
---
|
|
|
|
## Tooling Versions
|
|
|
|
### Recommended Versions (2024)
|
|
|
|
```json
|
|
{
|
|
"typescript": "^5.3.0",
|
|
"vite": "^5.0.0",
|
|
"react": "^18.2.0",
|
|
"hono": "^4.0.0",
|
|
"wrangler": "^3.25.0",
|
|
"vitest": "^1.2.0"
|
|
}
|
|
```
|
|
|
|
```toml
|
|
# Python (pyproject.toml)
|
|
[project]
|
|
requires-python = ">=3.11"
|
|
dependencies = [
|
|
"fastapi[standard]>=0.109.0",
|
|
"pydantic>=2.5.0",
|
|
"uvicorn>=0.27.0"
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### DO
|
|
|
|
- ✅ Use TypeScript strict mode
|
|
- ✅ Include tests in scaffold
|
|
- ✅ Configure linting and formatting
|
|
- ✅ Add .gitignore
|
|
- ✅ Include README with setup instructions
|
|
- ✅ Add CI/CD configuration
|
|
- ✅ Use environment variables for secrets
|
|
- ✅ Include health check endpoint
|
|
|
|
### DON'T
|
|
|
|
- ❌ Commit node_modules or .venv
|
|
- ❌ Hard-code secrets or API keys
|
|
- ❌ Skip type definitions
|
|
- ❌ Omit error handling
|
|
- ❌ Forget database migrations
|
|
- ❌ Skip documentation
|
|
|
|
---
|
|
|
|
## Deployment Checklist
|
|
|
|
### Pre-Deployment
|
|
|
|
- [ ] All tests passing
|
|
- [ ] TypeScript/mypy checks pass
|
|
- [ ] Linting passes
|
|
- [ ] Environment variables configured
|
|
- [ ] Database migrations applied
|
|
- [ ] Secrets set in production
|
|
- [ ] Build succeeds
|
|
- [ ] Health check endpoint working
|
|
|
|
### Post-Deployment
|
|
|
|
- [ ] Health check returns 200
|
|
- [ ] API endpoints accessible
|
|
- [ ] Database connections working
|
|
- [ ] Authentication functioning
|
|
- [ ] Monitoring enabled
|
|
- [ ] Error tracking active
|
|
- [ ] Logs accessible
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
### Issue: TypeScript errors after scaffold
|
|
|
|
**Solution**: Run `npm install` and ensure tsconfig.json is correct
|
|
|
|
### Issue: Wrangler fails to deploy
|
|
|
|
**Solution**: Check wrangler.toml config and Cloudflare authentication
|
|
|
|
### Issue: Database connection fails
|
|
|
|
**Solution**: Verify connection string and database credentials
|
|
|
|
### Issue: Tests fail after scaffold
|
|
|
|
**Solution**: Check test setup and mock configuration
|
|
|
|
---
|
|
|
|
**Total References**: 3 comprehensive guides
|
|
**Coverage**: Conventions, specifications, configurations
|
|
**Standards**: Production-ready Grey Haven stack
|