next-dev-qr

A lightweight, zero-config utility to generate a QR code in your terminal when starting the Next.js development server. Perfect for instant mobile testing without manually typing local IP addresses.

Built for modern Next.js (14, 15+), supporting both Webpack and Turbopack.

Features

• 🚀 Zero Friction: Scan and open your dev site on mobile instantly.
• 🛠 Turbopack Ready: Uses the Next.js instrumentation hook to work with the latest compilers.
• 🌐 Smart IP Detection: Automatically finds your local network IP.
• 🧹 Dev-Only: Automatically disables itself in production environments to keep logs clean.

Installation

npm install next-dev-qr
# or
pnpm add next-dev-qr
# or
yarn add next-dev-qr

Usage

Next.js 14.1+ supports an instrumentation file that runs code when the server starts. This is the recommended way to use next-dev-qr.

1. Enable Instrumentation

Ensure your next.config.js allows the instrumentation hook (this is default in Next.js 15).

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
}

module.exports = nextConfig

2. Create the Hook

Create an instrumentation.ts (or .js) file in your root directory (or inside /src if you use it).

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { register: registerQR } = await import('next-dev-qr');
    registerQR();
  }
}

3. Run

Start your server as usual:

npm run dev

The QR code will appear in your terminal immediately after the server initializes.

Why not a Webpack Plugin?

Traditional Next.js plugins modify the Webpack config. However, with the move toward Turbopack (Rust-based compiler), Webpack plugins are being phased out. next-dev-qr uses the Instrumentation API, making it bundler-agnostic and future-proof.

Contributing

This project aims to demonstrate the utility of QR-based mobile debugging for potential inclusion in Next.js core. Feel free to open issues or PRs.

License

MIT