Debugging

bamboo debug

Bamboo'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.

pnpm bamboo debug
# You can also debug a specific file or folder
# using the optional glob argument
pnpm bamboo debug src/components/Button.tsx
pnpm bamboo debug "./src/components/**"

npx bamboo debug
# # You can also debug a specific file or folder
# using the optional glob argument
npx bamboo debug src/components/Button.tsx
npx bamboo debug "./src/components/**"

yarn bamboo debug
# # You can also debug a specific file or folder
# using the optional glob argument
yarn bamboo debug src/components/Button.tsx
yarn bamboo debug "./src/components/**"

bun bamboo debug
# # You can also debug a specific file or folder
# using the optional glob argument
bun bamboo debug src/components/Button.tsx
bun bamboo debug "./src/components/**"

The command also takes:

• --dry – print the debug output to stdout instead of writing it to disk
• --only-config – emit only config.json, skipping the per-file AST and CSS
• --outdir [dir] – where the debug files go, ./styled-system/debug by default
• --silent, -c, --config <path>, --cwd <cwd>, --cpu-prof and --logfile <file>, as on the other commands

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.

BAMBOO_DEBUG env variable

You can prefix any of the Bamboo CLI command with the BAMBOO_DEBUG environment variable to show debug logs.

BAMBOO_DEBUG=* pnpm bamboo

This can be useful to check if a specific file is being processed or not, or if a specific function/component has been extracted.

❯ BAMBOO_DEBUG=* pnpm bamboo cssgen
🎋 debug [config:path] /my-app/bamboo.config.ts
🎋 debug [ast:import] Found import { css } in /my-app/src/theme.tsx
🎋 debug [ast:Icon] { kind: 'component' }
🎋 debug [ast:css] { kind: 'function' }
🎋 debug [hrtime] Parsed /my-app/src/theme.tsx (9.66ms)
🎋 debug [ast:import] Found import { css } in /my-app/src/components/button.tsx
🎋 debug [ast:Button] { kind: 'component' }
🎋 debug [ast:css] { kind: 'function' }
🎋 debug [ast:Anchor] { kind: 'component' }
🎋 debug [hrtime] Parsed /my-app/src/components/button.tsx (4.51ms)
🎋 debug [ast:import] No import found in /my-app/src/constants.ts
🎋 debug [hrtime] Parsed /my-app/src/constants.ts (4.23ms)
🎋 debug [ast:import] Found import { css } in /my-app/src/index.tsx
🎋 debug [ast:css] { kind: 'function' }

Performance profiling

If Bamboo is taking too long to process your files, you can use the --cpu-prof with the bamboo, bamboo cssgen, bamboo codegen and bamboo 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 bamboo-{command}-{timestamp}.cpuprofile file, which can be opened in tools like Speedscope (opens in a new tab). It is written to the directory --cwd resolves to, not to process.cwd(), and the bare command is named cli rather than after a subcommand:

pnpm bamboo --cpu-prof
# → bamboo-cli-20260809T101530123Z.cpuprofile

Which call wrote a rule

Turn on Vite's css.devSourcemap and the dev server serves the stylesheet with a source map to the call that first wrote each rule's atom, which DevTools shows beside the rule. See source maps in development.

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). Bamboo 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 bamboo.config.js file, setting it's value to match the way you import the outdir modules.

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

export default defineConfig({
  importMap: '~/styled-system',
})

This will ensure that the paths are resolved correctly, and HMR works as expected.

The rest of the troubleshooting answers live in the FAQ.