Bug: Project is broken on new install due to dependency conflicts

[alexsys-dev-007]

Apologies for my incompleteness, here, I was in a rush. There were some more issues (I will reiterate the complete list here):

1. Fatal Installation & Dependency Bugs

The npm install command fails immediately due to several conflicts in the package.json file.

• ERESOLVE Conflict (Astro 4 vs. Astro 5): The package.json lists astro@latest (Astro 5) but also includes older packages like @astrojs/vue@^4.5.0 that have a peer dependency on Astro 4. This creates a fatal ERESOLVE error.
• ETARGET Error (Broken node Dependency): The package.json incorrectly lists node as an npm dependency. This causes npm install to fail with an ETARGET error as it tries to download a non-existent Node.js binary.
• Adapter Conflict: The package.json includes both @astrojs/netlify and @astrojs/vercel, which are mutually exclusive.

2. Configuration Bugs

After fixing the dependency issues, the server still fails to start due to errors in the astro.config.mjs file.

• Missing Module Error: The config file imports @astrojs/vercel/serverless at the top, even if the user uninstalls the Vercel package. This causes a Cannot find module crash.
• Broken Logic: The adapter logic is conditional on an environment variable (env.NETLIFY), but this doesn't account for the Vercel import still being present.

3. Runtime & Code Bugs

After fixing the install and config, the dev server crashes when trying to render pages.

• CSS Syntax Error: Header.astro has an @apply rule nested inside an @screen rule, which is invalid syntax and breaks the build.
• Multiple "Cannot read properties of undefined (reading 'data')" Crashes: The src/pages/tag/[...page].astro file is highly prone to crashing:
  • It tries to .sort() posts from getCollection("blog") before filtering out invalid posts (e.g., drafts with no pubDate).
  • It tries to .map() posts to find tags before filtering out invalid posts.
  • It tries to destructure data from getEntry("config", "blog") without checking if the entry was found first.
  • The getStaticPaths function returns an empty array if no posts have tags, which causes the main component to crash because the page prop is undefined.

4. Cache Corruption

• Finally, after fixing all of the above, the dev server's cache is often corrupted from the previous crashes, leading to "ghost" errors like Cannot find module '@layouts/PageLayout.js' (looking for a .js file instead of .astro). This requires a full rm -rf node_modules to fix.

Summary of Fixes

To get the project running, I had to:

1. Edit package.json to remove the node dependency.
2. Edit astro.config.mjs to remove all Vercel imports and hard-code the Netlify adapter.
3. Run rm -rf node_modules package-lock.json.
4. Run npm uninstall @astrojs/vercel.
5. Run npm install @astrojs/vue@latest ... (and all other @astrojs packages) to force them to update to Astro 5-compatible versions.
6. Run npm install to get the remaining packages.
7. Manually add safety checks (e.g., .filter(post => post && post.data)) in tag/[...page].astro to prevent the runtime crashes.

5. Root Cause & Solution

The core issue is that this project is "unlocked," allowing new package versions to break the build. The package-lock.json in the repo is simply a little "rotten" and just needs to be locked down to protect from deprecations/ERESOLVE/ETARGET fatalities.

Solution: After all the dependencies are fixed, the new, working package-lock.json file must be committed to the repo. This will "lock in" the working state (Astro 5, the new Vue, etc.) and ensure that all new users get a reproducible, working build.

Hopefully, this helps save the next person some time! Thanks.