tauri-nuxt-dev

tauri-nuxt-dev

One command to run Tauri + Nuxt in development, with automatic free-port resolution.

Replaces the usual copy-pasted scripts/dev.ts: pick a free port, start Nuxt there, point Tauri at the same URL.

pnpm add -D tauri-nuxt-dev @tauri-apps/cli
# package.json → "dev": "tauri-nuxt-dev"
pnpm dev

Contents

• Why this exists
• Features
• Install
• Quick start
• Configuration (c12)
• CLI
• Recipes
• How it works
• Programmatic API
• Environment variables
• Security
• Migrating from scripts/dev.ts
• Related
• Development
• License

Why this exists

Tauri’s dev flow needs both sides to agree on a URL:

1. Nuxt binds a free port.
2. Tauri loads that exact devUrl.
3. beforeDevCommand starts Nuxt on the same port.

If 3000 is busy, a naive script either crashes or leaves Tauri pointing at the wrong port. This library resolves a free port once, then builds a Tauri --config override so both stay in sync.

preferred port (config / NUXT_PORT / --port / 3000)
        │
        ▼
  get-port-please  ──►  free port
        │
        ├─► beforeDevCommand  (package-manager aware `nuxt:dev`)
        └─► build.devUrl      (http://localhost:<port>)
                │
                ▼
           tauri dev --config <json>

Your on-disk src-tauri/tauri.conf.json is never modified.

Features

• Auto free port via get-port-please
• c12 project config — tauri-nuxt-dev.config.ts or package.json#tauri-nuxt-dev
• Package-manager aware — pnpm / npm / yarn / bun nuxt:dev scripts
• Local Tauri CLI first — resolves @tauri-apps/cli, falls back to PATH
• CLI + library — tauri-nuxt-dev bin, or tauriNuxtDev() in a script
• Safe spawn — no shell: true; shell-quoted beforeDevCommand only

Install

# pnpm
pnpm add -D tauri-nuxt-dev @tauri-apps/cli

# npm
npm i -D tauri-nuxt-dev @tauri-apps/cli

# yarn
yarn add -D tauri-nuxt-dev @tauri-apps/cli

# bun
bun add -d tauri-nuxt-dev @tauri-apps/cli

Requirements

Quick start

1. Add the script

{
  "scripts": {
    "nuxt:dev": "nuxt dev",
    "dev": "tauri-nuxt-dev"
  }
}

2. Run

pnpm dev

If 3000 is free you get http://localhost:3000. If not:

Port 3000 is busy, using port 3001

3. Optional config

// tauri-nuxt-dev.config.ts
import { defineConfig } from 'tauri-nuxt-dev';

export default defineConfig({
  port: 3000,
  nuxt: 'vpr', // or omit to auto-detect `nuxt:dev`
});

Programmatic (same runner)

import { tauriNuxtDev } from 'tauri-nuxt-dev';

process.exitCode = await tauriNuxtDev({ port: 3000 });

Configuration (c12)

Project settings load with c12 — same pattern as genbumppush.

Where config lives

Discovery is rooted at cwd (--cwd / options.cwd).

TypeScript configs: .ts config files load through native ESM when possible, then fall back to the optional peer jiti. Install it if your runtime cannot import the file directly:

pnpm add -D jiti

JSON and package.json#tauri-nuxt-dev configs need no extra dependency.

Resolution order (later wins)

1. Built-in defaults (empty; ports still honor NUXT_PORT / PORT)
2. "tauri-nuxt-dev" key in package.json
3. C12 config file (or the configFile you pass)
4. CLI flags / programmatic options (highest priority)

loadTauriNuxtDevConfig also loads .env via setupDotenv({ cwd }) without overwriting existing env vars. Secrets belong in the environment — not in config files.

TauriNuxtDevConfig fields

Runtime-only options on tauriNuxtDev (cwd, configFile, env, logger, signal) are never read from a config file.

defineConfig

import { defineConfig } from 'tauri-nuxt-dev';

export default defineConfig({
  port: 3000,
  portRange: [3000, 3100],
  host: '0.0.0.0',
  nuxt: 'vpr',
  tauriArgs: ['--features', 'debug'],
});

Same object in package.json:

{
  "tauri-nuxt-dev": {
    "port": 3000,
    "nuxt": "vpr",
    "tauriArgs": ["--features", "debug"]
  }
}

The return type is the package’s own TauriNuxtDevConfig — not c12 internals — so consumer declaration emit stays portable under pnpm (see genbumppush#6).

loadTauriNuxtDevConfig

import { loadTauriNuxtDevConfig } from 'tauri-nuxt-dev';

const config = await loadTauriNuxtDevConfig(process.cwd());

const forced = await loadTauriNuxtDevConfig(process.cwd(), './custom.config.ts', {
  port: 4000,
});

CLI

tauri-nuxt-dev [options] [-- <tauri dev args>]

• Unrecognized flags and everything after -- go to tauri dev.
• CLI flags always win over the config file.

tauri-nuxt-dev
tauri-nuxt-dev --port 4000
tauri-nuxt-dev --config ./tauri-nuxt-dev.config.ts
tauri-nuxt-dev --host 0.0.0.0
tauri-nuxt-dev --nuxt vpr
tauri-nuxt-dev -- --features debug
tauri-nuxt-dev --port 4000 -- --target aarch64-apple-darwin

Recipes

Vite+ / vpr template

// tauri-nuxt-dev.config.ts
import { defineConfig } from 'tauri-nuxt-dev';

export default defineConfig({ nuxt: 'vpr' });

or

tauri-nuxt-dev --nuxt vpr

await tauriNuxtDev({ nuxt: ['vpr', 'nuxt:dev'] });

Device / mobile testing (bind all interfaces)

tauri-nuxt-dev --host 0.0.0.0

Nuxt gets --host 0.0.0.0. Tauri’s devUrl still uses localhost so the webview can connect (0.0.0.0 / :: are mapped automatically).

Force a port or range

import { defineConfig } from 'tauri-nuxt-dev';

export default defineConfig({
  port: 4000,
  portRange: [4000, 4100],
});

Programmatic runner with abort + custom logger

import { tauriNuxtDev } from 'tauri-nuxt-dev';

const code = await tauriNuxtDev({
  cwd: process.cwd(),
  configFile: './tauri-nuxt-dev.config.ts',
  port: 3000,
  host: '0.0.0.0',
  nuxt: 'vpr',
  tauriArgs: ['--features', 'debug'],
  env: { FOO: 'bar' },
  logger: {
    info: (m) => console.info(m),
    warn: (m) => console.warn(m),
    error: (m) => console.error(m),
  },
  signal: AbortSignal.timeout(60_000),
});

process.exitCode = code;

How it works

1. Load c12 config (file / package.json + CLI/API overrides).
2. Resolve a free port with get-port-please
   preferred → fallback range [port, port+99].
3. Build the Nuxt command (package-manager aware — see below).
4. Build a one-off Tauri config override:

   {
     "build": {
       "devUrl": "http://localhost:<port>",
       "beforeDevCommand": "<nuxt command> --port <port>"
     }
   }
   

5. Spawn tauri dev --config <json> with shell: false.
6. Forward signals (SIGINT / SIGTERM / AbortSignal) and resolve with the child exit code (0 on clean signal exit).

# equivalent shape of what the runner passes to Tauri
tauri dev --config '{"build":{"devUrl":"http://localhost:3001","beforeDevCommand":"pnpm run nuxt:dev -- --port 3001"}}'

Package-manager aware Nuxt command

With "nuxt:dev": "nuxt dev" in package.json:

Fallbacks when there is no nuxt:dev script:

1. Local nuxt package → node <nuxt-bin> dev …
2. nuxt dev on PATH

Package-manager detection order: packageManager field → lockfile (pnpm-lock.yaml, yarn.lock, bun.lockb/bun.lock, package-lock.json) → npm_config_user_agent → npm.

Programmatic API

import {
  // runner + config
  tauriNuxtDev,
  defineConfig,
  loadTauriNuxtDevConfig,
  toConfigOverrides,
  defaults,
  // ports
  resolveDevPort,
  parsePort,
  // Tauri config payload
  buildTauriDevConfig,
  serializeTauriDevConfig,
  toBrowserHost,
  // Nuxt command
  resolveNuxtDevCommandArgs,
  formatShellCommand,
  shellQuote,
  // resolution helpers
  detectPackageManager,
  resolveLocalNuxtBin,
  resolveTauriCli,
} from 'tauri-nuxt-dev';

tauriNuxtDev(options?): Promise<number>

End-to-end: load config → free port → spawn tauri dev → return exit code.

interface Logger {
  info: (message: string) => void;
  warn: (message: string) => void;
  error: (message: string) => void;
}

Ports

import { resolveDevPort, parsePort } from 'tauri-nuxt-dev';

const port = await resolveDevPort(
  { port: 3000, portRange: [3000, 3100], host: '127.0.0.1' },
  process.env,
);

parsePort('3000'); // 3000
parsePort('0'); // undefined
parsePort('abc'); // undefined

parsePort accepts a string or number and returns undefined outside 1..65535.

Tauri config payload

import { buildTauriDevConfig, serializeTauriDevConfig, toBrowserHost } from 'tauri-nuxt-dev';

const config = buildTauriDevConfig({
  port: 3000,
  host: '0.0.0.0',
  beforeDevCommand: 'pnpm run nuxt:dev -- --port 3000 --host 0.0.0.0',
});
// { build: { devUrl: 'http://localhost:3000', beforeDevCommand: '…' } }

serializeTauriDevConfig(config); // JSON string for `--config`
toBrowserHost('::1'); // '[::1]'
toBrowserHost('0.0.0.0'); // 'localhost'

Nuxt command helpers

import { resolveNuxtDevCommandArgs, formatShellCommand, shellQuote } from 'tauri-nuxt-dev';

const args = resolveNuxtDevCommandArgs({
  cwd: process.cwd(),
  port: 4000,
  host: '0.0.0.0',
});
// ['pnpm', 'run', 'nuxt:dev', '--', '--port', '4000', '--host', '0.0.0.0']

formatShellCommand(args);
// 'pnpm run nuxt:dev -- --port 4000 --host 0.0.0.0'

shellQuote('hello world'); // "'hello world'" (POSIX)
shellQuote('hello world', 'win32'); // '"hello world"' (cmd.exe)

Resolution helpers

import { detectPackageManager, resolveLocalNuxtBin, resolveTauriCli } from 'tauri-nuxt-dev';

detectPackageManager('/path/to/app');
// { name: 'pnpm', packageJsonPath: '…/package.json', scripts: { … } }

resolveLocalNuxtBin();
// absolute path to nuxt bin, or undefined

resolveTauriCli();
// local: { command: process.execPath, prefixArgs: [entry], source: 'local' }
// path:  { command: 'tauri', prefixArgs: [], source: 'path' }

Local Tauri CLI is spawned as node <resolved-entry> … (no shell, cross-platform).

Environment variables

Security

• Child processes use shell: false.
• Local Tauri CLI runs via node <resolved-entry>, not a shell string.
• Ports are validated as safe integers in 1..65535.
• devUrl hosts are validated; wildcard binds map to localhost and bare IPv6 is bracketed.
• beforeDevCommand is a shell string only because Tauri requires one; argv tokens are shell-quoted for the platform (sh/POSIX single quotes on Unix, cmd.exe double quotes on Windows).
• Unknown CLI args are argv passthrough to tauri dev, not shell interpolation.
• .env is loaded without overwriting existing environment variables.

Report vulnerabilities via GitHub Security Advisories.

Migrating from scripts/dev.ts

Before — hand-rolled port scan + spawn in a template script.

After — config + one line:

// tauri-nuxt-dev.config.ts
import { defineConfig } from 'tauri-nuxt-dev';

export default defineConfig({ nuxt: 'vpr' });

{
  "scripts": {
    "dev": "tauri-nuxt-dev"
  }
}

Or keep a thin script:

// scripts/dev.ts
import { tauriNuxtDev } from 'tauri-nuxt-dev';

process.exitCode = await tauriNuxtDev({ nuxt: 'vpr' });

Related

• create-tauri-nuxt — Tauri + Nuxt template this library was extracted from
• get-port-please — port resolution
• c12 — config loading
• Tauri CLI — tauri dev
• Nuxt — nuxt dev

Development

pnpm install
pnpm test
pnpm build
pnpm check

Optional peer for TypeScript config files: jiti (see Configuration).

License

MIT © xcvzmoon