├── .gitignore
├── LICENSE
├── README.md
├── index.js
├── package.json
├── pnpm-lock.yaml
├── screenshots
├── bare.png
├── changed.png
├── cli.png
├── deduplication.png
├── info.png
├── life-cycle-events.png
├── markdown.png
├── message.gif
├── return-value.png
└── trace.png
├── src
├── development.ts
└── production.ts
├── test
└── basic.test.tsx
└── tsconfig.json
/.gitignore:
--------------------------------------------------------------------------------
1 | dist
2 | node_modules
3 | .DS_Store
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2022 Shu Ding
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # `useTilg`
2 |
3 | **Tiny Logger** is a magical React Hook to help you debug your components.
4 |
5 | You can quickly try out the [**demo**](https://codesandbox.io/s/usetilg-3kdtz8?file=/src/App.js:274-359).
6 |
7 | Click me
51 | }
52 | ```
53 |
54 |
55 | Logs of render and mount events.
58 |
59 |
60 |
61 | ### 2. Component Name and Props (Who)
62 |
63 | You might noticed that it also displays the **name** and **props** of the component, which is very helpful for debugging.
64 |
65 | ```jsx
66 | import useTilg from 'tilg'
67 |
68 | function MyButton({ text }) {
69 | useTilg()
70 | return {text}
71 | }
72 |
73 | function Title({ children }) {
74 | useTilg()
75 | return {children}
76 | }
77 |
78 | export default function Page() {
79 | return (
80 | <>
81 | Welcome!
82 |
92 | Information of the logged components.
95 |
96 |
97 |
98 | ### 3. Debug Message (Why)
99 |
100 | Another critical thing is to know why does a component re-renders. `useTilg` gives you a simple but powerful API for this:
101 |
102 | ```jsx
103 | import { useState } from 'react'
104 | import useTilg from 'tilg'
105 |
106 | function Counter() {
107 | const [count, setCount] = useState(0)
108 |
109 | useTilg()`count = ${count}`
110 |
111 | return setCount(count + 1)}>{count}
112 | }
113 | ```
114 |
115 | 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:
116 |
117 | ```jsx
118 | useTilg()`count = ${count}`
119 | ```
120 |
121 |
122 | Logs of “count = ?”.
125 |
126 |
127 | You can know where the message is from, too:
128 |
129 |
130 | Trace of the message and a link to the code location.
133 |
134 |
135 | ### 4. What Has Changed? (Why)
136 |
137 | 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**:
138 |
139 | ```jsx
140 | import { useState } from 'react'
141 | import useTilg from 'tilg'
142 |
143 | function MyApp() {
144 | const [input, setInput] = useState('')
145 | const [count, setCount] = useState(0)
146 |
147 | useTilg()`input = ${input}, count = ${count}`
148 |
149 | return (
150 | <>
151 | setCount(count + 1)}>{count}
153 |
154 | )
155 | }
156 | ```
157 |
158 |
159 | A hint for the updated part.
162 |
163 |
164 |
165 | ### 5. Quick Logs (Why)
166 |
167 | If you don't need a debug message but only want to quickly log some values, just pass them to the hook directly:
168 |
169 | ```jsx
170 | import { useState } from 'react'
171 | import useTilg from 'tilg'
172 |
173 | function MyApp() {
174 | const [input, setInput] = useState('')
175 | const [count, setCount] = useState(0)
176 |
177 | useTilg(input, count)
178 |
179 | return (
180 | <>
181 | setCount(count + 1)}>{count}
183 |
184 | )
185 | }
186 | ```
187 |
188 |
189 | Debug values quickly.
192 |
193 |
194 |
195 | setCount(count + 1)}>{count}
210 | }
211 | ```
212 |
213 |
214 | Markdown syntax in log messages.
217 |
218 |
219 |
220 | ### Return Original Value
221 |
222 | 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()`:
223 |
224 | ```diff
225 | function MyApp() {
226 | const [count, setCount] = useState(0)
227 |
228 | return setCount(count + 1)}>{
229 | + useTilg(count)
230 | }
231 | }
232 | ```
233 |
234 |
235 |
236 | Log and return the original value.
239 |
240 |
241 |
242 | ### Auto Deduplication
243 |
244 | Even if you have multiple `useTilg()` hooks in the same component, the lifecycle events will only be logged once per component:
245 |
246 | ```jsx
247 | function MyApp() {
248 | const [input, setInput] = useState('')
249 | const [count, setCount] = useState(0)
250 |
251 | useTilg()
252 | useTilg()`input = ${input}`
253 | useTilg()`count = ${count}`
254 |
255 | return (
256 | <>
257 | setCount(count + 1)}>{count}
259 |
260 | )
261 | }
262 | ```
263 |
264 |
265 | Render, mount, and unmount events will not be duplicated even if you have multiple useTilg() hooks.
268 |
269 |
270 | ### CLI Support
271 |
272 | If you are running your component during SSR, or running server-side tests, `useTilg()` properly outputs the result in Node.js CLI too:
273 |
274 | ```jsx
275 | function App() {
276 | const [count, setCount] = useState(42)
277 |
278 | useTilg()`The answer is ${{ answer: count }}`
279 |
280 | return setCount(count + 1)}>{count}
281 | }
282 | ```
283 |
284 |
285 | Node.js CLI output.
288 |
289 |
290 | = {}
34 | let formatted = ''
35 | let char = ''
36 |
37 | const result = []
38 | const styles = []
39 |
40 | function setStylesAndFormatted(
41 | type: string,
42 | value: string,
43 | tokenType: boolean
44 | ) {
45 | if (!disableStyling) {
46 | if (IS_BROWSER) {
47 | if (formatted.endsWith('%c')) {
48 | styles[styles.length - 1] += value
49 | } else {
50 | formatted += '%c'
51 | styles.push(value)
52 | }
53 | } else {
54 | formatted += value
55 | }
56 | }
57 | tokens[type] = tokenType
58 | char = undefined
59 | }
60 |
61 | function checkNextOrPrev(value: string | undefined) {
62 | return typeof value === 'undefined' || SEPARATOR.test(value)
63 | }
64 |
65 | function process(
66 | type: string,
67 | open: string,
68 | close: string,
69 | next?: string,
70 | prev?: string
71 | ) {
72 | if (tokens[type] && checkNextOrPrev(next)) {
73 | setStylesAndFormatted(type, close, false)
74 | } else if (!tokens[type] && checkNextOrPrev(prev)) {
75 | setStylesAndFormatted(type, open, true)
76 | } else {
77 | char = type
78 | }
79 | }
80 |
81 | for (let i = 0; i < strings.length; i++) {
82 | formatted = ''
83 | let prev = undefined
84 | const str = strings[i]
85 |
86 | for (let j = 0; j < str.length; j++) {
87 | char = str[j]
88 |
89 | if (char === '*') {
90 | if (str[j + 1] === '*') {
91 | j++
92 | process(
93 | '**',
94 | IS_BROWSER ? 'font-weight: bold;' : '\u001B[1m',
95 | IS_BROWSER ? 'font-weight: normal;' : '\u001B[22m',
96 | str[j + 1],
97 | prev
98 | )
99 | } else {
100 | process(
101 | '*',
102 | IS_BROWSER ? 'font-style: italic;' : '\u001B[3m',
103 | IS_BROWSER ? 'font-style: normal;' : '\u001B[23m',
104 | str[j + 1],
105 | prev
106 | )
107 | }
108 | } else if (char === '_') {
109 | if (str[j + 1] === '_') {
110 | j++
111 | process(
112 | '__',
113 | IS_BROWSER ? 'font-weight: bold;' : '\u001B[1m',
114 | IS_BROWSER ? 'font-weight: normal;' : '\u001B[22m',
115 | str[j + 1],
116 | prev
117 | )
118 | } else {
119 | process(
120 | '_',
121 | IS_BROWSER ? 'font-style: italic;' : '\u001B[3m',
122 | IS_BROWSER ? 'font-style: normal;' : '\u001B[23m',
123 | str[j + 1],
124 | prev
125 | )
126 | }
127 | } else if (char === '`') {
128 | process(
129 | '`',
130 | IS_BROWSER
131 | ? 'background: hsla(0,0%,70%,.3); border-radius:3px; padding: 0 2px;'
132 | : '\u001B[96m\u001B[1m',
133 | IS_BROWSER ? 'background: unset;' : '\u001B[39m\u001B[22m',
134 | str[j + 1],
135 | prev
136 | )
137 | }
138 |
139 | prev = char
140 | if (typeof char !== 'undefined') {
141 | formatted += char
142 | }
143 | }
144 |
145 | const hasPrevSlot = i > 0
146 | const hasNextSlot = i < args.length
147 | if (disableStyling) {
148 | if (hasNextSlot && formatted.endsWith(' ')) {
149 | formatted = formatted.slice(0, -1)
150 | }
151 | if (hasPrevSlot && formatted.startsWith(' ')) {
152 | formatted = formatted.slice(1)
153 | }
154 |
155 | if (formatted !== '') {
156 | result.push(formatted)
157 | }
158 |
159 | if (hasNextSlot) {
160 | if (typeof args[i] === 'string') {
161 | result.push(JSON.stringify(args[i]))
162 | } else {
163 | result.push(args[i])
164 | }
165 | }
166 | } else {
167 | if (!result.length) result.push('')
168 | if (hasNextSlot && hints[i]) {
169 | process(
170 | '~',
171 | IS_BROWSER
172 | ? 'text-decoration: underline; text-decoration-color: green; text-decoration-style: wavy; padding-bottom: 1px; text-decoration-skip-ink: none;'
173 | : '',
174 | ''
175 | )
176 | }
177 |
178 | if (formatted !== '') {
179 | if (result.length) {
180 | result[result.length - 1] += formatted
181 | } else {
182 | result.push(formatted)
183 | }
184 | }
185 |
186 | if (hasNextSlot) {
187 | let serialized
188 | if (
189 | args[i] &&
190 | (typeof args[i] === 'object' || typeof args[i] === 'function')
191 | ) {
192 | result[result.length - 1] += '%o'
193 | styles.push(args[i])
194 | } else {
195 | try {
196 | serialized = JSON.stringify(args[i])
197 | } catch (e) {
198 | serialized = '' + args[i]
199 | }
200 | result[result.length - 1] += serialized
201 | }
202 | }
203 |
204 | if (hasNextSlot && hints[i]) {
205 | formatted = ''
206 | process(
207 | '~',
208 | IS_BROWSER ? 'text-decoration: none; padding-bottom: 0;' : '',
209 | ''
210 | )
211 | result[result.length - 1] += formatted
212 | }
213 | }
214 | }
215 |
216 | if (trace) {
217 | if (disableStyling) {
218 | result.push(` (@ ${trace})`)
219 | } else {
220 | if (!result.length) result.push('')
221 | if (IS_BROWSER) {
222 | result[result.length - 1] += `%c(@ ${trace})`
223 | styles.push(
224 | 'color: #999; font-style: italic; font-size: 0.9em; padding-left: 2em;'
225 | )
226 | } else {
227 | result[result.length - 1] += ` \u001B[2m(@ ${trace})\u001B[22m`
228 | }
229 | }
230 | }
231 |
232 | result.push(...styles)
233 |
234 | return result
235 | }
236 |
237 | function log(...args) {
238 | console.log(...args)
239 | }
240 |
241 | /**
242 | * This function gets the name of the component which calls the useTilg hook.
243 | * Returns null if not able to retrieve the information.
244 | */
245 | const components = new WeakMap()
246 | const instances = new Map()
247 | function useTilgCurrentComponentContext() {
248 | const owner = (React as any)
249 | .__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner
250 | .current || { type: { name: 'unknown' }, memoizedProps: undefined }
251 |
252 | const name = owner.type.name
253 | const id = owner.type
254 |
255 | let path = ''
256 | let logPath = ''
257 |
258 | const stack = new Error().stack.split('\n')
259 | for (const line of stack) {
260 | const match = line.match(/^\s*at\s+(.*?)\s+\((.*?)\)$/)
261 | const callerName = match?.[1]
262 | const callerPath = match?.[2]
263 |
264 | if (callerPath) path += callerPath + ','
265 |
266 | if (callerName && !callerName.startsWith('useTilg')) {
267 | logPath = match[2]
268 | }
269 |
270 | if (
271 | callerName &&
272 | !callerName.startsWith('use') &&
273 | !/.+\.use.+/.test(callerName)
274 | ) {
275 | break
276 | }
277 | }
278 |
279 | return [name, owner, id, path, logPath]
280 | }
281 |
282 | export default function useTilg(...inlined: any[]) {
283 | const mark = useState(Math.random())[0]
284 | const [name, owner, id, hookPath, logPath] = useTilgCurrentComponentContext()
285 |
286 | const compute = () => {
287 | let hookId = 0
288 |
289 | if (!components.has(id)) {
290 | components.set(id, [])
291 | }
292 | const hooks = components.get(id)
293 | hookId = hooks.indexOf(hookPath)
294 | if (hookId === -1) {
295 | hookId = hooks.length
296 | hooks.push(hookPath)
297 | }
298 |
299 | const componentName = name ? '`<' + name + '/>`' : 'Component'
300 |
301 | // Only log the life cycle message for the first hook.
302 | if (hookId !== 0) return [componentName, hookId, 0]
303 |
304 | // Which component instance is this hook located in.
305 | if (!instances.has(id)) {
306 | instances.set(id, [])
307 | }
308 | const instanceMarks = instances.get(id)
309 | let index = instanceMarks.indexOf(mark)
310 | if (index === -1) {
311 | index = instanceMarks.length
312 | instanceMarks.push(mark)
313 | }
314 |
315 | return [componentName, hookId, index]
316 | }
317 |
318 | useEffect(() => {
319 | const [componentName, hookId, instanceId] = compute()
320 |
321 | // Only log the life cycle message for the first hook.
322 | if (hookId !== 0) return
323 | const note = instanceId > 0 ? ` (${instanceId + 1})` : ''
324 |
325 | log(...md([`${componentName}${note} mounted.`]))
326 | return () => {
327 | if (!instances.has(id)) {
328 | instances.set(id, [])
329 | }
330 | const instanceMarks = instances.get(id)
331 | let index = instanceMarks.indexOf(mark)
332 | if (index !== -1) {
333 | instanceMarks[index] = instanceMarks[instanceMarks.length - 1]
334 | instanceMarks.length--
335 | }
336 |
337 | if (!components.has(id)) {
338 | components.set(id, [])
339 | }
340 | const hooks = components.get(id)
341 | index = hooks.indexOf(hookPath)
342 | if (index !== -1) {
343 | hooks[index] = hooks[hooks.length - 1]
344 | hooks.length--
345 | }
346 |
347 | log(...md([`${componentName}${note} unmounted.`]))
348 | }
349 | }, [])
350 |
351 | const loggerEffectContent = useRef(null)
352 | loggerEffectContent.current = null
353 | const loggerPrevArgsContent = useRef(null)
354 | const loggerArgsContent = useRef([])
355 | loggerArgsContent.current = []
356 |
357 | useLayoutEffect(() => {
358 | const [componentName, hookId, instanceId] = compute()
359 |
360 | // Only log the life cycle message for the first hook.
361 | if (hookId === 0) {
362 | const note = instanceId > 0 ? ` (${instanceId + 1})` : ''
363 | log(
364 | ...md(
365 | [`${componentName}${note} rendered with props: \``, '`.'],
366 | [owner.memoizedProps]
367 | )
368 | )
369 | }
370 |
371 | let changed = false
372 | let changedHint = {}
373 |
374 | const prev = loggerPrevArgsContent.current
375 | const now = loggerArgsContent.current
376 | if (!prev || prev.length !== now.length) {
377 | // An arg has been removed or added, do nothing.
378 | changed = true
379 | } else {
380 | for (let i = 0; i < prev.length; i++) {
381 | if (prev[i] !== now[i]) {
382 | changed = true
383 | changedHint[i] = true
384 | }
385 | }
386 | }
387 | loggerPrevArgsContent.current = now
388 |
389 | if (changed && loggerEffectContent.current) {
390 | loggerEffectContent.current(changedHint)
391 | }
392 | })
393 |
394 | if (inlined.length > 0) {
395 | loggerArgsContent.current = inlined
396 | loggerEffectContent.current = (hints) => {
397 | const message = md(
398 | inlined.map((_, i) => (i > 0 ? ', ' : '')).concat(''),
399 | inlined,
400 | hints,
401 | logPath
402 | )
403 |
404 | log(...message)
405 | }
406 | return inlined[0]
407 | }
408 |
409 | return function useTilgInner(strings, ...args: any[]) {
410 | loggerEffectContent.current = (hints: Record) => {
411 | const message = strings.length ? md(strings, args, hints, logPath) : ''
412 |
413 | if (message) {
414 | // This is a work around to get rid of the hook count mismatch bug.
415 | log(...message)
416 | }
417 | }
418 |
419 | loggerArgsContent.current = args
420 |
421 | return args[0]
422 | }
423 | }
424 |
--------------------------------------------------------------------------------
/src/production.ts:
--------------------------------------------------------------------------------
1 | export default function useTilg(...args) {
2 | if (args.length) return args[0]
3 | return (_strings, ...innerArgs) => {
4 | if (innerArgs && innerArgs.length) return innerArgs[0]
5 | }
6 | }
7 |
--------------------------------------------------------------------------------
/test/basic.test.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import { act, create } from 'react-test-renderer'
3 | import { afterEach, describe, expect, it, vi } from 'vitest'
4 |
5 | import useTilg from '../src/development'
6 |
7 | describe('useTilg', () => {
8 | afterEach(() => {
9 | vi.restoreAllMocks()
10 | })
11 |
12 | it('should log the render, mount and unmount events', async () => {
13 | const logSpy = vi.spyOn(console, 'log')
14 |
15 | function App() {
16 | useTilg()
17 | return null
18 | }
19 | const app = create( 
56 | 
93 | 
123 | 
131 | 
160 | 
190 | 
215 | 
237 | 
266 | 
286 |