LocalAuth

LocalAuth stores the WhatsApp session in a local folder (.wwebjs_auth by default). After the first login, subsequent restarts restore the session automatically, no QR code needed.

Setup

LocalAuth is built into whatsapp-web.js. No extra packages required.

const { Client, LocalAuth } = require('whatsapp-web.js')

const client = new Client({
  authStrategy: new LocalAuth(),
})

client.on('qr', qr => {
  console.log('First run, scan this QR code')
})

client.on('ready', () => {
  console.log('Ready!')
})

client.initialize()

What Gets Created

After the first successful login, a .wwebjs_auth directory appears next to your app file:

Add .wwebjs_auth to your .gitignore to avoid accidentally committing session data.

Options

const client = new Client({
  authStrategy: new LocalAuth({
    clientId: 'my-app', // Unique name — lets multiple apps share one machine
    dataPath: './sessions', // Where to store session files (default: ./.wwebjs_auth)
  }),
})

clientId

When you run more than one app on the same machine, give each a different clientId so their sessions don't overwrite each other:

// app 1
const client1 = new Client({
  authStrategy: new LocalAuth({ clientId: 'support-app' }),
})

// app 2
const client2 = new Client({
  authStrategy: new LocalAuth({ clientId: 'sales-app' }),
})

This creates separate folders: .wwebjs_auth/support-app/ and .wwebjs_auth/sales-app/.

First Run vs Subsequent Runs

First run:

1. qr event fires — scan with your phone
2. Session is saved to disk
3. authenticated then ready fires

Subsequent runs:

1. Session is restored from disk
2. authenticated then ready fires — no QR code

client.on('qr', qr => {
  // This only fires on first run (or if session expires)
  console.log('Scan QR code')
})

client.on('ready', () => {
  console.log('Ready!')
})

Limitations

• One instance per clientId: Two processes with the same clientId will conflict.
• Tied to the filesystem: Moving the app to a different server means copying the session folder.
• Not suitable for containers: If the container is recreated, the session is lost. Use RemoteAuth instead.