Registry / web-framework / rollup-plugin-dev

rollup-plugin-dev

library2.1.0jsnpmunverified

rollup-plugin-dev is a Rollup plugin that provides a robust development server for local development workflows. The current stable version is 2.1.0, and it follows a feature-driven release cadence. It's built on Fastify, offering a modern, performant, and extensible server solution, distinguishing it from plugins using less active ecosystems like Koa (which it replaced in v2). Key features include detailed request logging, comprehensive proxying capabilities (with path rewriting), support for URL base paths, and automatic server shutdown when Rollup is not in watch mode. It supports single-page application (SPA) fallback routing and provides extensive configuration options for fine-tuning server behavior and integrating custom Fastify plugins.

web-framework

npm install rollup-plugin-dev

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-DEV

rollup-plugin-dev

web-frameworkjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dev

✓ import dev from 'rollup-plugin-dev'

✗ const dev = require('rollup-plugin-dev')

Rollup plugins are typically imported as ES modules in `rollup.config.js` files.

RollupDevOptions

✓ import type { RollupDevOptions } from 'rollup-plugin-dev'

Import types for type-safe configuration in TypeScript projects. The main `dev` function is a default export.

extend option (Fastify plugin)

✓ import fp from 'fastify-plugin'; import dev from 'rollup-plugin-dev'; const myCustomPlugin = fp(async (server, opts) => { /* ... */ }); // ... in rollup.config.js dev({ extend: myCustomPlugin })

When using the `extend` option to customize the Fastify server, the provided function should be a Fastify plugin, often wrapped with `fastify-plugin` for proper encapsulation and scope.

This quickstart configures `rollup-plugin-dev` to serve static files from `public` and `dist` directories, listen on port 3000, enable SPA routing, and proxy API requests.

import dev from 'rollup-plugin-dev'; import path from 'path'; export default { input: 'src/main.ts', output: { dir: 'dist', format: 'esm' }, plugins: [ dev({ dirs: [path.resolve(__dirname, 'public'), path.resolve(__dirname, 'dist')], port: 3000, host: '0.0.0.0', spa: true, // Serves index.html for all non-file requests proxy: [ { from: '/api', to: 'http://localhost:8000/v1' }, { from: '/auth/*', to: 'https://auth.example.com', opts: { rewritePrefix: '/auth' } } ], onListen: (server) => { server.log.info(`Dev server listening on http://${server.server.address().address}:${server.server.address().port}`); } }) ] };

Debug

Known issues

breakingVersion 2.0.0 was a complete rewrite, fundamentally changing the underlying server from Koa to Fastify. This means that any custom server extensions or deeper integrations relying on Koa's API are no longer compatible.

fix

Review your `server` and `extend` options, migrating any Koa-specific logic to Fastify's plugin system or server configuration attributes. Refer to Fastify's documentation.

affects: >=2.0.0

breakingThe `proxy` option configuration changed from an object in v1 to an array of objects in v2. V1's `{ '/v3/*': 'https://polyfill.io' }` syntax is no longer supported.

fix

Update your `proxy` configuration to an array of objects, using `from` and `to` properties. For path rewrites, ensure `opts` are configured correctly for `fastify-http-proxy`. Example: `proxy: [{ from: '/api', to: 'http://localhost:9000/resources' }]`.

affects: >=2.0.0

gotchaThe `extend` option allows full customization of the Fastify server by providing a Fastify plugin. While powerful, misconfigurations or incompatible plugins can lead to unexpected server behavior or errors, as it allows deep modification of the server instance.

fix

Use the `extend` option with caution. Always thoroughly test custom Fastify plugins and refer to Fastify's official documentation for best practices. It is recommended to wrap custom plugins with `fastify-plugin`.

affects: >=2.0.0

gotchaBy default, `rollup-plugin-dev` will automatically turn itself off if Rollup is not running in watch mode. This can be confusing if you expect the server to run during a single build process.

fix

If you need the server to run even outside of Rollup's watch mode (e.g., for a one-off build preview), set the `force: true` option in your plugin configuration.

affects: >=1.0.0

Errors

Common errors & fixes

Error: The 'proxy' option in 'rollup-plugin-dev' must be an array of objects, not an object.

Using the old v1 object-based proxy configuration in v2 or later.

fix

Update the `proxy` option from an object to an array of `{ from: '...', to: '...' }` objects. Example: `proxy: [{ from: '/api', to: 'http://localhost:3000' }]`.

Error: listen EADDRINUSE: address already in use :::8080

Another process is already using the default port 8080 (or the port you specified).

fix

Specify a different `port` option in your plugin configuration, e.g., `dev({ port: 3001 })`. The plugin will attempt to find the next available port if the specified one is busy, but explicitly setting it can prevent confusion.

The fallback file 'index.html' for SPA routing was not found in any of the served directories.

The `spa` option is enabled, but the specified fallback file (defaulting to `index.html`) is not present in any of the directories listed in the `dirs` option.

fix

Ensure that the fallback HTML file is located within one of the `dirs` being served. If `spa` is set to a specific path, e.g., `spa: 'path/to/fallback.html'`, verify that `path/to/fallback.html` is relative to one of your `dirs` entries.

Plugin `rollup-plugin-dev` requires Rollup to be in watch mode to function correctly.

Running Rollup in a single-build mode (e.g., `rollup -c`) without the `--watch` flag, while `rollup-plugin-dev`'s `force` option is `false` (default).

fix

Either run Rollup with the watch flag (`rollup -c --watch`) or explicitly set `force: true` in your `rollup-plugin-dev` configuration if you intend the server to run for a non-watch build.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/pearofducks/rollup-plugin-dev ↗

packagehttps://www.npmjs.com/package/rollup-plugin-dev ↗