next-qr

Print QR codes for your local Next.js dev server so phones and tablets on the same network can open it instantly.

Install

npm install -D next-qr

next >= 12 is required.

Quick Start

next.config.ts

import withQRCode from 'next-qr';

const nextConfig = {
  reactStrictMode: true,
};

export default withQRCode(nextConfig);

next.config.js / next.config.cjs

const withQRCode = require('next-qr');

module.exports = withQRCode({
  reactStrictMode: true,
});

Run your dev server as usual:

npm run dev

When the dev server is reachable, next-qr prints LAN URLs and QR codes in the terminal.

CLI

next-qr init
next-qr doctor

init can run from the app directory, a nested folder inside the app, or a workspace root when exactly one Next.js app is found.

Flags:

• --skip skips the confirmation prompt
• --force re-injects withQRCode
• --check shows planned changes without writing files
• --quiet reduces non-essential output

Bundler Behavior

withQRCode() detects the dev bundler automatically.

It prefers Turbopack when:

• bundler: "turbopack" is passed
• --turbopack or --turbo is in process.argv
• nextConfig.turbopack is defined
• Next.js major version is 16 or newer

It prefers Webpack when:

• bundler: "webpack" is passed
• --webpack is in process.argv
• the config already has a webpack(...) function

In Turbopack mode, next-qr waits for the dev server port and then prints QR codes. Serializable options use a detached watcher. Function options such as filter and logger use an in-process watcher instead. If the detached watcher cannot resolve the runtime entry, next-qr falls back to the in-process watcher path.

Options

type NextQRCodePluginOptions = {
  bundler?: 'webpack' | 'turbopack' | 'auto';
  enabled?: boolean;
  port?: number;
  path?: string;
  protocol?: 'http' | 'https';
  once?: boolean;
  filter?: (url: string) => boolean;
  logger?: {
    log: (...args: unknown[]) => void;
    warn?: (...args: unknown[]) => void;
  };
  hostFamily?: 'ipv4' | 'ipv6' | 'all';
  includeHosts?: string[];
  excludeHosts?: string[];
  preferInterface?: string;
  startupDelay?: number;
  startupTimeout?: number;
};

Notes:

• enabled disables the integration
• once defaults to true
• once: false is supported in Webpack mode; Turbopack still prints once when the dev server becomes reachable
• port falls back to process.env.PORT, then 3000
• path is optional and usually stays at the root
• protocol defaults to "http" and only needs changing for unusual HTTPS dev setups
• hostFamily defaults to "ipv4"
• includeHosts and excludeHosts match raw interface addresses before URLs are built
• preferInterface changes ordering and the recommended URL
• startupDelay and startupTimeout apply only in Turbopack mode

Examples

Force Webpack:

import withQRCode from 'next-qr';

export default withQRCode({}, { bundler: 'webpack' });

Filter printed URLs:

import withQRCode from 'next-qr';

export default withQRCode({}, { filter: (url) => url.includes('192.168.') });

API

withQRCode(nextConfig, options?)

Wraps a Next.js config and enables QR code printing in development.

new NextQRCodePlugin(options?)

Use the plugin directly if you manage Webpack plugins yourself.

printQRCodes(port, options?)

Prints URLs and QR codes immediately and returns the generated URLs.

getLocalNetworkUrls(port, options?)

Returns LAN URLs without printing anything.

getPreferredNetworkUrl(port, options?)

Returns the first URL after network preference ordering, or null when nothing is reachable.