Watch Mode
Rebuild automatically when source files change
Watch Mode
Watch mode rebuilds your project whenever a file in the module graph changes, giving you fast feedback during development. It is driven by Rollup's native watcher.
Watch mode is enabled from the CLI, not from a config option. There is no
top-level watch key in packem.config.ts; watcher tuning lives under
rollup.watch.
Enable Watch Mode
# Long form
packem build --watch
# Short form
packem build -wRun a command after every successful rebuild with --onSuccess (handy for
restarting a server):
packem build --watch --onSuccess "node dist/index.mjs"Tuning the Watcher
Watcher behaviour is configured through rollup.watch, which accepts Rollup's
WatcherOptions. These
options only take effect when the build is started with --watch.
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
export default defineConfig({
transformer,
rollup: {
watch: {
// Restrict which files are watched
include: 'src/**',
exclude: ['**/*.test.ts', 'node_modules/**'],
// Clear the console before each rebuild
clearScreen: true,
// Delay (ms) before a rebuild starts after a change
buildDelay: 0,
// Re-run the build without writing files to disk
skipWrite: false,
},
},
})Supported rollup.watch keys
| Key | Type | Description |
|---|---|---|
include | string | RegExp | (string | RegExp)[] | Limit watching to these files |
exclude | string | RegExp | (string | RegExp)[] | Skip watching these files |
clearScreen | boolean | Clear the screen before each rebuild |
buildDelay | number | Throttle rebuilds by this many milliseconds |
skipWrite | boolean | Run the build but don't write output files |
chokidar | ChokidarOptions | Options passed through to the underlying chokidar watcher |
Polling for problematic file systems
Native file events do not work reliably on some network drives, containers, or virtual machines. Fall back to polling by passing chokidar options:
export default defineConfig({
transformer,
rollup: {
watch: {
chokidar: {
usePolling: true,
interval: 1000,
},
},
},
})CSS in Watch Mode
Imported CSS (and preprocessor) files are part of the module graph, so editing a
watched stylesheet triggers a rebuild automatically. Configure CSS handling
under rollup.css:
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import postcssLoader from '@visulima/packem/css/loader/postcss'
export default defineConfig({
transformer,
rollup: {
css: {
mode: 'extract',
loaders: [postcssLoader],
// Emit source maps while iterating
sourceMap: true,
},
},
})Reacting to Watch Events
There is no dedicated "watch closed" hook. Use the rollup:watch hook to access
the Rollup watcher instance and subscribe to its events (including END and
ERROR) for cleanup or custom logging:
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
export default defineConfig({
transformer,
hooks: {
'rollup:watch': (context, watcher) => {
watcher.on('event', (event) => {
if (event.code === 'END') {
console.log('Rebuild complete')
}
if (event.code === 'ERROR') {
console.error('Rebuild failed:', event.error)
}
})
// Clean up when the process is terminated
process.on('SIGINT', () => {
watcher.close()
process.exit(0)
})
},
},
})Faster Rebuilds
Watch mode reuses Packem's persistent file cache when it is enabled, so unchanged modules are not re-transformed between rebuilds:
export default defineConfig({
transformer,
fileCache: true,
})See file cache for details.
Related Options
- On Success - Run a command after each successful build
- File Cache - Persistent cache for faster rebuilds
- Source Maps - Debug information