shuding/tilg

useTilg

Tiny Logger is a magical React Hook to help you debug your components.

You can quickly try out the demo.

Table of Contents

• Installation
• Features
  • Lifecycle Events (What)
  • Component Name and Props (Who)
  • Debug Message (Why)
  • What Has Changed? (Why)
  • Quick Logs (Why)
• Advanced Features
  • Markdown
  • Return Original Value
  • Auto Deduplication
  • CLI Support
• FAQ & Caveats

Installation

The package is released as tilg, use:

npm i tilg

to install it with npm. Or you can choose another package manager.

Features

1. Lifecycle Events (What)

Simply insert the useTilg() hook into the component, and it will log the render, mount, unmount events in the console:

import useTilg from 'tilg'

function MyButton() {
  useTilg()
  return <button>Click me</button>
}

Logs of render and mount events.

2. Component Name and Props (Who)

You might noticed that it also displays the name and props of the component, which is very helpful for debugging.

import useTilg from 'tilg'

function MyButton({ text }) {
  useTilg()
  return <button>{text}</button>
}

function Title({ children }) {
  useTilg()
  return <h1>{children}</h1>
}

export default function Page() {
  return (
    <>
      <Title>Welcome!</Title>
      <MyButton text='foo' />
      <MyButton text='bar' />
    </>
  )
}

When there’re multiple elements of the same component being rendered, it adds a counter <MyButton/> (2) for distinguishing so you know who is logging the information:

Information of the logged components.

3. Debug Message (Why)

Another critical thing is to know why does a component re-renders. useTilg gives you a simple but powerful API for this:

import { useState } from 'react'
import useTilg from 'tilg'

function Counter() {
  const [count, setCount] = useState(0)
  
  useTilg()`count = ${count}`
  
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

When appending a template literal to the useTilg() call, it will also be displayed as the debug message:

useTilg()`count = ${count}`

Logs of “count = ?”.

You can know where the message is from, too:

Trace of the message and a link to the code location.

4. What Has Changed? (Why)

Something troubles me a lot when debugging a component is, it’s sometimes hard to know which state has changed and triggered a re-render. useTilg tracks all the arguments in the debug message and tells you which one has changed since the previous render:

import { useState } from 'react'
import useTilg from 'tilg'

function MyApp() {
  const [input, setInput] = useState('')
  const [count, setCount] = useState(0)

  useTilg()`input = ${input}, count = ${count}`

  return (
    <>
      <input onChange={(e) => setInput(e.target.value)} value={input} />
      <button onClick={() => setCount(count + 1)}>{count}</button>
    </>
  )
}

A hint for the updated part.

5. Quick Logs (Why)

If you don't need a debug message but only want to quickly log some values, just pass them to the hook directly:

import { useState } from 'react'
import useTilg from 'tilg'

function MyApp() {
  const [input, setInput] = useState('')
  const [count, setCount] = useState(0)

  useTilg(input, count)

  return (
    <>
      <input onChange={(e) => setInput(e.target.value)} value={input} />
      <button onClick={() => setCount(count + 1)}>{count}</button>
    </>
  )
}

Debug values quickly.

Advanced Features

Markdown

You can use Markdown's code (`), italic (_ or *), and bold (__ or **) syntax in your debug message to make it look nicer:

function MyApp() {
  const [count, setCount] = useState(0)

  useTilg()`**Debug**: \`count\` = _${count}_.`

  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Markdown syntax in log messages.

Return Original Value

The useTilg() hook also returns its first argument, or the first value in the template if specified, so you can quickly debug something in-place by wrapping it with useTilg():

  function MyApp() {
    const [count, setCount] = useState(0)

    return <button onClick={() => setCount(count + 1)}>{
+     useTilg(count)
    }</button>
  }

Log and return the original value.

Auto Deduplication

Even if you have multiple useTilg() hooks in the same component, the lifecycle events will only be logged once per component:

function MyApp() {
  const [input, setInput] = useState('')
  const [count, setCount] = useState(0)

  useTilg()
  useTilg()`input = ${input}`
  useTilg()`count = ${count}`

  return (
    <>
      <input onChange={(e) => setInput(e.target.value)} value={input} />
      <button onClick={() => setCount(count + 1)}>{count}</button>
    </>
  )
}

Render, mount, and unmount events will not be duplicated even if you have multiple useTilg() hooks.

CLI Support

If you are running your component during SSR, or running server-side tests, useTilg() properly outputs the result in Node.js CLI too:

function App() {
  const [count, setCount] = useState(42)
  
  useTilg()`The answer is ${{ answer: count }}`

  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

Node.js CLI output.

FAQ & Caveats

• Is it safe to ship code with useTilg to production?
  Although useTilg() does nothing in a production build (process.env.NODE_ENV === 'production') but only an empty function, I encourge you to remove the hook from the source code after finishing the development of your app.

• How do you implement this hook? What can I learn from the code?
  It is very hacky. Don't do the same thing especially try it in production, or you will be fired.

• Why not design the API as useTilg`message`?
  Then it will not be identified as a hook, React Refresh and HMR will not work correctly.

License

The MIT License (MIT).