watch

Re-scan automatically when your source files change for a seamless development workflow.

Basic Usage

npx nightfall-css watch --url http://localhost:3000

Watches your source directories for file changes. When a CSS, TSX, JSX, or other relevant file is modified, Nightfall automatically re-scans your running app and regenerates the theme. This keeps your opposite theme in sync during development.

Watched File Types

By default, Nightfall watches for changes to these file types:

  • .css, .scss, .less — Stylesheet changes
  • .tsx, .jsx — Component changes that affect styles
  • .ts, .js — Configuration or utility changes
  • .html — Template changes

Watched Directories

Nightfall watches these directories by default:

# Default watched directories
src/
app/
pages/
components/
styles/

# Ignored by default
node_modules/
.next/
dist/
build/
.nightfall/

Options

npx nightfall-css watch [options]

Options:
  --url <url>          Target URL (required)
  --format <format>    Output format (default: css-variables)
  --output <path>      Output file path
  --preset <name>      Apply a preset
  --debounce <ms>      Debounce delay before re-scan (default: 500)
  --watch-dirs <dirs>  Custom directories to watch
  --ignore <patterns>  Additional ignore patterns
  --routes <paths>     Routes to scan on each change
  --verbose            Show detailed re-scan output

Custom Watch Directories

Override the default watched directories:

npx nightfall-css watch \
  --url http://localhost:3000 \
  --watch-dirs src/styles src/components src/layouts

Output During Watch

Watch mode provides real-time feedback as it detects changes and regenerates:

npx nightfall-css watch --url http://localhost:3000 --verbose

# [watch] Watching src/, app/, styles/
# [watch] Initial scan complete — 24 tokens generated
# [watch] Waiting for changes...
#
# [watch] Changed: src/components/Card.tsx
# [watch] Re-scanning http://localhost:3000...
# [watch] 2 colors changed, 22 unchanged
# [watch] Regenerated ./nightfall-theme.css (18ms)
#
# [watch] Changed: src/styles/globals.css
# [watch] Re-scanning http://localhost:3000...
# [watch] 5 colors changed, 19 unchanged
# [watch] Regenerated ./nightfall-theme.css (22ms)

With Hot Reload

Watch mode pairs perfectly with your dev server's hot reload. When you change a style, your dev server reloads, then Nightfall re-scans the updated page and regenerates the opposite theme — all automatically:

# Terminal 1: Your dev server
npm run dev

# Terminal 2: Nightfall watch mode
npx nightfall-css watch --url http://localhost:3000 --format css-variables

Debounce

Rapid file saves (e.g., from auto-save) are debounced to avoid redundant scans. The default debounce is 500ms. Increase it if your dev server takes longer to rebuild:

# Wait 2 seconds after last change before re-scanning
npx nightfall-css watch --url http://localhost:3000 --debounce 2000