diff --git a/.changeset/little-falcons-unite.md b/.changeset/little-falcons-unite.md new file mode 100644 index 000000000..59479af40 --- /dev/null +++ b/.changeset/little-falcons-unite.md @@ -0,0 +1,10 @@ +--- +'@pandacss/node': patch +'@pandacss/dev': patch +--- + +Add a `--cpu-prof` flag to `panda`, `panda cssgen`, `panda codegen` and `panda debug` commands This is useful for +debugging performance issues in `panda` itself. This will generate a `panda-{command}-{timestamp}.cpuprofile` file in +the current working directory, which can be opened in tools like [Speedscope](https://www.speedscope.app/) + +This is mostly intended for maintainers or can be asked by maintainers to help debug issues. diff --git a/.draft/panda-debug.mdx b/.draft/panda-debug.mdx deleted file mode 100644 index 481a4b8ee..000000000 --- a/.draft/panda-debug.mdx +++ /dev/null @@ -1,105 +0,0 @@ -## CLI Commands - -Panda comes with built-in commands to help you develop and debug your app. - -| Command | Description | -| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`studio`](/docs/references/cli.mdx#panda-studio) | Runs built-in documentation for tokens defined in your project. This will be useful for your team to communicate design decisions in your own way, and share information effectively.
More on that [here](/docs/tokens/02-visualization.mdx). | -| [`analyze`](/docs/references/cli.mdx#panda-analyze) | Analyze design token usage in your project, this will be automatically used by the `studio` command and available in the studio's [Token Analyzer page](/docs/tokens/02-visualization.mdx#token-analyzer) | -| [`debug`](/docs/references/cli.mdx#panda-debug) | Debug design token extraction & css generated from files | - -### Debugging - -Panda comes with a built-in debug command to help you debug your app. This can be useful to understand how Panda is -extracting styles from your code and generating CSS. - -By default it will scan & output debug files for the entire project depending on your `include` and `exclude` options -from your config file. - - - - - ```bash - pnpm panda debug - # You can also debug a specific file or folder - # using the optional glob argument - pnpm panda debug src/components/Button.tsx - pnpm panda debug "./src/components/**" - ``` - - - ```bash - npx panda debug - # # You can also debug a specific file or folder - # using the optional glob argument - npx panda debug src/components/Button.tsx - npx panda debug "./src/components/**" - ``` - - - ```bash - yarn panda debug - # # You can also debug a specific file or folder - # using the optional glob argument - yarn panda debug src/components/Button.tsx - yarn panda debug "./src/components/**" - ``` - - - ```bash - bun panda debug - # # You can also debug a specific file or folder - # using the optional glob argument - bun panda debug src/components/Button.tsx - bun panda debug "./src/components/**" - ``` - - - -This would generate a `debug` folder in your `config.outdir` folder with the following structure: - - - - - - - - - - -`*.ast.json` files will look like: - -```json -[ - { - "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. diff --git a/packages/cli/src/cli-main.ts b/packages/cli/src/cli-main.ts index 7ae6b712a..bcd95fcb1 100644 --- a/packages/cli/src/cli-main.ts +++ b/packages/cli/src/cli-main.ts @@ -12,6 +12,7 @@ import { setupConfig, setupGitIgnore, setupPostcss, + startProfiling, writeAnalyzeJSON, type CssGenOptions, } from '@pandacss/node' @@ -96,11 +97,17 @@ export async function main() { .option('-w, --watch', 'Watch files and rebuild') .option('-p, --poll', 'Use polling instead of filesystem events when watching') .option('--cwd ', 'Current working directory', { default: cwd }) + .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues') .action(async (flags: CodegenCommandFlags) => { const { silent, clean, config: configPath, watch, poll } = flags const cwd = resolve(flags.cwd ?? '') + let stopProfiling: Function = () => void 0 + if (flags.cpuProf) { + stopProfiling = await startProfiling(cwd, 'codegen') + } + if (silent) { logger.level = 'silent' } @@ -126,6 +133,8 @@ export async function main() { { cwd, poll }, ) } + + stopProfiling() }) cli @@ -143,11 +152,17 @@ export async function main() { .option('-p, --poll', 'Use polling instead of filesystem events when watching') .option('-o, --outfile [file]', "Output file for extracted css, default to './styled-system/styles.css'") .option('--cwd ', 'Current working directory', { default: cwd }) + .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues') .action(async (maybeGlob?: string, flags: CssGenCommandFlags = {}) => { const { silent, clean, config: configPath, outfile, watch, poll, minify, minimal, lightningcss } = flags const cwd = resolve(flags.cwd ?? '') + let stopProfiling: Function = () => void 0 + if (flags.cpuProf) { + stopProfiling = await startProfiling(cwd, 'cssgen') + } + const cssArtifact = ['preflight', 'tokens', 'static', 'global', 'keyframes'].find( (type) => type === maybeGlob, ) as CssArtifactType | undefined @@ -206,6 +221,8 @@ export async function main() { } }) } + + stopProfiling() }) cli @@ -223,17 +240,24 @@ export async function main() { .option('--hash', 'Hash the generated classnames to make them shorter') .option('--lightningcss', 'Use `lightningcss` instead of `postcss` for css optimization.') .option('--emitTokensOnly', 'Whether to only emit the `tokens` directory') + .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues') .action(async (files: string[], flags: MainCommandFlags) => { const { config: configPath, silent, ...rest } = flags const cwd = resolve(flags.cwd ?? '') + let stopProfiling: Function = () => void 0 + if (flags.cpuProf) { + stopProfiling = await startProfiling(cwd, 'cli') + } + if (silent) { logger.level = 'silent' } const config = compact({ include: files, ...rest, cwd }) await generate(config, configPath) + stopProfiling() }) cli @@ -330,11 +354,17 @@ export async function main() { .option('--only-config', "Should only output the config file, default to 'false'") .option('-c, --config ', 'Path to panda config file') .option('--cwd ', 'Current working directory', { default: cwd }) + .option('--cpu-prof', 'Generates a `.cpuprofile` to help debug performance issues') .action(async (maybeGlob?: string, flags: DebugCommandFlags = {}) => { const { silent, dry = false, outdir: outdirFlag, config: configPath } = flags ?? {} const cwd = resolve(flags.cwd!) + let stopProfiling: Function = () => void 0 + if (flags.cpuProf) { + stopProfiling = await startProfiling(cwd, 'debug') + } + if (silent) { logger.level = 'silent' } @@ -348,6 +378,7 @@ export async function main() { const outdir = outdirFlag ?? join(...ctx.paths.root, 'debug') await debug(ctx, { outdir, dry, onlyConfig: flags.onlyConfig }) + stopProfiling() }) cli diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts index c4a5b62ec..748614e0f 100644 --- a/packages/cli/src/types.ts +++ b/packages/cli/src/types.ts @@ -20,6 +20,7 @@ export interface CssGenCommandFlags { config?: string minify?: boolean lightningcss?: boolean + cpuProf?: boolean } export interface StudioCommandFlags extends Pick { @@ -45,6 +46,7 @@ export interface DebugCommandFlags { cwd?: string config?: string onlyConfig?: boolean + cpuProf?: boolean } export interface ShipCommandFlags { @@ -61,6 +63,7 @@ export interface CodegenCommandFlags extends Pick { @@ -74,4 +77,5 @@ export interface MainCommandFlags extends Pick hash?: boolean emitTokensOnly?: boolean lightningcss?: boolean + cpuProf?: boolean } diff --git a/packages/node/package.json b/packages/node/package.json index 7237b9761..e80b2fb1d 100644 --- a/packages/node/package.json +++ b/packages/node/package.json @@ -67,7 +67,8 @@ "prettier": "^2.8.8", "ts-morph": "19.0.0", "ts-pattern": "5.0.5", - "tsconfck": "^2.1.2" + "tsconfck": "^2.1.2", + "v8-profiler-next": "^1.10.0" }, "devDependencies": { "@types/fs-extra": "11.0.4", diff --git a/packages/node/src/cpu-profile.ts b/packages/node/src/cpu-profile.ts new file mode 100644 index 000000000..89a13b7a8 --- /dev/null +++ b/packages/node/src/cpu-profile.ts @@ -0,0 +1,33 @@ +import { logger } from '@pandacss/logger' +import fs from 'fs' +import path from 'path' + +export const startProfiling = async (cwd: string, prefix: string) => { + const v8Profiler = (await import('v8-profiler-next')).default + const date = new Date() + const timestamp = date.toISOString().replace(/[-:.]/g, '') + const title = `panda-${prefix}-${timestamp}` + + // set generateType 1 to generate new format for cpuprofile + // to be compatible with cpuprofile parsing in vscode. + v8Profiler.setGenerateType(1) + v8Profiler.startProfiling(title, true) + + const stopProfiling = () => { + const profile = v8Profiler.stopProfiling(title) + profile.export(function (error, result) { + if (error) { + console.error(error) + return + } + if (!result) return + + const outfile = path.join(cwd, `${title}.cpuprofile`) + fs.writeFileSync(outfile, result) + logger.info('cpu-prof', outfile) + profile.delete() + }) + } + + return stopProfiling +} diff --git a/packages/node/src/index.ts b/packages/node/src/index.ts index 980f56df1..3226f919e 100644 --- a/packages/node/src/index.ts +++ b/packages/node/src/index.ts @@ -2,6 +2,7 @@ export { analyzeTokens, writeAnalyzeJSON } from './analyze-tokens' export { buildInfo } from './build-info' export { Builder } from './builder' export { codegen } from './codegen' +export { startProfiling } from './cpu-profile' export { loadConfigAndCreateContext } from './config' export { PandaContext } from './create-context' export { cssgen, type CssGenOptions } from './cssgen' diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6dbd0d73b..d0514e00c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -528,6 +528,9 @@ importers: tsconfck: specifier: ^2.1.2 version: 2.1.2(typescript@5.3.3) + v8-profiler-next: + specifier: ^1.10.0 + version: 1.10.0 devDependencies: '@types/fs-extra': specifier: 11.0.4 @@ -6416,6 +6419,10 @@ packages: resolution: {integrity: sha512-OfX7E2oUDYxtBvsuS4e/jSn4Q9Qb6DzgeYtsAdkPZ47znpoNsMgZw0+tVijiv3uGNR6dgNlty6r9rzIzHjtd/A==} dev: false + /@gar/promisify@1.1.3: + resolution: {integrity: sha512-k2Ty1JcVojjJFwrg/ThKi2ujJ7XNLYaFGNB/bWT9wGR+oSMJHMa5w+CUq6p/pVrKeNNgA7pCqEcjSnHVoqJQFw==} + dev: false + /@gatsbyjs/parcel-namer-relative-to-cwd@2.11.0(@parcel/core@2.8.3): resolution: {integrity: sha512-Iniqvn2uREkyf6LC4Ge0NQE9EeVbACqDSFn2Fl4brl4obwcubwWxVyB4fof34r8yG7YuDIPWeyT6iuRocGqp8w==} engines: {node: '>=18.0.0', parcel: 2.x} @@ -7583,6 +7590,14 @@ packages: '@nodelib/fs.scandir': 2.1.5 fastq: 1.15.0 + /@npmcli/fs@2.1.2: + resolution: {integrity: sha512-yOJKRvohFOaLqipNtwYB9WugyZKhC/DZC4VYPmpaCzDBrA8YpK3qHZ8/HGscMnE4GqbkLNuVcCnxkeQEdGt6LQ==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + '@gar/promisify': 1.1.3 + semver: 7.5.4 + dev: false + /@npmcli/fs@3.1.0: resolution: {integrity: sha512-7kZUAaLscfgbwBQRbvdMYaZOWyMEcPTH/tJjnyAWJ/dvvs9Ef+CERx/qJb9GExJpl1qipaDGn7KqHnFGGixd0w==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -7606,6 +7621,15 @@ packages: - bluebird dev: true + /@npmcli/move-file@2.0.1: + resolution: {integrity: sha512-mJd2Z5TjYWq/ttPLLGqArdtnC74J6bOzg4rMDnN+p1xTacZ2yPRCk2y0oSWQtygLR9YVQXgOcONrwtnk3JupxQ==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + deprecated: This functionality has been moved to @npmcli/fs + dependencies: + mkdirp: 1.0.4 + rimraf: 3.0.2 + dev: false + /@npmcli/package-json@4.0.1: resolution: {integrity: sha512-lRCEGdHZomFsURroh522YvA/2cVb9oPIJrjHanCJZkiasz1BzcnLr3tBJhlV7S86MBJBuAQ33is2D60YitZL2Q==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -9981,7 +10005,7 @@ packages: find-cache-dir: 3.3.2 find-up: 5.0.0 fs-extra: 11.1.1 - glob: 10.2.7 + glob: 10.3.10 handlebars: 4.7.7 lazy-universal-dotenv: 4.0.0 node-fetch: 2.6.11 @@ -12304,6 +12328,26 @@ packages: '@webassemblyjs/ast': 1.11.6 '@xtuc/long': 4.2.2 + /@xprofiler/node-pre-gyp@1.0.11: + resolution: {integrity: sha512-kNFT4XscrA+Hjh+jSHs49PiG/YGf08a6eNDo16qjSnCaT4B5ngrKDcNtEJ6CnS0sDP/1oZmHCBYECB6wGKP7lg==} + hasBin: true + dependencies: + detect-libc: 1.0.3 + https-proxy-agent: 5.0.1 + make-dir: 3.1.0 + node-fetch: 2.6.11 + node-gyp: 9.3.1 + nopt: 5.0.0 + npmlog: 5.0.1 + rimraf: 3.0.2 + semver: 7.5.4 + tar: 6.1.15 + transitivePeerDependencies: + - bluebird + - encoding + - supports-color + dev: false + /@xtuc/ieee754@1.2.0: resolution: {integrity: sha512-DX8nKgqcGwsc0eJSqYt5lwP4DH5FlHnmuWWBRy7X0NcaGR0ZtuyeESgMwTYVEtxmsNGY+qit4QYT/MIYTOTPeA==} @@ -13419,7 +13463,6 @@ packages: /abbrev@1.1.1: resolution: {integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==} - dev: true /abort-controller@3.0.0: resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==} @@ -13521,6 +13564,13 @@ packages: transitivePeerDependencies: - supports-color + /agentkeepalive@4.5.0: + resolution: {integrity: sha512-5GG/5IbQQpC9FpkRGsSvZI5QYeSCzlJHdpBQntCsuTOxhKD8lqKhrleg2Yi7yvMIf82Ycmmqln9U8V9qwEiJew==} + engines: {node: '>= 8.0.0'} + dependencies: + humanize-ms: 1.2.1 + dev: false + /aggregate-error@3.1.0: resolution: {integrity: sha512-4I7Td01quW/RpocfNayFdFVk1qSuoh0E7JrbRJ16nH01HhKFQ88INq9Sd+nd72zqRySlr9BmDA8xlEJ6vJMrYA==} engines: {node: '>=8'} @@ -13671,7 +13721,6 @@ packages: /aproba@2.0.0: resolution: {integrity: sha512-lYe4Gx7QT+MKGbDsA+Z+he/Wtef0BiwDOlK/XkBrdfsh9J/jPPXbX0tE9x9cl27Tmu5gg3QUbUrQYa/y+KOHPQ==} - dev: true /arch@2.2.0: resolution: {integrity: sha512-Of/R0wqp83cgHozfIYLbBMnej79U/SVGOOyuB3VVFv1NRM/PSFMK12x9KVtiYzJqmnU5WR2qp0Z5rHb7sWGnFQ==} @@ -13711,7 +13760,14 @@ packages: dependencies: delegates: 1.0.0 readable-stream: 3.6.2 - dev: true + + /are-we-there-yet@3.0.1: + resolution: {integrity: sha512-QZW4EDmGwlYur0Yyf/b2uGucHQMa8aFUP7eu9ddR73vvhFyt4V0Vl3QHPcTNJ8l6qYOBdxgXdnBXQrHilfRQBg==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + delegates: 1.0.0 + readable-stream: 3.6.2 + dev: false /arg@1.0.0: resolution: {integrity: sha512-Wk7TEzl1KqvTGs/uyhmHO/3XLd3t1UeU4IstvPXVzGPM522cTjqjNZ99esCkcL52sjqjo8e8CTBcWhkxvGzoAw==} @@ -14814,6 +14870,32 @@ packages: resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==} engines: {node: '>=8'} + /cacache@16.1.3: + resolution: {integrity: sha512-/+Emcj9DAXxX4cwlLmRI9c166RuL3w30zp4R7Joiv2cQTtTtA+jeuCAjH3ZlGnYS3tKENSrKhAzVVP9GVyzeYQ==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + '@npmcli/fs': 2.1.2 + '@npmcli/move-file': 2.0.1 + chownr: 2.0.0 + fs-minipass: 2.1.0 + glob: 8.1.0 + infer-owner: 1.0.4 + lru-cache: 7.18.3 + minipass: 3.3.6 + minipass-collect: 1.0.2 + minipass-flush: 1.0.5 + minipass-pipeline: 1.2.4 + mkdirp: 1.0.4 + p-map: 4.0.0 + promise-inflight: 1.0.1 + rimraf: 3.0.2 + ssri: 9.0.1 + tar: 6.1.15 + unique-filename: 2.0.1 + transitivePeerDependencies: + - bluebird + dev: false + /cacache@17.1.4: resolution: {integrity: sha512-/aJwG2l3ZMJ1xNAnqbMpA40of9dj/pIH3QfiuQSqjfPJF747VR0J/bHn+/KdNnHKc6XQcWt/AfRSBft82W1d2A==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -15101,7 +15183,6 @@ packages: /chownr@2.0.0: resolution: {integrity: sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==} engines: {node: '>=10'} - dev: true /chrome-trace-event@1.0.3: resolution: {integrity: sha512-p3KULyQg4S7NIHixdwbGX+nFHkoBiA4YQmyWtjb8XngSKV124nJmRysgAeujbUVb15vh+RvFUfCPqU7rXk+hZg==} @@ -15329,7 +15410,6 @@ packages: /color-support@1.1.3: resolution: {integrity: sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==} hasBin: true - dev: true /color@4.2.3: resolution: {integrity: sha512-1rXeuUUiGGrykh+CeBdu5Ie7OJwinCgQY0bc7GCRxy5xVHy+moaqkpL/jqQq0MtQOeYcrqEz4abc5f0KtU7W4A==} @@ -15507,7 +15587,6 @@ packages: /console-control-strings@1.1.0: resolution: {integrity: sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==} - dev: true /constant-case@3.0.4: resolution: {integrity: sha512-I2hSBi7Vvs7BEuJDr5dDHfzb/Ruj3FyvFyh7KLilAjNQw3Be+xgqUBA2W6scVEcL0hL1dwPRtIqEPVUCKkSsyQ==} @@ -16591,7 +16670,6 @@ packages: /delegates@1.0.0: resolution: {integrity: sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==} - dev: true /denque@2.1.0: resolution: {integrity: sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==} @@ -16940,6 +17018,14 @@ packages: resolution: {integrity: sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w==} engines: {node: '>= 0.8'} + /encoding@0.1.13: + resolution: {integrity: sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==} + requiresBuild: true + dependencies: + iconv-lite: 0.6.3 + dev: false + optional: true + /end-of-stream@1.4.4: resolution: {integrity: sha512-+uw1inIHVPQoaVuHzRyXd21icM+cnt4CzD5rW+NC1wjOUSTOs+Te7FOv7AhN7vS9x/oIyhLP5PR1H+phQAHu5Q==} dependencies: @@ -17026,6 +17112,11 @@ packages: resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} engines: {node: '>=0.12'} + /env-paths@2.2.1: + resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==} + engines: {node: '>=6'} + dev: false + /envinfo@7.8.1: resolution: {integrity: sha512-/o+BXHmB7ocbHEAs6F2EnG0ogybVVUdkRunTT2glZU9XAaGmhqskrvKwqXuDfNjEO0LZKWdejEEpnq8aM0tOaw==} engines: {node: '>=4'} @@ -17037,7 +17128,6 @@ packages: /err-code@2.0.3: resolution: {integrity: sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA==} - dev: true /errno@0.1.8: resolution: {integrity: sha512-dJ6oBr5SQ1VSd9qkk7ByRgb/1SH4JZjCHSW/mr63/QcXO9zLVxvJ6Oy13nio03rxpSnVDDjFor75SjVeZWPW/A==} @@ -18923,7 +19013,6 @@ packages: engines: {node: '>= 8'} dependencies: minipass: 3.3.6 - dev: true /fs-minipass@3.0.3: resolution: {integrity: sha512-XUBA9XClHbnJWSfBzjkm6RvPsyg3sryZt06BEQoXcF7EK/xpGaQYJgQKDJSUH5SGZ76Y7pFx1QBnXz09rU5Fbw==} @@ -19463,7 +19552,20 @@ packages: string-width: 4.2.3 strip-ansi: 6.0.1 wide-align: 1.1.5 - dev: true + + /gauge@4.0.4: + resolution: {integrity: sha512-f9m+BEN5jkg6a0fZjleidjN51VE1X+mPFQ2DJ0uv1V39oCLCbsGe6yjbBnp7eK7z/+GAon99a3nHuqbuuthyPg==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + aproba: 2.0.0 + color-support: 1.1.3 + console-control-strings: 1.1.0 + has-unicode: 2.0.1 + signal-exit: 3.0.7 + string-width: 4.2.3 + strip-ansi: 6.0.1 + wide-align: 1.1.5 + dev: false /generic-names@4.0.0: resolution: {integrity: sha512-ySFolZQfw9FoDb3ed9d80Cm9f0+r7qj+HJkWjeD9RBfpxEVTlVhol+gvaQB/78WbwYfbnNh8nWHHBSlg072y6A==} @@ -19636,6 +19738,7 @@ packages: minimatch: 9.0.1 minipass: 5.0.0 path-scurry: 1.9.2 + dev: false /glob@10.3.10: resolution: {integrity: sha512-fa46+tv1Ak0UPK1TOy/pZrIybNNt4HCv7SDzwyfiOZkvZLEbjsZkJBPtDHVshZjbecAoAGSC20MjLDG/qr679g==} @@ -19677,7 +19780,6 @@ packages: inherits: 2.0.4 minimatch: 5.1.6 once: 1.4.0 - dev: true /global-dirs@3.0.1: resolution: {integrity: sha512-NBcGGFbBA9s1VzD41QXDG+3++t9Mn5t1FpLdhESY6oKY4gYTFpX4wO3sqGUa0Srjtbfj3szX0RnemmrVRUdULA==} @@ -19945,7 +20047,6 @@ packages: /has-unicode@2.0.1: resolution: {integrity: sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==} - dev: true /has-yarn@3.0.0: resolution: {integrity: sha512-IrsVwUHhEULx3R8f/aA8AHuEzAorplsab/v8HBzEiIukwq5i/EC+xmOW+HfP1OaDP+2JkgT1yILHN2O3UFIbcA==} @@ -20395,6 +20496,12 @@ packages: resolution: {integrity: sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==} engines: {node: '>=16.17.0'} + /humanize-ms@1.2.1: + resolution: {integrity: sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==} + dependencies: + ms: 2.1.3 + dev: false + /husky@8.0.3: resolution: {integrity: sha512-+dQSyqPh4x1hlO1swXBiNb2HzTDN1I2IGLQx1GrBuiqFJfoMrnZWwVmatvSiO+Iz8fBUnf+lekwNo4c2LlXItg==} engines: {node: '>=14'} @@ -20485,6 +20592,10 @@ packages: resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==} engines: {node: '>=8'} + /infer-owner@1.0.4: + resolution: {integrity: sha512-IClj+Xz94+d7irH5qRyfJonOdfTzuDaifE6ZPWfx0N0+/ATZCbuTPq2prFl526urkQd90WyUKIh1DfBQ2hMz9A==} + dev: false + /inflight@1.0.6: resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==} dependencies: @@ -20570,7 +20681,6 @@ packages: /ip@2.0.0: resolution: {integrity: sha512-WKa+XuLG1A1R0UWhl2+1XQSi+fZWMsYKffMZTTYsiZaUD8k2yDAj5atimTUD2TZkyCkNEeYE5NhFZmupOGtjYQ==} - dev: true /ipaddr.js@1.9.1: resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==} @@ -20806,6 +20916,10 @@ packages: is-glob: 2.0.1 dev: false + /is-lambda@1.0.1: + resolution: {integrity: sha512-z7CMFGNrENq5iFB9Bqo64Xk6Y9sg+epq1myIcdHaGnbMTYOxvzsEtdYqQUylB7LxfkvgrrjP32T6Ywciio9UIQ==} + dev: false + /is-lower-case@2.0.2: resolution: {integrity: sha512-bVcMJy4X5Og6VZfdOZstSexlEy20Sr0k/p/b2IlQJlfdKAQuMpiv5w2Ccxb8sKdRUNAG1PnHVHjFSdRDVS6NlQ==} dependencies: @@ -21166,6 +21280,7 @@ packages: '@isaacs/cliui': 8.0.2 optionalDependencies: '@pkgjs/parseargs': 0.11.0 + dev: false /jackspeak@2.3.6: resolution: {integrity: sha512-N3yCS/NegsOBokc8GAdM8UcmfsKiSS8cipheD/nivzr700H+nsMOxJjQnvwOcRYVuFkdH0wGUvW2WbXGmrZGbQ==} @@ -22054,11 +22169,11 @@ packages: /lru-cache@7.18.3: resolution: {integrity: sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==} engines: {node: '>=12'} - dev: true /lru-cache@9.1.2: resolution: {integrity: sha512-ERJq3FOzJTxBbFjZ7iDs+NiK4VI9Wz+RdrrAB8dio1oV+YvdPzUEE4QNiT2VD51DkIbCYRUUzCRkssXCHqSnKQ==} engines: {node: 14 || >=16.14} + dev: false /lru-queue@0.1.0: resolution: {integrity: sha512-BpdYkt9EvGl8OfWHDQPISVpcl5xZthb+XPsbELj5AQXxIC8IriDZIQYjBJPEm5rS420sjZ0TLEzRcq5KdBhYrQ==} @@ -22105,6 +22220,31 @@ packages: dependencies: semver: 6.3.1 + /make-fetch-happen@10.2.1: + resolution: {integrity: sha512-NgOPbRiaQM10DYXvN3/hhGVI2M5MtITFryzBGxHM5p4wnFxsVCbxkrBrDsk+EZ5OB4jEOT7AjDxtdF+KVEFT7w==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + agentkeepalive: 4.5.0 + cacache: 16.1.3 + http-cache-semantics: 4.1.1 + http-proxy-agent: 5.0.0 + https-proxy-agent: 5.0.1 + is-lambda: 1.0.1 + lru-cache: 7.18.3 + minipass: 3.3.6 + minipass-collect: 1.0.2 + minipass-fetch: 2.1.2 + minipass-flush: 1.0.5 + minipass-pipeline: 1.2.4 + negotiator: 0.6.3 + promise-retry: 2.0.1 + socks-proxy-agent: 7.0.0 + ssri: 9.0.1 + transitivePeerDependencies: + - bluebird + - supports-color + dev: false + /makeerror@1.0.12: resolution: {integrity: sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==} dependencies: @@ -23326,7 +23466,6 @@ packages: engines: {node: '>=10'} dependencies: brace-expansion: 2.0.1 - dev: true /minimatch@7.4.6: resolution: {integrity: sha512-sBz8G/YjVniEz6lKPNpKxXwazJe4c19fEfV2GDMX6AjFz+MX9uDWIZW8XreVhkFW3fkIdTv/gxWr/Kks5FFAVw==} @@ -23358,28 +23497,42 @@ packages: engines: {node: '>= 8'} dependencies: minipass: 3.3.6 - dev: true + + /minipass-fetch@2.1.2: + resolution: {integrity: sha512-LT49Zi2/WMROHYoqGgdlQIZh8mLPZmOrN2NdJjMXxYe4nkN6FUyuPuOAOedNJDrx0IRGg9+4guZewtp8hE6TxA==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + minipass: 3.3.6 + minipass-sized: 1.0.3 + minizlib: 2.1.2 + optionalDependencies: + encoding: 0.1.13 + dev: false /minipass-flush@1.0.5: resolution: {integrity: sha512-JmQSYYpPUqX5Jyn1mXaRwOda1uQ8HP5KAT/oDSLCzt1BYRhQU0/hDtsB1ufZfEEzMZ9aAVmsBw8+FWsIXlClWw==} engines: {node: '>= 8'} dependencies: minipass: 3.3.6 - dev: true /minipass-pipeline@1.2.4: resolution: {integrity: sha512-xuIq7cIOt09RPRJ19gdi4b+RiNvDFYe5JH+ggNvBqGqpQXcru3PcRmOZuHBKWK1Txf9+cQ+HMVN4d6z46LZP7A==} engines: {node: '>=8'} dependencies: minipass: 3.3.6 - dev: true + + /minipass-sized@1.0.3: + resolution: {integrity: sha512-MbkQQ2CTiBMlA2Dm/5cY+9SWFEN8pzzOXi6rlM5Xxq0Yqbda5ZQy9sU75a673FE9ZK0Zsbr6Y5iP6u9nktfg2g==} + engines: {node: '>=8'} + dependencies: + minipass: 3.3.6 + dev: false /minipass@3.3.6: resolution: {integrity: sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==} engines: {node: '>=8'} dependencies: yallist: 4.0.0 - dev: true /minipass@5.0.0: resolution: {integrity: sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==} @@ -23395,7 +23548,6 @@ packages: dependencies: minipass: 3.3.6 yallist: 4.0.0 - dev: true /mitt@1.2.0: resolution: {integrity: sha512-r6lj77KlwqLhIUku9UWYes7KJtsczvolZkzp8hbaDPPaE24OmWl5s539Mytlj22siEQKosZ26qCBgda2PKwoJw==} @@ -23419,7 +23571,6 @@ packages: resolution: {integrity: sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==} engines: {node: '>=10'} hasBin: true - dev: true /mkdirp@2.1.6: resolution: {integrity: sha512-+hEnITedc8LAtIP9u3HJDFIdcLV2vXP33sqLLIzkv1Db1zO/1OxbvYf0Y1OC/S/Qo5dxHXepofhmxL02PsKe+A==} @@ -23535,6 +23686,10 @@ packages: thenify-all: 1.6.0 dev: false + /nan@2.18.0: + resolution: {integrity: sha512-W7tfG7vMOGtD30sHoZSSc/JVYiyDPEyQVso/Zz+/uQd0B0L46gtC+pHha5FFMRpil6fm/AoEcRWyOVi4+E/f8w==} + dev: false + /nanoid@3.3.7: resolution: {integrity: sha512-eSRppjcPIatRIMC1U6UngP8XFcz8MQWGQdt1MTBQ7NaAmvXDfvNxbvWV3x2y6CdEUciCSsDHDQZbhYaB8QEo2g==} engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} @@ -23911,6 +24066,26 @@ packages: resolution: {integrity: sha512-NTZVKn9IylLwUzaKjkas1e4u2DLNcV4rdYagA4PWdPwW87Bi7z+BznyKSRwS/761tV/lzCGXplWsiaMjLqP2zQ==} hasBin: true + /node-gyp@9.3.1: + resolution: {integrity: sha512-4Q16ZCqq3g8awk6UplT7AuxQ35XN4R/yf/+wSAwcBUAjg7l58RTactWaP8fIDTi0FzI7YcVLujwExakZlfWkXg==} + engines: {node: ^12.13 || ^14.13 || >=16} + hasBin: true + dependencies: + env-paths: 2.2.1 + glob: 7.2.3 + graceful-fs: 4.2.11 + make-fetch-happen: 10.2.1 + nopt: 6.0.0 + npmlog: 6.0.2 + rimraf: 3.0.2 + semver: 7.5.4 + tar: 6.1.15 + which: 2.0.2 + transitivePeerDependencies: + - bluebird + - supports-color + dev: false + /node-html-parser@5.4.2: resolution: {integrity: sha512-RaBPP3+51hPne/OolXxcz89iYvQvKOydaqoePpOgXcrOKZhjVIzmpKZz+Hd/RBO2/zN2q6CNJhQzucVz+u3Jyw==} dependencies: @@ -23939,7 +24114,6 @@ packages: hasBin: true dependencies: abbrev: 1.1.1 - dev: true /nopt@6.0.0: resolution: {integrity: sha512-ZwLpbTgdhuZUnZzjd7nb1ZV+4DoiC6/sfiVKok72ym/4Tlf+DFdlHYmT2JPmcNNWV6Pi3SDf1kT+A4r9RTuT9g==} @@ -23947,7 +24121,6 @@ packages: hasBin: true dependencies: abbrev: 1.1.1 - dev: true /normalize-package-data@2.5.0: resolution: {integrity: sha512-/5CMN3T0R4XTj4DcGaexo+roZSdSFW/0AOOTROrjxzCG1wrWXEsGbRKevjlIL+ZDE4sZlJr5ED4YW0yqmkK+eA==} @@ -24054,7 +24227,16 @@ packages: console-control-strings: 1.1.0 gauge: 3.0.2 set-blocking: 2.0.0 - dev: true + + /npmlog@6.0.2: + resolution: {integrity: sha512-/vBvz5Jfr9dT/aFWd0FIRf+T/Q2WBsLENygUaFUqstqsycmZAP/t5BvFJTK0viFmSUxiUKTUplWy5vt+rvKIxg==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + are-we-there-yet: 3.0.1 + console-control-strings: 1.1.0 + gauge: 4.0.4 + set-blocking: 2.0.0 + dev: false /nth-check@2.1.1: resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==} @@ -24739,6 +24921,7 @@ packages: dependencies: lru-cache: 9.1.2 minipass: 5.0.0 + dev: false /path-to-regexp@0.1.7: resolution: {integrity: sha512-5DFkuoqlv1uYQKxy8omFBeJPQcdoE07Kv2sferDCrAq1ohOU+MSDswDIbnx3YAM60qIOnYa53wBhXW0EbMonrQ==} @@ -25854,7 +26037,6 @@ packages: peerDependenciesMeta: bluebird: optional: true - dev: true /promise-retry@2.0.1: resolution: {integrity: sha512-y+WKFlBR8BGXnsNlIHFGPZmyDf3DFMoLhaflAnyZgV6rG6xu+JwesTo2Q9R6XwYmtmwAFCkAk3e35jEdoeh/3g==} @@ -25862,7 +26044,6 @@ packages: dependencies: err-code: 2.0.3 retry: 0.12.0 - dev: true /promise@7.3.1: resolution: {integrity: sha512-nolQXZ/4L+bP/UGlkfaIujX9BKxGwmQ9OT4mOt5yvy8iK1h3wqTEJCijzGANTCCl9nWjY41juyAn2K3Q1hLLTg==} @@ -27648,6 +27829,11 @@ packages: engines: {node: '>=8.0.0'} dev: false + /smart-buffer@4.2.0: + resolution: {integrity: sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==} + engines: {node: '>= 6.0.0', npm: '>= 3.0.0'} + dev: false + /smartwrap@2.0.2: resolution: {integrity: sha512-vCsKNQxb7PnCNd2wY1WClWifAc2lwqsG8OaswpJkVJsvMGcnEntdTCDajZCkk93Ay1U3t/9puJmb525Rg5MZBA==} engines: {node: '>=6'} @@ -27721,6 +27907,25 @@ packages: - utf-8-validate dev: false + /socks-proxy-agent@7.0.0: + resolution: {integrity: sha512-Fgl0YPZ902wEsAyiQ+idGd1A7rSFx/ayC1CQVMw5P+EQx2V0SgpGtf6OKFhVjPflPUl9YMmEOnmfjCdMUsygww==} + engines: {node: '>= 10'} + dependencies: + agent-base: 6.0.2 + debug: 4.3.4 + socks: 2.7.1 + transitivePeerDependencies: + - supports-color + dev: false + + /socks@2.7.1: + resolution: {integrity: sha512-7maUZy1N7uo6+WVEX6psASxtNlKaNVMlGQKkG/63nEDdLOWNbiUMoLK7X4uYoLhQstau72mLgfEWcXcwsaHbYQ==} + engines: {node: '>= 10.13.0', npm: '>= 3.0.0'} + dependencies: + ip: 2.0.0 + smart-buffer: 4.2.0 + dev: false + /solid-js@1.7.11: resolution: {integrity: sha512-JkuvsHt8jqy7USsy9xJtT18aF9r2pFO+GB8JQ2XGTvtF49rGTObB46iebD25sE3qVNvIbwglXOXdALnJq9IHtQ==} dependencies: @@ -27907,6 +28112,13 @@ packages: minipass: 7.0.4 dev: true + /ssri@9.0.1: + resolution: {integrity: sha512-o57Wcn66jMQvfHG1FlYbWeZWW/dHZhJXjpIcTfXldXEk5nz5lStPo3mK0OJQfGR3RbZUlbISexbljkJzuEj/8Q==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + minipass: 3.3.6 + dev: false + /stable@0.1.8: resolution: {integrity: sha512-ji9qxRnOVfcuLDySj9qzhGSEFVobyt1kIOSkj1qZzYLzq7Tos/oUUWvotUPQLlrsidqsK6tBH89Bc9kL5zHA6w==} deprecated: 'Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#browser_compatibility' @@ -28557,7 +28769,6 @@ packages: minizlib: 2.1.2 mkdirp: 1.0.4 yallist: 4.0.0 - dev: true /telejson@7.1.0: resolution: {integrity: sha512-jFJO4P5gPebZAERPkJsqMAQ0IMA1Hi0AoSfxpnUaV6j6R2SZqlpkbS20U6dEUtA3RUYt2Ak/mTlkQzHH9Rv/hA==} @@ -29376,6 +29587,13 @@ packages: - rollup dev: true + /unique-filename@2.0.1: + resolution: {integrity: sha512-ODWHtkkdx3IAR+veKxFV+VBkUMcN+FaqzUUd7IZzt+0zhDZFPFxhlqwPF3YQvMHx1TD0tdgYl+kuPnJ8E6ql7A==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + unique-slug: 3.0.0 + dev: false + /unique-filename@3.0.0: resolution: {integrity: sha512-afXhuC55wkAmZ0P18QsVE6kp8JaxrEokN2HGIoIVv2ijHQd419H0+6EigAFcIzXeMIkcIkNBpB3L/DXB3cTS/g==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -29383,6 +29601,13 @@ packages: unique-slug: 4.0.0 dev: true + /unique-slug@3.0.0: + resolution: {integrity: sha512-8EyMynh679x/0gqE9fT9oilG+qEt+ibFyqjuVTsZn1+CMxH+XLlpvr2UZx4nVcCwTpx81nICr2JQFkM+HPLq4w==} + engines: {node: ^12.13.0 || ^14.15.0 || >=16.0.0} + dependencies: + imurmurhash: 0.1.4 + dev: false + /unique-slug@4.0.0: resolution: {integrity: sha512-WrcA6AyEfqDX5bWige/4NQfPZMtASNVxdmWR76WESYQVAACSgWcR6e9i0mofqqBxYFtL4oAxPIptY73/0YE1DQ==} engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0} @@ -29883,6 +30108,18 @@ packages: resolution: {integrity: sha512-l8lCEmLcLYZh4nbunNZvQCJc5pv7+RCwa8q/LdUx8u7lsWvPDKmpodJAJNwkAhJC//dFY48KuIEmjtd4RViDrA==} dev: false + /v8-profiler-next@1.10.0: + resolution: {integrity: sha512-HME7CR3V8gkBEAutcMyGS0vK0XH2hFQhF5SvSdrF/mdjWIGoaiY+WH3RpY7ePY7J7vNDbQfP+Ikefdi1z/mJXg==} + requiresBuild: true + dependencies: + '@xprofiler/node-pre-gyp': 1.0.11 + nan: 2.18.0 + transitivePeerDependencies: + - bluebird + - encoding + - supports-color + dev: false + /v8-to-istanbul@9.1.0: resolution: {integrity: sha512-6z3GW9x8G1gd+JIIgQQQxXuiJtCXeAjp6RaPEPLv62mH3iPHPxV6W3robxtCzNErRo6ZwTmzWhsbNvjyEBKzKA==} engines: {node: '>=10.12.0'} @@ -30998,7 +31235,6 @@ packages: resolution: {integrity: sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==} dependencies: string-width: 4.2.3 - dev: true /widest-line@3.1.0: resolution: {integrity: sha512-NsmoXalsWVDMGupxZ5R08ka9flZjjiLvHVAWYOKtiKM8ujtZWr9cRffak+uSE48+Ob8ObalXpwyeUiyDD6QFgg==} diff --git a/website/pages/docs/guides/_meta.json b/website/pages/docs/guides/_meta.json index a473b0d27..ed4409ed6 100644 --- a/website/pages/docs/guides/_meta.json +++ b/website/pages/docs/guides/_meta.json @@ -4,5 +4,6 @@ "multiple-themes": "Multiple Themes", "fonts": "Custom Fonts", "dynamic-styling": "Dynamic Styles", - "static": "Static Generator" + "static": "Static Generator", + "debugging": "Debugging" } diff --git a/website/pages/docs/guides/debugging.mdx b/website/pages/docs/guides/debugging.mdx new file mode 100644 index 000000000..22891d9b0 --- /dev/null +++ b/website/pages/docs/guides/debugging.mdx @@ -0,0 +1,199 @@ +--- +title: Debugging +description: How can I debug my styles or profile the extraction process? +--- + +# Debugging + +## panda debug + +Panda comes with a built-in debug command to help you debug your app. This can be useful to see which files are being processed, what styles are being generated for each of your source files, and what your final config looks like. + +By default it will scan and output debug files for the entire project depending on your `include` and `exclude` options +from your config file. + + + + + ```bash + pnpm panda debug + # You can also debug a specific file or folder + # using the optional glob argument + pnpm panda debug src/components/Button.tsx + pnpm panda debug "./src/components/**" + ``` + + + ```bash + npx panda debug + # # You can also debug a specific file or folder + # using the optional glob argument + npx panda debug src/components/Button.tsx + npx panda debug "./src/components/**" + ``` + + + ```bash + yarn panda debug + # # You can also debug a specific file or folder + # using the optional glob argument + yarn panda debug src/components/Button.tsx + yarn panda debug "./src/components/**" + ``` + + + ```bash + bun panda debug + # # You can also debug a specific file or folder + # using the optional glob argument + bun panda debug src/components/Button.tsx + bun panda debug "./src/components/**" + ``` + + + +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: + +```json +[ + { + "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. + +```bash +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](https://www.speedscope.app/) + +```bash +pnpm panda --cpu-prof +``` + +## FAQ + +### Why are my styles not applied? + +Check that the [`@layer` rules](/docs/concepts/cascade-layers#layer-css) are set and the corresponding `.css` file is included. [If you're not using `postcss`](/docs/installation/cli), ensure that `styled-system/styles.css` is imported and that the `panda` command has been run (or is running with `--watch`). + +--- + +### 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](https://github.com/chakra-ui/panda/issues) or in the [discord](https://discord.gg/VQrkpsgSx7). If you can't find it, please create a minimal reproduction and submit [a new github issue](https://github.com/chakra-ui/panda/issues/new/choose) 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. + +```json +// tsconfig.json + +{ + "compilerOptions": { + "baseUrl": "./src", + "paths": { + "@my-path/*": ["./styled-system/*"] + } + } +} +``` + +```js +// panda.config.js + +module.exports = { + importMap: '@my-path' +} +``` + +This will ensure that the paths are resolved correctly, and HMR works as expected. + +---