refactor: standardize errors

Author: segunadebayo

.changeset/consistent-error-handling.md

@@ -0,0 +1,12 @@
+---
+'@pandacss/types': patch
+'@pandacss/logger': patch
+'@pandacss/shared': patch
+'@pandacss/cli': patch
+'@pandacss/core': patch
+'@pandacss/config': patch
+'@pandacss/node': patch
+'@pandacss/generator': patch
+---
+
+Improve error handling architecture across all packages.

packages/cli/src/cli-main.ts

@@ -367,8 +367,9 @@ export async function main() {
         const studioPath = require.resolve('@pandacss/studio', { paths: [cwd] })
         studio = require(studioPath)
       } catch (error) {
-        logger.error('studio', error)
-        throw new PandaError('MISSING_STUDIO', "You need to install '@pandacss/studio' to use this command")
+        throw new PandaError('MISSING_STUDIO', "You need to install '@pandacss/studio' to use this command", {
+          cause: error,
+        })
       }
 
       if (preview) {
@@ -666,20 +667,5 @@ export async function main() {
   cli.version(version)
 
   cli.parse(process.argv, { run: false })
-
-  try {
-    await cli.runMatchedCommand()
-  } catch (error) {
-    if (error instanceof PandaError) {
-      logger.error('cli', error)
-
-      if (logger.isDebug) {
-        console.error(error)
-      }
-
-      process.exit(1)
-    }
-
-    throw error
-  }
+  await cli.runMatchedCommand()
 }

packages/cli/src/errors.ts

@@ -1,18 +1,47 @@
 import { isMainThread, parentPort } from 'worker_threads'
 import colors from 'kleur'
+import { PandaError } from '@pandacss/shared'
 
-export function handleError(error: any) {
-  if (error.loc) {
+export function handleError(error: unknown) {
+  if (error instanceof PandaError) {
+    console.error(colors.red(`${error.code}: ${error.message}`))
+    if (error.hint) {
+      console.error(colors.dim(error.hint))
+    }
+    if (error.cause instanceof Error) {
+      console.error(colors.dim(`Caused by: ${error.cause.message}`))
+    }
+  } else if (isLocError(error)) {
     console.error(colors.bold(colors.red(`Error parsing: ${error.loc.file}:${error.loc.line}:${error.loc.column}`)))
-  }
-  if (error.frame) {
-    console.error(colors.red(error.message))
-    console.error(colors.dim(error.frame))
+    if (error.frame) {
+      console.error(colors.red(error.message))
+      console.error(colors.dim(error.frame))
+    } else {
+      console.error(colors.red(error.message))
+    }
   } else {
-    console.error(colors.red(error.message))
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(colors.red(message))
   }
+
   process.exitCode = 1
   if (!isMainThread && parentPort) {
     parentPort.postMessage('error')
   }
 }
+
+interface LocError {
+  loc: { file: string; line: number; column: number }
+  frame?: string
+  message: string
+}
+
+function isLocError(error: unknown): error is LocError {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'loc' in error &&
+    typeof (error as any).loc === 'object' &&
+    'message' in error
+  )
+}

packages/config/src/merge-hooks.ts

@@ -170,8 +170,7 @@ const tryCatch = (name: string, fn: AnyFunction) => {
     try {
       return fn(...args)
     } catch (e) {
-      logger.error('hooks', `The error below comes from the plugin ${name}`)
-      console.error(e)
+      logger.caughtError('hooks', `Error in plugin "${name}"`, e)
     }
   }
 }

packages/core/src/conditions.ts

@@ -184,7 +184,9 @@ export class Conditions {
     try {
       return parseCondition(condNameOrQuery)
     } catch (error) {
-      logger.error('core:condition', error)
+      const query = typeof condNameOrQuery === 'string' ? condNameOrQuery : JSON.stringify(condNameOrQuery)
+      const message = error instanceof Error ? error.message : String(error)
+      logger.warn('core:condition', `Failed to parse condition "${query}": ${message}`)
     }
   }
 

packages/core/src/stylesheet.ts

@@ -35,6 +35,8 @@ export class Stylesheet {
     } catch (error) {
       if (error instanceof CssSyntaxError) {
         logger.error('sheet:process', error.showSourceCode(true))
+      } else {
+        logger.caughtError('sheet:process', 'Failed to process styles', error)
       }
     }
     return

packages/generator/src/artifacts/css/parser-css.ts

@@ -13,8 +13,8 @@ export const generateParserCss = (ctx: Context, decoder: StyleDecoder) => {
   try {
     const css = sheet.toCss({ minify })
     return css
-  } catch (err) {
-    logger.error('serializer:css', 'Failed to serialize CSS: ' + err)
+  } catch (error) {
+    logger.caughtError('serializer:css', 'Failed to serialize CSS', error)
     return ''
   }
 }

packages/generator/src/artifacts/css/token-css.ts

@@ -123,6 +123,8 @@ const parse = (str: string) => {
   } catch (error) {
     if (error instanceof CssSyntaxError) {
       logger.error('tokens:process', error.showSourceCode(true))
+    } else {
+      logger.caughtError('tokens:process', 'Failed to parse token CSS', error)
     }
   }
 }

packages/logger/src/create-logger.ts

@@ -52,6 +52,14 @@ export const createLogger = (conf: LoggerConfig = {}): LoggerInterface => {
     }
   }
 
+  const caughtError = (type: string, context: string, error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+    logFns.error(type, `${context}: ${message}`)
+    if (error instanceof Error && error.stack) {
+      logFns.debug(type, error.stack)
+    }
+  }
+
   return {
     get level() {
       return level
@@ -63,6 +71,7 @@ export const createLogger = (conf: LoggerConfig = {}): LoggerInterface => {
       onLog = fn
     },
     ...logFns,
+    caughtError,
     print(data: any) {
       console.dir(data, { depth: null, colors: true })
     },

packages/node/src/create-context.ts

@@ -75,7 +75,7 @@ export class PandaContext extends Generator {
       const encoder = styleEncoder || this.parserOptions.encoder
       result = this.project.parseSourceFile(file, encoder)
     } catch (error) {
-      logger.error('file:extract', error)
+      logger.caughtError('file:extract', `Failed to parse ${file}`, error)
     }
 
     measure()