Stable for Next.js App Router

next-live2d

A drop-in Live2D widget for Next.js with better runtime stability, safer cleanup, and practical controls for real-world products.

Latest: v2.0.3 • Runtime initialization fixes

npmjs.com/package/next-live2d

GitHubYouTubeTikTok
$ npm install next-live2d
'use client'
import { Live2DWidget } from 'next-live2d'

export default function Page() {
  return <Live2DWidget modelName="Kar98k-normal" />
}

v2.0.1 highlights

  • Safe script loading to avoid duplicate Live2D initialization.
  • Better handling for strict mode and route transitions.
  • Timeout guard to prevent endless waiting loops.
  • More stable behavior when imported into external Next.js projects.
Tip: Keep a single widget instance per layout/page for best stability.

Release timeline

v2.0.3

2026-07-27

Runtime Initialization Fixes

  • • Fixed Live2D init context binding to prevent undefined emit runtime crash
  • • Added model.json preflight validation before widget init
  • • Added clean dev scripts to avoid stale .next chunk mismatch during local package testing

v2.0.2

2026-07-27

GitHub Username Migration

  • • Default model host now points to github.com/2hjaito
  • • Repository and issue links updated in package metadata
  • • README and demo links aligned with the new username

v2.0.1

2026-07-27

Stability & Next.js Hardening

  • • Prevent duplicate script injection under React StrictMode
  • • Safer async initialization flow to reduce race conditions
  • • Timeout protection while waiting for widget container
  • • Cleanup improvements to reduce freezes on remount/route changes

v2.0.0

2026-03-07

Major Feature Release

  • • Custom baseUrl for self-hosted models
  • • Position, size, opacity, hoverOpacity controls
  • • Random model mode and loading fallback
  • • React 18/19 support with stronger TypeScript exports

v1.4.1

2025-06-24

Strict Mode Crash Fix

  • • Avoided unsafe global delete operation
  • • Improved unmount cleanup safety

Documentation

Full changelog and release notes are maintained in the library repository. Keep the demo page aligned with those notes to make package updates easier for users.

Usage docsFull changelogOpen route test page