Skip to main content

Troubleshooting

Common issues and solutions when working with the minimal template.

Build Fails with "DATA_REPOSITORY not set"​

The build requires the DATA_REPOSITORY environment variable to know where to fetch content from.

Solution: Set the required environment variables before building:

# Local development — create a .env file in apps/web/
DATA_REPOSITORY=https://github.com/your-org/your-content-repo
GH_TOKEN=ghp_your_token_here
GITHUB_BRANCH=main
SITE_URL=https://my-directory.com

For Vercel deployments, add these in the dashboard under Settings > Environment Variables. For GitHub Actions, add them as repository secrets under Settings > Secrets and variables > Actions.

TypeScript Errors After Adding New Components​

When you add or modify components, TypeScript may report errors that were not present before.

Solution: Run the type checker to see all errors at once:

pnpm typecheck

Common causes:

  • Missing type imports — ensure you import types from @ever-works/core
  • Props mismatch — check the component interface for required vs optional props
  • Astro component types — use astro check for Astro-specific type issues
# Run Astro's own checker for .astro file issues
pnpm --filter @ever-works/web-minimal astro check

pnpm Install Fails​

Installation issues are typically caused by Node.js version mismatches or a corrupted store.

Solution:

  1. Verify your Node.js version:

    node --version
    # Should be 22+ (24 LTS recommended)

  2. Clear the pnpm store and reinstall:

    pnpm store prune
    rm -rf node_modules
    rm -rf apps/*/node_modules packages/*/node_modules
    pnpm install

  3. If using nvm or fnm, make sure you are on the correct Node version:

    nvm use 24
    pnpm install

Content Not Loading​

Items, categories, or pages are missing or empty at runtime.

Solution:

  1. Check that the .content/ directory exists in apps/web/:

    ls apps/web/.content/

  2. Verify YAML format — YAML is whitespace-sensitive. Common mistakes include:

    • Using tabs instead of spaces for indentation
    • Missing quotes around values with special characters
    • Incorrect nesting levels

  3. Validate your YAML files:

    # Install a YAML linter
    npx yaml-lint apps/web/.content/.works/works.yml

  4. Check that required fields exist in each item file:

    name: "Item Name"
    slug: "item-name"
    description: "A description."
    status: "approved"
    updated_at: "2026-01-01 00:00"

  5. If using DATA_REPOSITORY, confirm the repo URL and branch are correct and the token has read access.

Plugin Not Working​

A plugin is enabled but its feature does not appear on the site.

Solution:

  1. Check apps/web/src/lib/plugins.config.ts — verify the plugin is listed in the definePlugins array:

    import { definePlugins } from '@ever-works/plugins';
    import { searchPlugin } from '@ever-works/plugin-search';

    export const plugins = definePlugins([
        searchPlugin(),
        // Other plugins...
    ]);

  2. Verify the plugin package is in your dependencies:

    pnpm --filter @ever-works/web-minimal list | grep plugin

  3. Check for missing peer dependencies — plugins may depend on other packages:

    pnpm install

  4. Restart the dev server after changing plugins.config.ts:

    # Stop the current server (Ctrl+C), then:
    pnpm dev:web

E2E Tests Failing​

Playwright tests fail or cannot start.

Solution:

  1. Install Playwright browsers:

    npx playwright install

  2. Make sure the dev server is running (some test configurations expect it):

    pnpm dev:web

  3. Run the tests with verbose output to see what is failing:

    pnpm --filter @ever-works/web-e2e test:e2e --reporter=list

  4. If tests time out, increase the timeout or check that the dev server starts on the expected port (default 4321).

  5. Run a single test file to isolate issues:

    npx playwright test tests/home.spec.ts

Dark Mode Flicker​

A flash of the wrong color scheme appears on page load before dark mode kicks in.

Solution: Add a flash-prevention script in the <head> of your layout, before any stylesheets:

---
// src/layouts/BaseLayout.astro
---
<html>
  <head>
    <script is:inline>
      // Prevent dark mode flash — runs synchronously before paint
      (function () {
        const theme = localStorage.getItem('theme-preference');
        if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
          document.documentElement.classList.add('dark');
        }
      })();
    </script>
    <!-- stylesheets go here -->
  </head>
  <body>
    <slot />
  </body>
</html>

The is:inline directive tells Astro to keep the script inline (not bundled), so it executes before the page paints.

Interactive Components Not Working​

Search bars, filter dropdowns, dark mode toggles, or other interactive elements render but do not respond to user input.

Solution: Astro components are static by default. Interactive components need a client directive to hydrate on the client side:

---
import SearchBar from '../components/SearchBar.tsx';
import DarkModeToggle from '../components/DarkModeToggle.tsx';
---

<!-- Hydrate on page load -->
<SearchBar client:load />

<!-- Hydrate when visible in viewport -->
<DarkModeToggle client:visible />

Available directives:

DirectiveWhen it hydrates
client:loadImmediately on page load
client:idleAfter page has finished initial load
client:visibleWhen the component scrolls into view
client:mediaWhen a CSS media query is met
client:onlySkips server rendering entirely

If you forget the client: directive, the component renders as static HTML with no JavaScript — event handlers will not fire.

Vite Module Runner Timeout​

Build hangs or times out with a message about Vite module runner failing to resolve a deep dependency chain (commonly isomorphic-git).

Solution: Ensure isomorphic-git is externalized in your Astro config:

// astro.config.ts
export default defineConfig({
    vite: {
        ssr: {
            external: ['isomorphic-git'],
        },
    },
});

This prevents Vite from bundling isomorphic-git's deep dependency tree through the module runner, which can time out after 60s.

Port Already in Use​

The dev server fails to start because port 4321 is already taken.

Solution:

# Linux/macOS — find what is using the port
lsof -i :4321

# Windows — find what is using the port
netstat -ano | findstr :4321

# Kill the process or use a different port
pnpm --filter @ever-works/web-minimal dev -- --port 4322

Build Succeeds but Pages Are Empty​

The build completes without errors, but the deployed site shows blank pages.

Solution:

  1. Check the build output:

    ls apps/web/dist/

    You should see index.html and other HTML files.

  2. Verify that content was fetched at build time — look for warnings in the build log about missing content or empty data arrays.

  3. Ensure the output directory in your hosting config points to apps/web/dist, not the monorepo root.