Skip to content

shuding/tilg

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
April 10, 2022 22:12
April 10, 2022 22:12
April 10, 2022 22:12
April 27, 2022 14:10
April 10, 2022 22:12
April 15, 2022 23:05
April 10, 2022 22:12
April 10, 2022 22:12

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

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>
}

lifecycle event logs
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 logs
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}`

debug message
Logs of “count = ?”.

You can know where the message is from, too:

trace
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>
    </>
  )
}

changed argument
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>
    </>
  )
}

value without message
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
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>
  }

return original value
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>
    </>
  )
}

deduplication
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>
}

deduplication
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).