Debugging

Analog includes structured debug logging powered by obug. You can enable debug output through the debug option in your Vite config or via the DEBUG environment variable.

The examples below use npm, but the same DEBUG values work with any package manager.

Enabling Debug Output

All scopes, both build and dev

The simplest forms enable all scopes for both build and dev commands. Omitting mode always means both.

// vite.config.ts
import analog from '@analogjs/platform';

export default defineConfig({
  plugins: [
    analog({
      debug: true,
    }),
  ],
});

The object form without mode is equivalent:

analog({
  debug: { scopes: true },
});

Specific scopes, both build and dev

analog({
  debug: ['analog:platform:routes', 'analog:angular:compiler'],
});

// Object form equivalent — omitting mode means both
analog({
  debug: { scopes: ['analog:platform:routes', 'analog:angular:compiler'] },
});

Restrict to build or dev only

Use the mode option to restrict debug output to a single Vite command:

// All scopes, only during development
analog({
  debug: { mode: 'dev' },
});

// All scopes, only during builds
analog({
  debug: { mode: 'build' },
});

// Specific scopes, only during development
analog({
  debug: {
    scopes: ['analog:angular:hmr', 'analog:angular:styles'],
    mode: 'dev',
  },
});

// Specific scopes, only during builds
analog({
  debug: {
    scopes: ['analog:platform:typed-router'],
    mode: 'build',
  },
});

Different scopes per command

Use an array of objects to enable different scopes for build and dev simultaneously:

analog({
  debug: [
    { scopes: ['analog:angular:hmr', 'analog:angular:styles'], mode: 'dev' },
    { scopes: ['analog:platform:typed-router'], mode: 'build' },
  ],
});

You can mix immediate and deferred entries. Entries without mode enable immediately for both commands:

analog({
  debug: [
    { scopes: ['analog:platform'] },
    { scopes: ['analog:angular:hmr'], mode: 'dev' },
    { scopes: ['analog:platform:typed-router'], mode: 'build' },
  ],
});

tip

To enable debug output for both build and dev, omit mode. Any form without mode outputs in both commands.

Environment variable

The DEBUG environment variable works independently of the config option and is always active regardless of mode:

# All Analog scopes
DEBUG=analog:* npm run dev

# Specific scopes
DEBUG=analog:platform:routes,analog:angular:compiler npm run build

# All platform scopes
DEBUG=analog:platform:* npm run dev

Debugging a local Analog checkout from another pnpm workspace

If you want to debug Analog while serving a different app on your machine, point that consumer workspace at the built Analog package outputs under /Volumes/Development/analog/packages/*/dist.

Use the built dist directories, not the raw package roots. Build the packages first so each dist folder contains its generated package.json. The source package manifests still contain catalog: and workspace:* references that are only rewritten during Analog's release-style build pipeline.

Local checkout example

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'libs/**'

catalog:
  '@analogjs/astro-angular': file:/Volumes/Development/analog/packages/astro-angular/dist
  '@analogjs/content': file:/Volumes/Development/analog/packages/content/dist
  '@analogjs/platform': file:/Volumes/Development/analog/packages/platform/dist
  '@analogjs/router': file:/Volumes/Development/analog/packages/router/dist
  '@analogjs/storybook-angular': file:/Volumes/Development/analog/packages/storybook-angular/dist
  '@analogjs/vite-plugin-angular': file:/Volumes/Development/analog/packages/vite-plugin-angular/dist
  '@analogjs/vite-plugin-nitro': file:/Volumes/Development/analog/packages/vite-plugin-nitro/dist
  '@analogjs/vitest-angular': file:/Volumes/Development/analog/packages/vitest-angular/dist

overrides:
  '@analogjs/astro-angular': file:/Volumes/Development/analog/packages/astro-angular/dist
  '@analogjs/content': file:/Volumes/Development/analog/packages/content/dist
  '@analogjs/platform': file:/Volumes/Development/analog/packages/platform/dist
  '@analogjs/router': file:/Volumes/Development/analog/packages/router/dist
  '@analogjs/storybook-angular': file:/Volumes/Development/analog/packages/storybook-angular/dist
  '@analogjs/vite-plugin-angular': file:/Volumes/Development/analog/packages/vite-plugin-angular/dist
  '@analogjs/vite-plugin-nitro': file:/Volumes/Development/analog/packages/vite-plugin-nitro/dist
  '@analogjs/vitest-angular': file:/Volumes/Development/analog/packages/vitest-angular/dist

Root package.json

{
  "dependencies": {
    "@analogjs/platform": "catalog:"
  },
  "overrides": {
    "@analogjs/astro-angular": "file:/Volumes/Development/analog/packages/astro-angular/dist",
    "@analogjs/content": "file:/Volumes/Development/analog/packages/content/dist",
    "@analogjs/platform": "file:/Volumes/Development/analog/packages/platform/dist",
    "@analogjs/router": "file:/Volumes/Development/analog/packages/router/dist",
    "@analogjs/storybook-angular": "file:/Volumes/Development/analog/packages/storybook-angular/dist",
    "@analogjs/vite-plugin-angular": "file:/Volumes/Development/analog/packages/vite-plugin-angular/dist",
    "@analogjs/vite-plugin-nitro": "file:/Volumes/Development/analog/packages/vite-plugin-nitro/dist",
    "@analogjs/vitest-angular": "file:/Volumes/Development/analog/packages/vitest-angular/dist"
  }
}

important

Keep the overrides in both places. If you only pin one Analog package, pnpm will still resolve the rest of the packages in this list from npm instead of your local checkout.

note

Keep your normal dependency entries on catalog: in package.json. pnpm picks those up from pnpm-workspace.yaml. The explicit file: specs are still duplicated in overrides so transitive Analog packages stay pinned to the same local checkout.

The examples above include the full set of published Analog workspace packages that are typically consumed from an app workspace. If you're also testing the create-analog CLI itself, point it at dist/packages/create-analog separately.

Configuration Reference

Form	Scopes	When
true	All	Both build and dev
['scope1', 'scope2']	Listed	Both build and dev
{ scopes: true }	All	Both build and dev
{ scopes: ['scope1'] }	Listed	Both build and dev
{ mode: 'dev' }	All	Dev only
{ mode: 'build' }	All	Build only
{ scopes: ['scope1'], mode: 'dev' }	Listed	Dev only
{ scopes: ['scope1'], mode: 'build' }	Listed	Build only
[{ ..., mode: 'dev' }, { ..., mode: 'build' }]	Per-entry	Split across commands

Available Scopes

@analogjs/platform

Scope	Area
analog:platform	Platform plugin initialization, experimental option resolution, dependency transform config
analog:platform:routes	Route discovery and resolution
analog:platform:content	Content pipeline
analog:platform:typed-router	Typed route generation, file discovery, collisions, watch-mode regeneration
analog:platform:tailwind	Tailwind CSS @reference injection in component styles
analog:platform:style-pipeline	Community style-pipeline plugin registration and platform-level integration

@analogjs/vite-plugin-angular

Scope	Area
analog:angular:hmr	Hot Module Replacement lifecycle, component updates, middleware
analog:angular:styles	Stylesheet processing, externalization, encapsulation
analog:angular:compiler	TypeScript compilation, compiler options
analog:angular:compilation-api	Experimental Angular Compilation API path selection, version checks, incremental updates
analog:angular:tailwind	Tailwind CSS @reference injection via the tailwindCss plugin option
analog:angular:style-pipeline	Reserved for Angular-side style-pipeline resource diagnostics

@analogjs/vite-plugin-nitro

Scope	Area
analog:nitro	Nitro server lifecycle, experimental websocket upgrades
analog:nitro:ssr	Server-side rendering
analog:nitro:prerender	Prerendering

note

When debugging SSR builds that reuse shared plugins, seeing repeated @analogjs/vite-plugin-angular entries in the resolved SSR plugin list can be expected. That SSR duplication is not the same as registering analog() twice in the client build.

Using with @analogjs/vite-plugin-angular standalone

The debug option is also available when using the Angular plugin directly:

import angular from '@analogjs/vite-plugin-angular';

export default defineConfig({
  plugins: [
    angular({
      debug: true,
    }),
  ],
});

When used through analog(), the debug value is forwarded to the Angular plugin automatically.