Statue setup is supposed to be fast and easy. For most, it is. But not everybody can be so lucky.

To make setup painless for most web developers, we make a few critical assumptions. Check each one by running the following commands and looking for an error.

• Updated versions of Node and the Node Package Manager are installed: npm -v && node -v || echo "node is not set up, use nvm install node"
• The Node Version Manager can be used to fix issues with incompatible Node versioning: nvm install node || echo "nvm is not set up, download and install"
• That users are able and willing to paste bash commands into their terminal: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash || echo "failed to install nvm from github, check out https://github.com/nvm-sh/nvm?tab=readme-ov-file#install--update-script"
• That no other applications or web servers will interfere with npm run dev serving html over a local port: lsof -i 3000 || echo "No other server has the port"
• That the user has superuser authority over the pid using port 3000, or the ability to install lsof if not available: kill -9 $(lsof -t -i:3000) || sudo kill -9 $(lsof -t -i:3000) || echo "cannot kill port 3000 pid
• That they have access to a network or computer capable of installing all the node dependencies and packages.

Environment Issues

Node Version Compatibility

Statue requires Node.js version 18 or higher. Check your version:

node -v

If you're running an older version, use nvm to upgrade:

nvm install 18
nvm use 18

Port Conflicts

The development server runs on port 3000 by default. If you see EADDRINUSE errors, another process is using that port.

Find what's using the port:

lsof -i :3000

Kill the process:

kill -9 $(lsof -t -i:3000)
# or with sudo if needed
sudo kill -9 $(lsof -t -i:3000)

File System Permissions

If you get EACCES errors during installation or build:

# Fix npm permissions (recommended approach)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Add to your shell profile to make permanent
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

Environment Variables

Statue uses SvelteKit's environment variable system. Variables must be prefixed with PUBLIC_ to be exposed to the browser:

# .env file
PUBLIC_SITE_URL=https://yoursite.com
PRIVATE_API_KEY=secret123

If environment variables aren't loading, ensure:

• The .env file is in your project root
• You restart the dev server after changes
• Public variables use the PUBLIC_ prefix

Package Problems

Installation Failures

If npm install fails, try these steps in order:

1. Clear npm cache:

npm cache clean --force

2. Delete lock files and node_modules:

rm -rf node_modules package-lock.json
npm install

3. Use legacy peer deps (for peer dependency conflicts):

npm install --legacy-peer-deps

Missing Dependencies

If you see errors about missing packages like gray-matter, marked, or prismjs:

npm install gray-matter marked prismjs

For TypeScript type errors about missing types:

npm install --save-dev @types/node @types/prismjs

SvelteKit Sync Issues

If you see errors about missing generated files or types:

npm run prepare
# or directly:
npx svelte-kit sync

This generates the .svelte-kit directory with necessary type definitions.

Vite Build Errors

Memory issues during build:

NODE_OPTIONS=--max-old-space-size=4096 npm run build

Module resolution errors: Ensure your vite.config.js has proper alias configuration:

import { sveltekit } from '@sveltejs/kit/vite';

export default {
  plugins: [sveltekit()],
  resolve: {
    alias: {
      $lib: './src/lib'
    }
  }
};

Statue SSG Package Issues

If you're having issues with the statue-ssg package itself:

1. Check version:

npm list statue-ssg

2. Update to latest:

npm update statue-ssg

3. Reinstall:

npm uninstall statue-ssg
npm install statue-ssg

TypeScript Errors

If you see TypeScript errors during npm run check:

Update TypeScript and svelte-check:

npm install --save-dev typescript@latest svelte-check@latest

Ignore specific type checking (not recommended for production): Add // @ts-ignore above problematic lines, but investigate the root cause.

Adapter Issues

If deployment fails, ensure you're using the correct adapter:

For static sites (most common):

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
  kit: {
    adapter: adapter()
  }
};

For other platforms: See SvelteKit adapters documentation.