tiktok-live-nuxt

tiktok-live-nuxt

Nuxt module for TikTok LIVE API — real-time chat, gifts, viewers, battles & AI captions from any TikTok LIVE stream.

<script setup>
const { messages, viewers, gifts, connected } = useTikTokLive('gbnews')
</script>

<template>
  <div>
    <p>👀 {{ viewers }} viewers</p>
    <div v-for="msg in messages" :key="msg.data?.msgId">
      <b>{{ msg.data?.user?.uniqueId }}:</b> {{ msg.data?.comment }}
    </div>
  </div>
</template>

That's it. Auto-imported, reactive, auto-connects on mount. ☝️

Quick Setup

1. Install

# npm
npm install tiktok-live-nuxt

# pnpm
pnpm add tiktok-live-nuxt

# bun
bun add tiktok-live-nuxt

# yarn
yarn add tiktok-live-nuxt

2. Configure

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['tiktok-live-nuxt'],
  tiktool: {
    apiKey: 'YOUR_API_KEY' // Get free key → https://tik.tools
  }
})

Or via environment variable (recommended for production):

TIKTOOL_API_KEY=your_api_key

3. Use

<script setup>
const { messages, viewers, gifts, connected, error } = useTikTokLive('username')
</script>

No imports needed — useTikTokLive is auto-imported by the module.

SSR & Client-Side

This composable uses WebSocket which only runs in the browser. It's designed to work correctly in both SSR and CSR modes:

<!-- Option 1: Works out of the box (SSR-safe) -->
<script setup>
const { messages, connected } = useTikTokLive('gbnews')
</script>

<!-- Option 2: Client-only wrapper (avoids empty state flash) -->
<ClientOnly>
  <TikTokChat username="gbnews" />
</ClientOnly>

API Reference

useTikTokLive(uniqueId, options?)

Reactive Returns

Methods

Events

<script setup>
const tiktok = useTikTokLive('gbnews')

tiktok.on('chat', (data) => {
  // data.user.uniqueId, data.comment
})

tiktok.on('gift', (data) => {
  // data.user.uniqueId, data.giftName, data.diamondCount
})

tiktok.on('like', (data) => {
  // data.user.uniqueId, data.likeCount
})

tiktok.on('follow', (data) => {
  // data.user.uniqueId
})

tiktok.on('roomUserSeq', (data) => {
  // data.viewerCount
})
</script>

PK Battles + Boosters

battleArmies.hosts[] gives per-host MVP breakdown sorted by score:

<script setup>
const tiktok = useTikTokLive('streamer_name')

tiktok.on('battleArmies', (e) => {
  console.log(`⏱ ${e.secsRemaining}s left`)
  for (const host of e.hosts ?? []) {
    const mvp = host.contributors[0]
    console.log(`${host.hostUserId}: ${host.teamTotalScore} (MVP ${mvp?.nickname}: ${mvp?.score})`)
  }
})

tiktok.on('battleItemCard', (e) => {
  // x2/x3 boosters, gloves, mist, thunder, extra-time, match-guide
  const tag = e.multiplier > 0 ? `x${e.multiplier} BOOSTER` : e.effect.toUpperCase()
  console.log(`💥 ${e.senderNickname} → ${tag}`)
  // e.iconUrl + e.accentColor for drop-in overlay
})
</script>

Full Example

<script setup>
const username = ref('gbnews')
const tiktok = useTikTokLive(username.value)

const topGifters = computed(() => {
  const map = new Map()
  for (const g of tiktok.gifts.value) {
    const user = g.data?.user?.uniqueId
    const diamonds = g.data?.diamondCount || 0
    map.set(user, (map.get(user) || 0) + diamonds)
  }
  return [...map.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5)
})
</script>

<template>
  <div v-if="tiktok.error.value" class="error">{{ tiktok.error.value }}</div>

  <div v-else-if="!tiktok.connected.value">Connecting to @{{ username }}...</div>

  <div v-else>
    <p>✅ Connected — 👀 {{ tiktok.viewers.value }} viewers — {{ tiktok.eventCount.value }} events</p>

    <h3>💬 Chat</h3>
    <div v-for="msg in tiktok.messages.value" :key="msg.data?.msgId">
      <b>{{ msg.data?.user?.uniqueId }}:</b> {{ msg.data?.comment }}
    </div>

    <h3>🏆 Top Gifters</h3>
    <div v-for="([name, diamonds], i) in topGifters" :key="name">
      {{ i + 1 }}. @{{ name }} — {{ diamonds }} 💎
    </div>
  </div>
</template>

Other SDKs

Links

• 🌐 tik.tools — Dashboard & API keys
• 📖 Documentation
• 🎙️ AI Live Captions

License

MIT — tik.tools