Devlog 15

Phase 1: Creating the Skeleton and Splitting Components

Overextending the Style Files

The project started as a single page where all HTML, CSS, and JS lived together. When I created the unified BaseLayout.astro, I kept the old global.css. However, that file had specific styles just for the countdown page, which broke the layout of the new homepage.

Cleaning Up Style Pollution

To fix this, I moved the countdown-specific CSS directly into the <style> tag of the countdown page (index.astro). Astro automatically confines these styles to their own page, ensuring they no longer mess up the homepage layout.

Phase 2: Fixing Astro’s Route Misinterpretation

Keeping Scripts in the Wrong Folder

I originally placed the logic script (script.js) inside the src/pages/countdown/ folder to keep it close to the page. During local testing, Astro threw an error saying there was no API route handler for that JavaScript file.

Moving Scripts to a Dedicated Folder

I learned that Astro treats every file inside src/pages/ as a public URL or an API route. To fix this, I moved the file to a new src/scripts/ folder and renamed it countdown.js, keeping the pages folder strictly for actual web pages.

Phase 3: Resolving Build Crashes from File Names

Using Special Characters in Names

Inside my documentation folder, I named a development note file ship#2.md. When I ran npm run build, the entire build process crashed immediately with a path error.

Removing the Broken Characters

The build tool (Vite) treats the # symbol as a URL anchor link, which breaks file path reading. I renamed the file to ship2.md, and the system was able to parse the path and build successfully.

Phase 4: Overcoming the Environment Conflict (Server vs. Client)

Running Browser Code on the Server

This was the biggest challenge. When I imported countdown.js into the page, the build failed multiple times, throwing errors like window is not defined and document is not defined.

Protecting the Code with Environment Guards

Astro runs pages on the server to generate static HTML during the build step. Because Node.js does not have browser features like window or document, the script crashed.

I fixed this with two steps:

1. I imported the script using the ?url suffix in Astro so the server only records its path instead of running it.
2. I wrapped all the browser-specific logic inside a typeof window !== "undefined" check. This ensures the script stays quiet during the server build and only runs once it reaches the user’s browser.