Debugging
How can I debug my styles or profile the extraction process?
panda debug
Panda's built-in debug command helps you see which files are processed, what styles are generated, and your final config.
By default it will scan and output debug files for the entire project depending on your include
and exclude
options
from your config file.
This would generate a debug
folder in your config.outdir
folder with the following structure:
The config.json
file will contain the resolved config result, meaning the output after merging config presets in your
own specific options.
It can be useful to check if your config contains everything you expect for your app to be working, such as tokens or recipes.
*.ast.json
files will look like:
[
{
"name": "css",
"type": "object",
"data": [
{
"transitionProperty": "all",
"opacity": "0.5",
"border": "1px solid",
"borderColor": "black",
"color": "gray.600",
"_hover": {
"color": "gray.900"
},
"rounded": "md",
"p": "1.5",
"_dark": {
"borderColor": "rgba(255, 255, 255, 0.1)",
"color": "gray.400",
"_hover": {
"color": "gray.50"
}
}
}
],
"kind": "CallExpression",
"line": 13,
"column": 9
}
]
And the .css
file associated would just contain the styles generated from the extraction process on that file only.
PANDA_DEBUG env variable
You can prefix any of the Panda CLI command with the PANDA_DEBUG
environment variable to show debug logs.
PANDA_DEBUG=* pnpm panda
This can be useful to check if a specific file is being processed or not, or if a specific function/component has been extracted.
⯠PANDA_DEBUG=* pnpm panda cssgen
š¼ debug [config:path] /Users/astahmer/dev/open-source/panda-clone/website/panda.config.ts
š¼ debug [ast:import] Found import { css } in /Users/astahmer/dev/open-source/panda-clone/website/theme.config.tsx
š¼ debug [ast:Icon] { kind: 'component' }
š¼ debug [ast:css] { kind: 'function' }
š¼ debug [hrtime] Parsed /Users/astahmer/dev/open-source/panda-clone/website/theme.config.tsx (9.66ms)
š¼ debug [ast:import] Found import { css } in /Users/astahmer/dev/open-source/panda-clone/website/src/DEFAULT_THEME.tsx
š¼ debug [ast:DiscordIcon] { kind: 'component' }
š¼ debug [ast:css] { kind: 'function' }
š¼ debug [ast:Anchor] { kind: 'component' }
š¼ debug [ast:GitHubIcon] { kind: 'component' }
š¼ debug [ast:Flexsearch] { kind: 'component' }
š¼ debug [ast:MatchSorterSearch] { kind: 'component' }
š¼ debug [hrtime] Parsed /Users/astahmer/dev/open-source/panda-clone/website/src/DEFAULT_THEME.tsx (4.51ms)
š¼ debug [ast:import] No import found in /Users/astahmer/dev/open-source/panda-clone/website/src/constants.tsx
š¼ debug [hrtime] Parsed /Users/astahmer/dev/open-source/panda-clone/website/src/constants.tsx (4.23ms)
š¼ debug [ast:import] Found import { css } in /Users/astahmer/dev/open-source/panda-clone/website/src/index.tsx
š¼ debug [ast:css] { kind: 'function' }
Performance profiling
If Panda is taking too long to process your files, you can use the --cpu-prof
with the panda
, panda cssgen
,
panda codegen
and panda debug
commands to generate a flamegraph of the whole process, which will allow you (or us as
maintainers) to see which part of the process is taking the most time.
This will generate a panda-{command}-{timestamp}.cpuprofile
file in the current working directory, which can be opened
in tools like Speedscope (opens in a new tab)
pnpm panda --cpu-prof
FAQ
Why are my styles not applied?
Check that the @layer
rules are set and the corresponding .css
file is
included. If you're not using postcss
, ensure that styled-system/styles.css
is imported
and that the panda
command has been run (or is running with --watch
).
Some CSS is missing when using absolute imports
This can happen when tsconfig
(with paths
or baseUrl
) or with package.json
#imports
(opens in a new tab). Panda tries to automatically infer and read the
custom paths defined in tsconfig.json
file. However, there might be scenarios that won't work.
To fix this add the importMap
option to your panda.config.js
file, setting it's value to match the way you import
the outdir
modules.
// app.tsx
import { css } from "~/styled-system/css"
// tsconfig.json paths
// -> importMap: "~/styled-system"
import { css } from "styled-system/css"
// tsconfig.json baseUrl
// -> importMap: "styled-system"
import { css } from "@my-monorepo/ui-kit/css"
// monorepo workspace package
// -> importMap: "@my-monorepo/ui-kit"
import { css } from "#styled-system/css"
// package.json#imports
// -> importMap: "#styled-system
// panda.config.js
export default defineConfig({
importMap: '~/styled-system'
})
This will ensure that the paths are resolved correctly, and HMR works as expected.
How can I debug the styles?
You can use the panda debug
to debug design token extraction & css generated from files.
If the issue persists, you can try looking for it in the issues (opens in a new tab) or in the discord (opens in a new tab). If you can't find it, please create a minimal reproduction and submit a new github issue (opens in a new tab) so we can help you.
Why is my IDE not showing styled-system
imports?
If you're not getting import autocomplete in your IDE, you may need to include the styled-system
directory in your
tsconfig.json file.
HMR does not work when I use tsconfig
paths?
Panda tries to automatically infer and read the custom paths defined in tsconfig.json
file. However, there might be
scenarios where the hot module replacement doesn't work.
To fix this add the importMap
option to your panda.config.js
file, setting it's value to the specified paths
in
your tsconfig.json
file.
// tsconfig.json
{
"compilerOptions": {
"baseUrl": "./src",
"paths": {
"@my-path/*": ["./styled-system/*"]
}
}
}
// panda.config.js
module.exports = {
importMap: '@my-path'
}
This will ensure that the paths are resolved correctly, and HMR works as expected.
The postcss plugin sometimes seems slow or runs too frequently
This is mostly specific to the host bundler (vite
, webpack
etc) you're using, it is up to them to decide when to run
the postcss plugin again, and sometimes it can be more than needed for your usage. We do our best to cache the results
of the postcss plugin by checking if the filesystem or your config have actually changed, but sometimes it might not be
enough.
In those rare cases, you might want to swap to using the CLI instead, as it will always be more performant than the postcss alternative since we directly watch for filesystem changes and only run the extract/codegen steps when needed.
If you want to keep the convenience of having just one command to run, you can use something like concurrently
for
that:
{
"scripts": {
"dev": "concurrently \"next dev\" \"panda --watch\""
}
}