Debug

In general, if you run into any issues with Vike, we recommend that you reach out to us.

If you report a Vike bug, then we quickly fix it (usually under 24 hours).

That said, you can also dig into issues yourself.

In some situations, you may want to dig into a problem yourself. For example, if we ask you to provide a minimal reproduction, it might be quicker to dig into Vike's source code instead.

Verbose errors

Vike prettifies transpilation errors, such as errors thrown by esbuild and Babel.

While Vike is careful about not removing relevant information, it may mistakenly do so. In that case create a new GitHub issue. Until a Vike maintainer fixes the issue you can use the debug flag DEBUG=vike:error.

# - Show verbose original errors
# - Show infinite stack traces (`Error.stackTraceLimit = Infinity`)
DEBUG=vike:error npm run dev

For even more information:

# Usually only used by Vike maintainers
DEBUG=vike:error,vike:log npm run dev

Digging into node_modules/

The quickest way to dig into Vike is by:

  • Directly modifying the built code at node_modules/vike/dist/esm/**/*.js, for example to:
    • Inject console.log() to gather insights.
    • Try to fix the bug.
  • Reading the TypeScript source code ($ git clone git@github.com:vikejs/vike), to understand how the code works.

The trick here is to directly modify the built code at node_modules/, while using the TypeScript source code to navigate and read code.

We recommend directly manipulating node_modules/vike/dist/esm/**/*.js because it's simpler and quicker than building Vike. That said, you can also build and then link Vike:

$ git clone git@github.com:vikejs/vike
$ cd vike/vike/
$ pnpm install
$ pnpm run dev
$ cd ../../my-app/
$ pnpm link ../vike/vike/

It may sound scary to dig into foreign source code, but it's sometimes quicker to find the root cause of your problem than treating Vike as a black box. Also:

  • It's more interesting. (Open Source is usually well-written and pleasurable to read.)
  • You may end up being able to make a PR solving your problem and help the whole community.

We recommend this practice not only for Vike, but also for other tools such as Vite.

Vike debug logs

You can use Vike's debug logs to gather insights.

# Inspect Vike's routing
DEBUG=vike:routing npm run dev
# Inspect HTTP Streaming
DEBUG=vike:stream npm run dev
# Inspect errors
DEBUG=vike:error npm run dev
# Inspect logs
DEBUG=vike:log npm run dev
# Combination
DEBUG=vike:log,vike:error,vike:stream npm run dev

These debug logs allow you to understand how Vike thinks of your app. For example, to figure out why your app returns a 404, use vike:routing.

There are more debug logs but these aren't user-friendly as they are meant for Vike maintainers.

For more debug logs, add a comment at #249.

Vite debug logs

To enable Vite's debug logs, set the environment variable DEBUG to vite:*.

$ DEBUG=vite:* npm run dev

See also