Project setup and structure
- Tool Evaluation Strategy: Choose tools closest to the framework’s ecosystem over feature-rich but distant alternatives. @vite-pwa/astro was the most feature-rich PWA option but chosen because Vite is core to Astro, ensuring long-term support over simpler alternatives like astro-webmanifest or webapp-astro-pwa with maintenance or popularity concerns.
- Configuration Format Evolution: Linting tools have frequently changed configuration formats; both Stylelint and ESLint evolved from JSON to JS and will hopefully include TypeScript soon. TypeScript configurations avoid mixing JavaScript files and provide better editor support, though many plugins still lack TypeScript support and documentation.
- Linting Configuration Approach: Start with all linting rules enabled by default, then selectively customize based on project conflicts and preferences. Adding standards to an existing project is more difficult than lowering them. Starting with strict rules then customizing ensures maximum code quality while maintaining development efficiency.
- Shareable Configuration Management: Maintaining multiple copies of linter configurations across personal and professional projects becomes unsustainable as tools evolve. Implementing shareable configurations eliminates duplication and centralizes maintenance; a future project to research and implement now that configurations are code-based rather than JSON.
- Documentation Organization: Separate documentation files with cross-linking work better than monolithic README files for complex projects. Scanning document filenames provides better overview than maintaining table of contents in single files.
- Framework Migration Strategy: Astro requires React-like thinking patterns despite being different from React. Moving existing code to temporary folders alongside framework templates enables side-by-side comparison during migration, clarifying structural differences and preventing loss of working implementations.
| Criteria | @vite-pwa/astro | astro-webmanifest | webapp-astro-pwa |
|---|---|---|---|
| Ecosystem proximity | Vite core team | Community | Individual |
| Feature completeness | Full PWA + Workbox | Manifest only | Basic PWA |
| Maintenance | Active | Infrequent | Uncertain |
| Long-term support | High confidence | Moderate | Low |
I found during tool evaluation that ecosystem proximity often matters more than features. @vite-pwa/astro integration was selected because it’s maintained by the Vite which is core to Astro’s architectural patterns. Manual SEO tag implementation avoided configuration complexity while providing exactly the needed functionality without unused features.
Configuration format changes in linting tools require ongoing maintenance, particularly when plugin ecosystems lag behind core tool updates. TypeScript configuration support varies significantly across plugins, with some providing excellent type safety while others require guesswork and trial-and-error configuration approaches. This inconsistency makes plugin evaluation more time-consuming but necessary for maintenance.
Managing configurations across multiple projects highlighted the need for shareable configurations. With linting configurations now code-based rather than JSON, implementing shareable configurations should leverage familiar programming concepts for easier maintenance and distribution.
Documentation structure affects both discoverability and maintenance overhead. Single large files become difficult to navigate and update, while well-organized separate files with clear naming conventions improve both developer experience and documentation maintenance.
Developing the website
- Framework Selection Process: SPAs aren't ideal for public websites needing search engine indexing, and adding SSR is a heavy task. Astro and Custom Elements were chosen for static sites with minimal interactivity, working well without framework overhead designed for complex state management.
- Documentation Priority: Writing flexible code requires documenting the “why” for future maintainability. Code will inevitably have different requirements and additional interconnections, so documenting reasoning and writing automated tests ensures stability and prevents difficult future changes.
- Security vs Performance Trade-offs: Default to security when faced with genuine trade-offs, trusting that performance improvements occur over time while security typically degrades without active maintenance. Pursue both when possible, accepting trade-offs only when genuine conflicts exist.
- CSS Framework Concerns: Styling frameworks like Bootstrap and Tailwind can prevent developers from understanding CSS fundamentals and cascade behavior. Too many web developers try to avoid writing CSS rather than embracing the cascade and understanding encapsulation patterns.
- Developer Skill Gaps: The separation between developers who avoid CSS and designers who avoid code creates problematic gaps. More developers should understand design implementation, and more designers should understand CSS and componentization principles.
Documentation purpose, reasoning, and decision making for all projects: solo ones because you cannot remember everything anymore, and team ones because team members will change and the scope will be so wide that no one developer can keep it all in their head. It boils down to the same thing: you cannot know everything. Documenting the reasoning behind technical decisions enables confident modifications when requirements change or new features are needed.
Security-first decision making worked because performance optimizations continue improving through tool updates and hardware advancement, while security posture tends to degrade over time without active maintenance. The PWA implementation exemplified pursuing both objectives without compromise.
Styling framework concerns reflect a broader issue where developers avoid learning fundamental web technologies. Understanding CSS cascade behavior and proper encapsulation techniques provides better long-term solutions than utility-based approaches that abstract away the underlying platform. Everyone should be attempting to learn new skills, maintain existing ones, and keep up to date with development trends; not doing so is a recipe for becoming irrelevant.
Deployment and infrastructure
- Infrastructure as Code Limitations: Infrastructure providers and IaC tools update rapidly, requiring constant maintenance. Workarounds also need documentation so projects can progress while adapting when updates open new solution possibilities.
- Infrastructure Maintenance Scheduling:
Run
terraform planquarterly to identify configuration drift before it becomes unmanageable. Proactive maintenance prevents infrastructure technical debt accumulation and avoids extensive catch-up scenarios when urgent changes are needed. - Tool Mismatch Recognition: Parcel wasn’t a good fit for my static website, requiring too much customization and fighting against the tool’s priorities. S3/CloudFront limitations for directory index files showed AWS priorities don’t align with basic static file server expectations.
- Service Focus Alignment: Static Site Generation isn’t AWS Amplify’s primary focus, but SPA requirements largely overlap with static website needs, providing reasonable future compatibility. Recognition that tools may not perfectly match use cases but can still be viable solutions.
Infrastructure as Code limitations highlight the challenge of managing rapidly evolving cloud services through automation tools. The race between infrastructure providers, IaC tools, and users creates constant maintenance overhead. Documenting bugs and workarounds enables project progress while maintaining the ability to adapt when better solutions become available.
I started scheduling infrastructure maintenance after client projects where stable infrastructure required extensive updates before adding new features. Quarterly Terraform planning catches provider updates, deprecated resources, and configuration drift before they compound into major upgrade projects, saving significant time compared to reactive infrastructure updates.
Tool selection requires understanding that perfect matches rarely exist. Parcel’s focus on application bundling conflicted with static site requirements, while S3/CloudFront’s enterprise focus doesn’t prioritize basic static file server functionality. Amplify provides adequate functionality despite different primary objectives because SPA and static site requirements overlap.
General development principles
- Simplicity Principle: The correct tool is often the simplest; either to write, test, or maintain. Limited ability to predict future requirements means choosing flexible solutions over feature-rich ones that may not match actual needs.
- Flexibility Through Documentation: True flexibility comes from documenting the “why” behind code decisions so future modifications can be made confidently. Code will inevitably require different requirements and interconnections with new systems.
- Feature Addition Restraint: Don’t add features that aren’t necessary unless trivial to implement. Premature optimization and feature addition create maintenance overhead without providing immediate value.
- Predictable Investment Areas: Some investments reliably pay dividends: comprehensive test coverage, clear documentation, and robust error handling. These areas can be prioritized because they consistently reduce future development friction.
The simplicity principle came from recognizing that predicting future requirements remains challenging despite experience. Stakeholder and user responses to projects often surprise developers, making flexibility more valuable than feature completeness. Simple solutions typically adapt better to changing requirements than complex ones optimized for specific scenarios.
Documentation and testing represent reliable investments because code modification requirements are predictable even when specific changes aren’t. Comprehensive test coverage ensures that future changes don’t introduce regressions, while clear documentation enables confident modifications when context has been lost over time.