A magical React Hook that helps you debug components.
# `useTilg`
**Tiny Logger** is a magical React Hook to help you debug your components.
You can quickly try out the [**demo**](https://codesandbox.io/s/usetilg-3kdtz8?file=/src/App.js:274-359).
## Table of Contents
- [Installation](#installation)
- [Features](#features)
- [Lifecycle Events (What)](#1-lifecycle-events-what)
- [Component Name and Props (Who)](#2-component-name-and-props-who)
- [Debug Message (Why)](#3-debug-message-why)
- [What Has Changed? (Why)](#4-what-has-changed-why)
- [Quick Logs (Why)](#5-quick-logs-why)
- [Advanced Features](#advanced-features)
- [Markdown](#markdown)
- [Return Original Value](#return-original-value)
- [Auto Deduplication](#auto-deduplication)
- [CLI Support](#cli-support)
- [FAQ & Caveats](#faq--caveats)
## Installation
The package is released as `tilg`, use:
```sh
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:
```jsx
import useTilg from 'tilg'
function MyButton() {
useTilg()
return Click me
}
```
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.
```jsx
import useTilg from 'tilg'
function MyButton({ text }) {
useTilg()
return {text}
}
function Title({ children }) {
useTilg()
return
{children}
}
export default function Page() {
return (
<>
Welcome!
</>
)
}
```
When there’re multiple elements of the same component being rendered, it adds a counter ` (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:
```jsx
import { useState } from 'react'
import useTilg from 'tilg'
function Counter() {
const [count, setCount] = useState(0)
useTilg()`count = ${count}`
return setCount(count + 1)}>{count}
}
```
When appending a [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to the `useTilg()` call, it will also be displayed as the debug message:
```jsx
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**:
```jsx
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 (
<>
setInput(e.target.value)} value={input} />
setCount(count + 1)}>{count}
</>
)
}
```
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:
```jsx
import { useState } from 'react'
import useTilg from 'tilg'
function MyApp() {
const [input, setInput] = useState('')
const [count, setCount] = useState(0)
useTilg(input, count)
return (
<>
setInput(e.target.value)} value={input} />
setCount(count + 1)}>{count}
</>
)
}
```
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:
```jsx
function MyApp() {
const [count, setCount] = useState(0)
useTilg()`**Debug**: \`count\` = _${count}_.`
return setCount(count + 1)}>{count}
}
```
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()`:
```diff
function MyApp() {
const [count, setCount] = useState(0)
return setCount(count + 1)}>{
+ useTilg(count)
}
}
```
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:
```jsx
function MyApp() {
const [input, setInput] = useState('')
const [count, setCount] = useState(0)
useTilg()
useTilg()`input = ${input}`
useTilg()`count = ${count}`
return (
<>
setInput(e.target.value)} value={input} />
setCount(count + 1)}>{count}
</>
)
}
```
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:
```jsx
function App() {
const [count, setCount] = useState(42)
useTilg()`The answer is ${{ answer: count }}`
return setCount(count + 1)}>{count}
}
```
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](https://github.com/facebook/react/blob/0568c0f8cde4ac6657dff9a5a8a7112acc35a748/packages/react/index.js#L35).
- **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).