What Went Well
- Framework Choice: Using Astro v4 was the right call given the Node v20 environment. It allowed for rapid development of a multi-page site with minimal boilerplate.
- Tailwind Integration: Manually setting up Tailwind and the Typography plugin went smoothly after the initial
astro addversion conflict, providing a professional look with very little custom CSS. - Dynamic Routing: Implementing dynamic routes for Teams, Retros, and Documentary notes ensured a scalable architecture for future content.
- Content Discovery: The workspace structure was well-organized enough that I could easily locate core design docs and assets for the initial curation.
What Didn’t Go Well
- Node Version Mismatch: The default
create-astro@latestandastro addcommands failed due to Node v20 vs Node v22 requirements. I had to pivot to Astro v4 and manual package installation. - Filename Escaping: Initial use of
\[slug\].astroin shell commands caused build errors because the shell/Astro expected literal brackets[slug].astro. This required a quick rename and rebuild. - Empty Directories: Some team asset directories were empty (Alpha/Beta), making it difficult to feature them prominently on the first pass.
Failure Modes & Bottlenecks
- Interactive Prompts:
create-astroandastro addare inherently interactive. I had to use the--yesand non-interactive flags, and in one case, move a file out of the directory to allow the tool to run in an “empty” folder. - API Timeout: One
create-astroattempt timed out, likely due to a network or registry stall, requiring a retry.
Key Decisions Made
- Astro v4 vs v5/v6: Chose to downgrade to Astro v4 to match the container’s Node version rather than attempting to upgrade the system environment.
- Data/Page Split: Decided to move Markdown files out of
src/pages/intosrc/data/to avoid route collision between the.mdfiles and the dynamic.astrotemplates. - Curated Asset Copying: Chose to copy key hero frames to
public/assets/rather than linking to GCS directly for faster local builds and better control over the site’s visual entry points.
Suggestions for Improvement
- Environment Consistency: Ensuring the container has Node v22+ would allow for the latest Astro 5/6 features (like Content Layer), which is much more powerful for this kind of project.
- Asset Metadata: A standard
meta.jsonin each team’s asset directory describing “Hero Frame 1”, “Character Sheet”, etc., would make automated curation much easier. - Template Pre-population: For future web builders, a pre-configured
package.jsonfor the specific project Node version would save bootstrap time.