Troubleshooting

Solutions for common issues in Velocity.

Installation Issues

Clear and reinstall dependencies:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Astro 6 requires Node.js 22.12.0+:

node --version  # Should be 22.12.0 or higher

# Using nvm
nvm install 22
nvm use 22

<style>
  @reference "../../styles/global.css";
  h1 { @apply text-2xl; }
</style>

Regenerate types:

pnpm astro sync

pnpm build 2>&1 | grep -i error

Try restarting the dev server:

# Stop with Ctrl+C
pnpm dev

Update types:

pnpm astro sync
pnpm check

Check tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Use <style> without is:global:

<style>
  /* These styles are scoped */
  .my-class { color: red; }
</style>

Add a client directive:

<Counter client:visible />
<Modal client:load />

Use absolute paths from public/ or import:

---
import myImage from '@/assets/image.png';
---

<img src={myImage.src} alt="Description" />

Check that your hosting provider supports Node.js 22+.

Set in your hosting configuration:

NODE_VERSION=22

For static hosting, ensure trailingSlash is configured:

export default defineConfig({
  trailingSlash: 'always', // or 'never'
});