mirror of
https://github.com/hanzoai/gui.git
synced 2026-10-25 02:31:41 +00:00
zeekayandHanzo Dev
751ef5c778
Both old names are owned by a different npm account (artemis-prime), so publishing them returns 403 — which is how this surfaced: the 8.0.0 run shipped @hanzogui/logo and @hanzogui/demos depending on [email protected], a version that cannot be published and therefore does not exist. Those two were uninstallable. @hanzo/gui and @hanzogui/* are ours, so the framework now carries the name it is imported by everywhere downstream, and the loader moves under the scope we control. The rewrite is limited to package references. `DEBUG?.startsWith('hanzogui')` is a log-namespace filter and join(dir, 'hanzogui') is a path — rewriting either would change behaviour, so both are untouched. Co-authored-by: Hanzo Dev <[email protected]>
121 lines
3.4 KiB
Plaintext
121 lines
3.4 KiB
Plaintext
---
|
|
title: Developing with Gui
|
|
description: Tips and tricks
|
|
---
|
|
|
|
Gui includes many helpful tools for debugging UI.
|
|
|
|
### Debugging
|
|
|
|
Gui has several ways of giving you more insight into what's happening at
|
|
compile-time.
|
|
|
|
#### Visualizer
|
|
|
|
You can set up a simple visualizer that shows a heads-up display when you
|
|
hold "Option" (or any key you define) after a short delay, revealing
|
|
the styled component names and even the file numbers and components they are in
|
|
(if you have the compiler plugin installed) as an overlay over your app in
|
|
development mode.
|
|
|
|
```tsx
|
|
import { setupDev } from '@hanzogui/core'
|
|
|
|
setupDev({
|
|
// can just be true as well for defaulting to key: Alt + delay: 800
|
|
visualizer: {
|
|
key: 'Alt',
|
|
delay: 800,
|
|
},
|
|
})
|
|
```
|
|
|
|
#### Debug Pragma
|
|
|
|
To see what's being extracted, why, and every step along the optimization
|
|
pipeline, add `// debug` to the top of any file. Adding `// debug-verbose` will
|
|
show even more information, including more granular timings.
|
|
|
|
If you're developing in your design system package that is built with
|
|
@hanzogui/build, esbuild will strip this banner. You can try using `//! debug`
|
|
(esbuild only preserves comments at the top that start with `//!`), but still
|
|
occasionally esbuild will insert a helper above the comment, breaking it, so be
|
|
sure to check the built file in `dist/jsx`.
|
|
|
|
#### Debug Prop
|
|
|
|
Adding `debug` to any Gui component outputs detailed information about
|
|
what's happening at runtime. Use it like so:
|
|
|
|
```tsx
|
|
import { Button } from '@hanzo/gui'
|
|
|
|
export default () => <Button debug>Hello world</Button>
|
|
```
|
|
|
|
You'll see props, styles, and a variety of variables relevant to processing
|
|
them.
|
|
|
|
You can do `<Button debug="break" />` to have it break at the beginning of
|
|
rendering, or `<Button debug="verbose" />` to have it output more detailed debug
|
|
information.
|
|
|
|
#### DEBUG Environment Variable
|
|
|
|
If you set `DEBUG=hanzogui` before your build command, you get the full
|
|
debug output of every file built. This is useful for seeing everything that's
|
|
happening across every file and is especially helpful for diagnosing production
|
|
issues.
|
|
|
|
### Runtime introspection
|
|
|
|
In development mode, Gui sets the variable `Gui` onto `globalThis` with
|
|
a lot of helpful internals, including your entire parsed config from
|
|
`hanzogui.config.ts`.
|
|
|
|
Beyond your config, you have:
|
|
|
|
- **allSelectors**: All the selectors inserted by Gui (before runtime).
|
|
|
|
#### Inspecting Components
|
|
|
|
Any `styled()` component will have a `staticConfig` property attached to it:
|
|
|
|
```tsx
|
|
const Circle = styled(View, {
|
|
borderRadius: 1000,
|
|
})
|
|
|
|
console.log(Circle.staticConfig) // lots of helpful information
|
|
```
|
|
|
|
- `componentName` is taken from the `name` key
|
|
- `variants` contains the merged variants including parents.
|
|
- `defaultProps` is the extracted props left to use as defaults on the
|
|
component.
|
|
|
|
### Classes generated
|
|
|
|
Gui generates helpful CSS classes. For components created with `styled()`
|
|
where a `name` is set like this:
|
|
|
|
```tsx
|
|
const MyButton = styled(View, {
|
|
name: 'MyButton',
|
|
backgroundColor: 'red',
|
|
})
|
|
```
|
|
|
|
Gui adds the classname `is_MyButton`. This is a useful escape hatch for
|
|
attaching CSS to any extra component. All the default Gui components have
|
|
their name set.
|
|
|
|
For components that extend a Text-based component, a further classname is set of
|
|
the format `font_[fontFamily]`. So if you do:
|
|
|
|
```tsx
|
|
<Paragraph fontFamily="$body" />
|
|
```
|
|
|
|
The classnames `is_Paragraph` and `font_body` will be output to DOM.
|